Doc/libsun.tex

\chapter{SUNOS ONLY}

The modules described in this chapter provide interfaces to features
that are unique to the SunOS operating system (versions 4 and 5; the
latter is also known as SOLARIS version 2).

\section{Built-in module \sectcode{sunaudiodev}}
\bimodindex{sunaudiodev}

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 format with a sample rate of 8K per second. A full
description can be gotten with \samp{man audio}.

The module defines the following variables and functions:

\renewcommand{\indexsubitem}{(in module sunaudiodev)}
\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 the audio manpage for details.
\end{funcdesc}

\subsection{Audio device object methods}

The audio device objects are returned by \code{open} define the
following methods (except \code{control} objects which only provide
getinfo, setinfo and drain):

\renewcommand{\indexsubitem}{(audio device method)}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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
\file{/usr/include/sun/audioio.h} and in the audio man page. Member names
are slightly different from their C counterparts: a status object is
only a single structure. Members of the \code{play} substructure have
\samp{o_} prepended to their name and members of the \code{record}
structure have \samp{i_}. So, the C member \code{play.sample_rate} is
accessed as \code{o_sample_rate}, \code{record.gain} as \code{i_gain}
and \code{monitor_gain} plainly as \code{monitor_gain}.
\end{funcdesc}

\begin{funcdesc}{ibufcount}{}
This method returns the number of samples that are buffered on the
recording side, i.e.
the program will not block on a \code{read} call of so many samples.
\end{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{setinfo}{status}
This method sets the audio device status parameters. The \var{status}
parameter is an device status object as returned by \code{getinfo} and
possibly modified by the program.
\end{funcdesc}

\begin{funcdesc}{write}{samples}
Write is passed a python string containing audio samples to be played.
If there is enough buffer space free it will immedeately return,
otherwise it will block.
\end{funcdesc}

There is a companion module, \code{SUNAUDIODEV}, which defines useful
symbolic constants like \code{MIN_GAIN}, \code{MAX_GAIN},
\code{SPEAKER}, etc. The names of
the constants are the same names as used in the C include file
\file{<sun/audioio.h>}, with the leading string \samp{AUDIO_} stripped.

Useability of the control device is limited at the moment, since there
is no way to use the 'wait for something to happen' feature the device
provides. This is because that feature makes heavy use of signals, and
these do not map too well onto Python.