Doc/lib/libsunaudio.tex

   1 \section{\module{sunaudiodev} ---
   2          Access to Sun audio hardware}
   3
   4 \declaremodule{builtin}{sunaudiodev}
   5   \platform{SunOS}
   6 \modulesynopsis{Access to Sun audio hardware.}
   7
   8
   9 This module allows you to access the Sun audio interface. The Sun
  10 audio hardware is capable of recording and playing back audio data
  11 in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A
  12 full description can be found in the \manpage{audio}{7I} manual page.
  13
  14 The module
  15 \refmodule[sunaudiodev-constants]{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}
  16 defines constants which may be used with this module.
  17
  18 This module defines the following variables and functions:
  19
  20 \begin{excdesc}{error}
  21 This exception is raised on all errors. The argument is a string
  22 describing what went wrong.
  23 \end{excdesc}
  24
  25 \begin{funcdesc}{open}{mode}
  26 This function opens the audio device and returns a Sun audio device
  27 object. This object can then be used to do I/O on. The \var{mode} parameter
  28 is one of \code{'r'} for record-only access, \code{'w'} for play-only
  29 access, \code{'rw'} for both and \code{'control'} for access to the
  30 control device. Since only one process is allowed to have the recorder
  31 or player open at the same time it is a good idea to open the device
  32 only for the activity needed. See \manpage{audio}{7I} for details.
  33
  34 As per the manpage, this module first looks in the environment
  35 variable \code{AUDIODEV} for the base audio device filename.  If not
  36 found, it falls back to \file{/dev/audio}.  The control device is
  37 calculated by appending ``ctl'' to the base audio device.
  38 \end{funcdesc}
  39
  40
  41 \subsection{Audio Device Objects \label{audio-device-objects}}
  42
  43 The audio device objects are returned by \function{open()} define the
  44 following methods (except \code{control} objects which only provide
  45 \method{getinfo()}, \method{setinfo()}, \method{fileno()}, and
  46 \method{drain()}):
  47
  48 \begin{methoddesc}[audio device]{close}{}
  49 This method explicitly closes the device. It is useful in situations
  50 where deleting the object does not immediately close it since there
  51 are other references to it. A closed device should not be used again.
  52 \end{methoddesc}
  53
  54 \begin{methoddesc}[audio device]{fileno}{}
  55 Returns the file descriptor associated with the device.  This can be
  56 used to set up \code{SIGPOLL} notification, as described below.
  57 \end{methoddesc}
  58
  59 \begin{methoddesc}[audio device]{drain}{}
  60 This method waits until all pending output is processed and then returns.
  61 Calling this method is often not necessary: destroying the object will
  62 automatically close the audio device and this will do an implicit drain.
  63 \end{methoddesc}
  64
  65 \begin{methoddesc}[audio device]{flush}{}
  66 This method discards all pending output. It can be used avoid the
  67 slow response to a user's stop request (due to buffering of up to one
  68 second of sound).
  69 \end{methoddesc}
  70
  71 \begin{methoddesc}[audio device]{getinfo}{}
  72 This method retrieves status information like input and output volume,
  73 etc. and returns it in the form of
  74 an audio status object. This object has no methods but it contains a
  75 number of attributes describing the current device status. The names
  76 and meanings of the attributes are described in
  77 \code{<sun/audioio.h>} and in the \manpage{audio}{7I}
  78 manual page.  Member names
  79 are slightly different from their C counterparts: a status object is
  80 only a single structure. Members of the \cdata{play} substructure have
  81 \samp{o_} prepended to their name and members of the \cdata{record}
  82 structure have \samp{i_}. So, the C member \cdata{play.sample_rate} is
  83 accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain}
  84 and \cdata{monitor_gain} plainly as \member{monitor_gain}.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}[audio device]{ibufcount}{}
  88 This method returns the number of samples that are buffered on the
  89 recording side, i.e.\ the program will not block on a
  90 \function{read()} call of so many samples.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}[audio device]{obufcount}{}
  94 This method returns the number of samples buffered on the playback
  95 side. Unfortunately, this number cannot be used to determine a number
  96 of samples that can be written without blocking since the kernel
  97 output queue length seems to be variable.
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}[audio device]{read}{size}
 101 This method reads \var{size} samples from the audio input and returns
 102 them as a Python string. The function blocks until enough data is available.
 103 \end{methoddesc}
 104
 105 \begin{methoddesc}[audio device]{setinfo}{status}
 106 This method sets the audio device status parameters. The \var{status}
 107 parameter is an device status object as returned by \function{getinfo()} and
 108 possibly modified by the program.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}[audio device]{write}{samples}
 112 Write is passed a Python string containing audio samples to be played.
 113 If there is enough buffer space free it will immediately return,
 114 otherwise it will block.
 115 \end{methoddesc}
 116
 117 The audio device supports asynchronous notification of various events,
 118 through the SIGPOLL signal.  Here's an example of how you might enable
 119 this in Python:
 120
 121 \begin{verbatim}
 122 def handle_sigpoll(signum, frame):
 123     print 'I got a SIGPOLL update'
 124
 125 import fcntl, signal, STROPTS
 126
 127 signal.signal(signal.SIGPOLL, handle_sigpoll)
 128 fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
 129 \end{verbatim}
 130
 131
 132 \section{\module{SUNAUDIODEV} ---
 133          Constants used with \module{sunaudiodev}}
 134
 135 \declaremodule[sunaudiodev-constants]{standard}{SUNAUDIODEV}
 136   \platform{SunOS}
 137 \modulesynopsis{Constants for use with \refmodule{sunaudiodev}.}
 138
 139
 140 This is a companion module to
 141 \refmodule{sunaudiodev}\refbimodindex{sunaudiodev} which defines
 142 useful symbolic constants like \constant{MIN_GAIN},
 143 \constant{MAX_GAIN}, \constant{SPEAKER}, etc. The names of the
 144 constants are the same names as used in the C include file
 145 \code{<sun/audioio.h>}, with the leading string \samp{AUDIO_}
 146 stripped.