Doc/libsun.tex

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