mirror of https://github.com/python/cpython
134 lines
5.4 KiB
TeX
134 lines
5.4 KiB
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 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}
|
|
|
|
There is a companion module,
|
|
\module{SUNAUDIODEV}\refstmodindex{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.
|
|
|
|
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}
|