Doc/libsunaudio.tex

   1 \section{Built-in Module \module{sunaudiodev}}
   2 \label{module-sunaudiodev}
   3 \bimodindex{sunaudiodev}
   4
   5 This module allows you to access the sun audio interface. The sun
   6 audio hardware is capable of recording and playing back audio data
   7 in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A
   8 full description can be found in the \manpage{audio}{7I} manual page.
   9
  10 The module defines the following variables and functions:
  11
  12 \begin{excdesc}{error}
  13 This exception is raised on all errors. The argument is a string
  14 describing what went wrong.
  15 \end{excdesc}
  16
  17 \begin{funcdesc}{open}{mode}
  18 This function opens the audio device and returns a sun audio device
  19 object. This object can then be used to do I/O on. The \var{mode} parameter
  20 is one of \code{'r'} for record-only access, \code{'w'} for play-only
  21 access, \code{'rw'} for both and \code{'control'} for access to the
  22 control device. Since only one process is allowed to have the recorder
  23 or player open at the same time it is a good idea to open the device
  24 only for the activity needed. See \manpage{audio}{7I} for details.
  25 \end{funcdesc}
  26
  27
  28 \subsection{Audio Device Objects}
  29 \label{audio-device-objects}
  30
  31 The audio device objects are returned by \function{open()} define the
  32 following methods (except \code{control} objects which only provide
  33 \method{getinfo()}, \method{setinfo()} and \method{drain()}):
  34
  35 \begin{methoddesc}[audio device]{close}{}
  36 This method explicitly closes the device. It is useful in situations
  37 where deleting the object does not immediately close it since there
  38 are other references to it. A closed device should not be used again.
  39 \end{methoddesc}
  40
  41 \begin{methoddesc}[audio device]{drain}{}
  42 This method waits until all pending output is processed and then returns.
  43 Calling this method is often not necessary: destroying the object will
  44 automatically close the audio device and this will do an implicit drain.
  45 \end{methoddesc}
  46
  47 \begin{methoddesc}[audio device]{flush}{}
  48 This method discards all pending output. It can be used avoid the
  49 slow response to a user's stop request (due to buffering of up to one
  50 second of sound).
  51 \end{methoddesc}
  52
  53 \begin{methoddesc}[audio device]{getinfo}{}
  54 This method retrieves status information like input and output volume,
  55 etc. and returns it in the form of
  56 an audio status object. This object has no methods but it contains a
  57 number of attributes describing the current device status. The names
  58 and meanings of the attributes are described in
  59 \file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I}
  60 manual page.  Member names
  61 are slightly different from their \C{} counterparts: a status object is
  62 only a single structure. Members of the \cdata{play} substructure have
  63 \samp{o_} prepended to their name and members of the \cdata{record}
  64 structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is
  65 accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain}
  66 and \cdata{monitor_gain} plainly as \member{monitor_gain}.
  67 \end{methoddesc}
  68
  69 \begin{methoddesc}[audio device]{ibufcount}{}
  70 This method returns the number of samples that are buffered on the
  71 recording side, i.e.\ the program will not block on a
  72 \function{read()} call of so many samples.
  73 \end{methoddesc}
  74
  75 \begin{methoddesc}[audio device]{obufcount}{}
  76 This method returns the number of samples buffered on the playback
  77 side. Unfortunately, this number cannot be used to determine a number
  78 of samples that can be written without blocking since the kernel
  79 output queue length seems to be variable.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}[audio device]{read}{size}
  83 This method reads \var{size} samples from the audio input and returns
  84 them as a Python string. The function blocks until enough data is available.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}[audio device]{setinfo}{status}
  88 This method sets the audio device status parameters. The \var{status}
  89 parameter is an device status object as returned by \function{getinfo()} and
  90 possibly modified by the program.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}[audio device]{write}{samples}
  94 Write is passed a Python string containing audio samples to be played.
  95 If there is enough buffer space free it will immediately return,
  96 otherwise it will block.
  97 \end{methoddesc}
  98
  99 There is a companion module,
 100 \module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful
 101 symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN},
 102 \constant{SPEAKER}, etc. The names of the constants are the same names
 103 as used in the \C{} include file \code{<sun/audioio.h>}, with the
 104 leading string \samp{AUDIO_} stripped.
 105
 106 Useability of the control device is limited at the moment, since there
 107 is no way to use the ``wait for something to happen'' feature the
 108 device provides.