328 lines
13 KiB
TeX
328 lines
13 KiB
TeX
\section{\module{ossaudiodev} ---
|
|
Access to OSS-compatible audio devices}
|
|
|
|
\declaremodule{builtin}{ossaudiodev}
|
|
\platform{Linux, FreeBSD}
|
|
\modulesynopsis{Access to OSS-compatible audio devices.}
|
|
|
|
% XXX OSS is standard for Linux and FreeBSD -- what about NetBSD?
|
|
% OpenBSD? others?
|
|
This module allows you to access the OSS (Open Sound System) audio
|
|
interface. OSS is available for a wide range of open-source and
|
|
commercial Unices, and is the standard audio interface for Linux (up to
|
|
kernel 2.4) and FreeBSD.
|
|
|
|
\begin{seealso}
|
|
\seetitle[http://www.opensound.com/pguide/oss.pdf]
|
|
{Open Sound System Programmer's Guide}
|
|
{the official documentation for the OSS C API}
|
|
\seetext{The module defines a large number of constants supplied by
|
|
the OSS device driver; see \file{<sys/soundcard.h>} on either
|
|
Linux or FreeBSD for a listing .}
|
|
\end{seealso}
|
|
|
|
\module{ossaudiodev} defines the following variables and functions:
|
|
|
|
\begin{excdesc}{error}
|
|
This exception is raised on certain errors. The argument is a string
|
|
describing what went wrong.
|
|
|
|
(If \module{ossaudiodev} receives an error from a system call such as
|
|
\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it
|
|
raises \exception{IOError}. Errors detected directly by
|
|
\module{ossaudiodev} result in \exception{ossaudiodev.error}.)
|
|
\end{excdesc}
|
|
|
|
\begin{funcdesc}{open}{\optional{device, }mode}
|
|
Open an audio device and return an OSS audio device object. This
|
|
object supports many file-like methods, such as \method{read()},
|
|
\method{write()}, and \method{fileno()} (although there are subtle
|
|
differences between conventional Unix read/write semantics and those of
|
|
OSS audio devices). It also supports a number of audio-specific
|
|
methods; see below for the complete list of methods.
|
|
|
|
Note the unusual calling syntax: the \emph{first} argument is optional,
|
|
and the second is required. This is a historical artifact for
|
|
compatibility with the older \module{linuxaudiodev} module which
|
|
\module{ossaudiodev} supersedes. % XXX it might also be motivated
|
|
% by my unfounded-but-still-possibly-true belief that the default
|
|
% audio device varies unpredictably across operating systems. -GW
|
|
|
|
\var{device} is the audio device filename to use. If it is not
|
|
specified, this module first looks in the environment variable
|
|
\envvar{AUDIODEV} for a device to use. If not found, it falls back to
|
|
\file{/dev/dsp}.
|
|
|
|
\var{mode} is one of \code{'r'} for read-only (record) access,
|
|
\code{'w'} for write-only (playback) access and \code{'rw'} for both.
|
|
Since many soundcards only allow one process to have the recorder or
|
|
player open at a time it is a good idea to open the device only for the
|
|
activity needed. Further, some soundcards are half-duplex: they can be
|
|
opened for reading or writing, but not both at once.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{openmixer}{\optional{device}}
|
|
Open a mixer device and return an OSS mixer device object.
|
|
\var{device} is the mixer device filename to use. If it is
|
|
not specified, this module first looks in the environment variable
|
|
\envvar{MIXERDEV} for a device to use. If not found, it falls back to
|
|
\file{/dev/mixer}.
|
|
|
|
\end{funcdesc}
|
|
|
|
\subsection{Audio Device Objects \label{ossaudio-device-objects}}
|
|
|
|
Setting up the device
|
|
|
|
To set up the device, three functions must be called in the correct
|
|
sequence:
|
|
\begin{enumerate}
|
|
\item \method{setfmt()} to set the output format,
|
|
\item \method{channels()} to set the number of channels, and
|
|
\item \method{speed()} to set the sample rate.
|
|
\end{enumerate}
|
|
|
|
The audio device objects are returned by \function{open()} define the
|
|
following methods:
|
|
|
|
\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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{read}{size}
|
|
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]{write}{data}
|
|
Writes Python string \var{data} to the audio device and returns the
|
|
number of bytes written. If the audio device is opened in blocking
|
|
mode, the entire string is always written. If the device is opened in
|
|
nonblocking mode, some data may not be written---see
|
|
\method{writeall()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{writeall}{data}
|
|
Writes the entire Python string \var{data} to the audio device. If the
|
|
device is opened in blocking mode, behaves identially to
|
|
\method{write()}; in nonblocking mode, waits until the device becomes
|
|
available before feeding it more data. Returns \code{None}, since the
|
|
amount of data written is always equal to the amount of data supplied.
|
|
\end{methoddesc}
|
|
|
|
Simple IOCTLs:
|
|
|
|
\begin{methoddesc}[audio device]{nonblock}{}
|
|
Attempts to put the device into nonblocking mode. Once in nonblocking
|
|
mode there is no way to return to blocking mode.
|
|
|
|
Raises \exception{IOError} if the IOCTL failed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{getfmts}{}
|
|
Returns a bitmask of the audio output formats supported by the
|
|
soundcard. On a typical Linux system, these formats are:
|
|
|
|
\begin{tableii}{l|l}{constant}{Format}{Description}
|
|
\lineii{AFMT_MU_LAW}
|
|
{a logarithmic encoding. This is the default format on
|
|
\file{/dev/audio} and is the format used by Sun .au files.}
|
|
\lineii{AFMT_A_LAW}
|
|
{a logarithmic encoding}
|
|
\lineii{AFMT_IMA_ADPCM}
|
|
{a 4:1 compressed format defined by the Interactive Multimedia
|
|
Association.}
|
|
\lineii{AFMT_U8}
|
|
{Unsigned, 8-bit audio.}
|
|
\lineii{AFMT_S16_LE}
|
|
{Unsigned, 16-bit audio, little-endian byte order (as used by
|
|
Intel processors)}
|
|
\lineii{AFMT_S16_BE}
|
|
{Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
|
|
PowerPC, Sparc)}
|
|
\lineii{AFMT_S8}
|
|
{Signed, 8 bit audio.}
|
|
\lineii{AFMT_U16_LE}
|
|
{Signed, 16-bit little-endian audio}
|
|
\lineii{AFMT_U16_BE}
|
|
{Signed, 16-bit big-endian audio}
|
|
\end{tableii}
|
|
Most systems support only a subset of these formats. Many devices only
|
|
support \constant{AFMT_U8}; the most common format used today is
|
|
\constant{AFMT_S16_LE}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{setfmt}{format}
|
|
Used to set the current audio format to \var{format}---see
|
|
\method{getfmts()} for a list. May also be used to return the current
|
|
audio format---do this by passing an ``audio format'' of
|
|
\constant{AFMT_QUERY}. Returns the audio format that the device was set
|
|
to, which may not be the requested format.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{channels}{num_channels}
|
|
Sets the number of output channels to \var{num_channels}. A value of 1
|
|
indicates monophonic sound, 2 stereophonic. Some devices may have more
|
|
than 2 channels, and some high-end devices may not support mono.
|
|
Returns the number of channels the device was set to.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{speed}{samplerate}
|
|
Sets the samplerate to \var{samplerate} samples per second and returns
|
|
the rate actually set. Most sound devices don't support arbitrary
|
|
sample rates. Common rates are:
|
|
|
|
8000---default rate
|
|
11025---speech recording
|
|
22050
|
|
44100---Audio CD-quality (at 16 bits/sample and 2 channels)
|
|
96000---DVD-quality
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{sync}
|
|
Waits until the sound device has played every byte in its buffer and
|
|
returns. This also occurs when the sound device is closed. The OSS
|
|
documentation recommends simply closing and re-opening the device rather
|
|
than using \method{sync()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{reset}
|
|
Immediately stops and playing or recording and returns the device to a
|
|
state where it can accept commands. The OSS documentation recommends
|
|
closing and re-opening the device after calling \method{reset()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{post}
|
|
To be used like a lightweight \method{sync()}, the \method{post()}
|
|
IOCTL informs the audio device that there is a likely to be a pause in
|
|
the audio output---i.e., after playing a spot sound effect, before
|
|
waiting for user input, or before doing disk I/O.
|
|
\end{methoddesc}
|
|
|
|
Convenience methods
|
|
|
|
\begin{methoddesc}[audio device]{setparameters}{samplerate,num_channels,format,emulate}
|
|
Initialise the sound device in one method. \var{samplerate},
|
|
\var{channels} and \var{format} should be as specified in the
|
|
\method{speed()}, \method{channels()} and \method{setfmt()}
|
|
methods. If \var{emulate} is true, attempt to find the closest matching
|
|
format instead, otherwise raise ValueError if the device does not
|
|
support the format. The default is to raise ValueError on unsupported
|
|
formats.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{bufsize}{}
|
|
Returns the size of the hardware buffer, in samples.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{obufcount}{}
|
|
Returns the number of samples that are in the hardware buffer yet to be
|
|
played.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{obuffree}{}
|
|
Returns the number of samples that could be queued into the hardware
|
|
buffer to be played without blocking.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Mixer Device Objects \label{mixer-device-objects}}
|
|
|
|
File-like interface
|
|
|
|
\begin{methoddesc}[mixer device]{close}{}
|
|
This method closes the open mixer device file. Any further attempts to
|
|
use the mixer after this file is closed will raise an IOError.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{fileno}{}
|
|
Returns the file handle number of the open mixer device file.
|
|
\end{methoddesc}
|
|
|
|
Mixer interface
|
|
|
|
\begin{methoddesc}[mixer device]{controls}{}
|
|
This method returns a bitmask specifying the available mixer controls
|
|
(``Control'' being a specific mixable ``channel'', such as
|
|
\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This
|
|
bitmask indicates a subset of all available mixer channels---the
|
|
\constant{SOUND_MIXER_*} constants defined at module level. To determine if,
|
|
for example, the current mixer object supports a PCM mixer, use the
|
|
following Python code:
|
|
|
|
\begin{verbatim}
|
|
mixer=ossaudiodev.openmixer()
|
|
if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM):
|
|
# PCM is supported
|
|
<code>
|
|
\end{verbatim}
|
|
|
|
For most purposes, the \constant{SOUND_MIXER_VOLUME} (Master volume) and
|
|
\constant{SOUND_MIXER_PCM} channels should suffice---but code that uses the
|
|
mixer should be flexible when it comes to choosing sound channels. On
|
|
the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
|
|
exist.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{stereocontrols}{}
|
|
Returns a bitmask indicating stereo mixer channels. If a bit is set,
|
|
the corresponding channel is stereo; if it is unset, the channel is
|
|
either monophonic or not supported by the mixer (use in combination with
|
|
\method{channels()} to determine which).
|
|
|
|
See the code example for the \method{channels()} function for an example
|
|
of getting data from a bitmask.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{reccontrols}{}
|
|
Returns a bitmask specifying the mixer controls that may be used to
|
|
record. See the code example for \method{controls()} for an example of
|
|
reading from a bitmask.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{get}{channel}
|
|
Returns the volume of a given mixer channel. The returned volume is a
|
|
2-tuple \code{(left_volume,right_volume)}. Volumes are specified as
|
|
numbers from 0 (silent) to 100 (full volume). If the channel is
|
|
monophonic, a 2-tuple is still returned, but both channel volumes are
|
|
the same.
|
|
|
|
If an unknown channel is specified, \exception{error} is raised.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{set}{channel, (left, right)}
|
|
Sets the volume for a given mixer channel to \code{(left,right)}.
|
|
\code{left} and \code{right} must be ints and between 0 (silent) and 100
|
|
(full volume). On success, the new volume is returned as a 2-tuple.
|
|
Note that this may not be exactly the same as the volume specified,
|
|
because of the limited resolution of some soundcard's mixers.
|
|
|
|
Raises \exception{IOError} if an invalid mixer channel was specified;
|
|
\exception{TypeError} if the argument format was incorrect, and
|
|
\exception{error} if the specified volumes were out-of-range.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{get_recsrc}{}
|
|
This method returns a bitmask indicating which channel or channels are
|
|
currently being used as a recording source.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{set_recsrc}{bitmask}
|
|
Call this function to specify a recording source. Returns a bitmask
|
|
indicating the new recording source (or sources) if successful; raises
|
|
\exception{IOError} if an invalid source was specified. To set the current
|
|
recording source to the microphone input:
|
|
|
|
\begin{verbatim}
|
|
mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
|
|
\end{verbatim}
|
|
\end{methoddesc}
|
|
|
|
|
|
|