ref: 1fe3143e4c43ce2c74e0cfdd70b1bd556bbb9e1b
dir: /sys/src/cmd/python/Doc/lib/libsunaudio.tex/
\section{\module{sunaudiodev} --- Access to Sun audio hardware} \declaremodule{builtin}{sunaudiodev} \platform{SunOS} \modulesynopsis{Access to Sun audio hardware.} This module allows you to access the Sun audio interface. The Sun audio hardware is capable of recording and playing back audio data in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A full description can be found in the \manpage{audio}{7I} manual page. The module \refmodule[sunaudiodev-constants]{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV} defines constants which may be used with this module. This module defines the following variables and functions: \begin{excdesc}{error} This exception is raised on all errors. The argument is a string describing what went wrong. \end{excdesc} \begin{funcdesc}{open}{mode} This function opens the audio device and returns a Sun audio device object. This object can then be used to do I/O on. The \var{mode} parameter is one of \code{'r'} for record-only access, \code{'w'} for play-only access, \code{'rw'} for both and \code{'control'} for access to the control device. Since only one process is allowed to have the recorder or player open at the same time it is a good idea to open the device only for the activity needed. See \manpage{audio}{7I} for details. As per the manpage, this module first looks in the environment variable \code{AUDIODEV} for the base audio device filename. If not found, it falls back to \file{/dev/audio}. The control device is calculated by appending ``ctl'' to the base audio device. \end{funcdesc} \subsection{Audio Device Objects \label{audio-device-objects}} The audio device objects are returned by \function{open()} define the following methods (except \code{control} objects which only provide \method{getinfo()}, \method{setinfo()}, \method{fileno()}, and \method{drain()}): \begin{methoddesc}[audio device]{close}{} This method explicitly closes the device. It is useful in situations where deleting the object does not immediately close it since there are other references to it. A closed device should not be used again. \end{methoddesc} \begin{methoddesc}[audio device]{fileno}{} Returns the file descriptor associated with the device. This can be used to set up \code{SIGPOLL} notification, as described below. \end{methoddesc} \begin{methoddesc}[audio device]{drain}{} This method waits until all pending output is processed and then returns. Calling this method is often not necessary: destroying the object will automatically close the audio device and this will do an implicit drain. \end{methoddesc} \begin{methoddesc}[audio device]{flush}{} This method discards all pending output. It can be used avoid the slow response to a user's stop request (due to buffering of up to one second of sound). \end{methoddesc} \begin{methoddesc}[audio device]{getinfo}{} This method retrieves status information like input and output volume, etc. and returns it in the form of an audio status object. This object has no methods but it contains a number of attributes describing the current device status. The names and meanings of the attributes are described in \code{<sun/audioio.h>} and in the \manpage{audio}{7I} manual page. Member names are slightly different from their C counterparts: a status object is only a single structure. Members of the \cdata{play} substructure have \samp{o_} prepended to their name and members of the \cdata{record} structure have \samp{i_}. So, the C member \cdata{play.sample_rate} is accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain} and \cdata{monitor_gain} plainly as \member{monitor_gain}. \end{methoddesc} \begin{methoddesc}[audio device]{ibufcount}{} This method returns the number of samples that are buffered on the recording side, i.e.\ the program will not block on a \function{read()} call of so many samples. \end{methoddesc} \begin{methoddesc}[audio device]{obufcount}{} This method returns the number of samples buffered on the playback side. Unfortunately, this number cannot be used to determine a number of samples that can be written without blocking since the kernel output queue length seems to be variable. \end{methoddesc} \begin{methoddesc}[audio device]{read}{size} This method reads \var{size} samples from the audio input and returns them as a Python string. The function blocks until enough data is available. \end{methoddesc} \begin{methoddesc}[audio device]{setinfo}{status} This method sets the audio device status parameters. The \var{status} parameter is an device status object as returned by \function{getinfo()} and possibly modified by the program. \end{methoddesc} \begin{methoddesc}[audio device]{write}{samples} Write is passed a Python string containing audio samples to be played. If there is enough buffer space free it will immediately return, otherwise it will block. \end{methoddesc} The audio device supports asynchronous notification of various events, through the SIGPOLL signal. Here's an example of how you might enable this in Python: \begin{verbatim} def handle_sigpoll(signum, frame): print 'I got a SIGPOLL update' import fcntl, signal, STROPTS signal.signal(signal.SIGPOLL, handle_sigpoll) fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG) \end{verbatim} \section{\module{SUNAUDIODEV} --- Constants used with \module{sunaudiodev}} \declaremodule[sunaudiodev-constants]{standard}{SUNAUDIODEV} \platform{SunOS} \modulesynopsis{Constants for use with \refmodule{sunaudiodev}.} This is a companion module to \refmodule{sunaudiodev}\refbimodindex{sunaudiodev} which defines useful symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN}, \constant{SPEAKER}, etc. The names of the constants are the same names as used in the C include file \code{<sun/audioio.h>}, with the leading string \samp{AUDIO_} stripped.