diff options
Diffstat (limited to 'Doc/lib/libsunaudio.tex')
-rw-r--r-- | Doc/lib/libsunaudio.tex | 146 |
1 files changed, 0 insertions, 146 deletions
diff --git a/Doc/lib/libsunaudio.tex b/Doc/lib/libsunaudio.tex deleted file mode 100644 index ec70437..0000000 --- a/Doc/lib/libsunaudio.tex +++ /dev/null @@ -1,146 +0,0 @@ -\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. |