401 lines
16 KiB
TeX
401 lines
16 KiB
TeX
\section{\module{ossaudiodev} ---
|
|
Access to OSS-compatible audio devices}
|
|
|
|
\declaremodule{builtin}{ossaudiodev}
|
|
\platform{Linux, FreeBSD}
|
|
\modulesynopsis{Access to OSS-compatible audio devices.}
|
|
|
|
\versionadded{2.3}
|
|
|
|
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 and
|
|
recent versions of FreeBSD.
|
|
|
|
% Things will get more complicated for future Linux versions, since
|
|
% ALSA is in the standard kernel as of 2.5.x. Presumably if you
|
|
% use ALSA, you'll have to make sure its OSS compatibility layer
|
|
% is active to use ossaudiodev, but you're gonna need it for the vast
|
|
% majority of Linux audio apps anyways.
|
|
%
|
|
% Sounds like things are also complicated for other BSDs. In response
|
|
% to my python-dev query, Thomas Wouters said:
|
|
%
|
|
% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
|
|
% > OSS installation manual tells you to remove references to OSS/Free from the
|
|
% > kernel :)
|
|
%
|
|
% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
|
|
% from its <soundcard.h>:
|
|
% > * WARNING! WARNING!
|
|
% > * This is an OSS (Linux) audio emulator.
|
|
% > * Use the Native NetBSD API for developing new code, and this
|
|
% > * only for compiling Linux programs.
|
|
%
|
|
% There's also an ossaudio manpage on OpenBSD that explains things
|
|
% further. Presumably NetBSD and OpenBSD have a different standard
|
|
% audio interface. That's the great thing about standards, there are so
|
|
% many to choose from ... ;-)
|
|
%
|
|
% This probably all warrants a footnote or two, but I don't understand
|
|
% things well enough right now to write it! --GPW
|
|
|
|
\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 \code{<sys/soundcard.h>} on either
|
|
Linux or FreeBSD for a listing .}
|
|
\end{seealso}
|
|
|
|
\module{ossaudiodev} defines the following variables and functions:
|
|
|
|
\begin{excdesc}{OSSAudioError}
|
|
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{OSSAudioError}.)
|
|
|
|
(For backwards compatibility, the exception class is also available as
|
|
\code{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.
|
|
|
|
\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 sound cards 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 sound cards are half-duplex: they can be
|
|
opened for reading or writing, but not both at once.
|
|
|
|
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
|
|
\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}}
|
|
|
|
Before you can write to or read from an audio device, you must call
|
|
three methods in the correct order:
|
|
\begin{enumerate}
|
|
\item \method{setfmt()} to set the output format
|
|
\item \method{channels()} to set the number of channels
|
|
\item \method{speed()} to set the sample rate
|
|
\end{enumerate}
|
|
Alternately, you can use the \method{setparameters()} method to set all
|
|
three audio parameters at once. This is more convenient, but may not be
|
|
as flexible in all cases.
|
|
|
|
The audio device objects returned by \function{open()} define the
|
|
following methods and (read-only) attributes:
|
|
|
|
\begin{methoddesc}[audio device]{close}{}
|
|
Explicitly close the audio device. When you are done writing to or
|
|
reading from an audio device, you should explicitly close it. A closed
|
|
device cannot be used again.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{fileno}{}
|
|
Return the file descriptor associated with the device.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{read}{size}
|
|
Read \var{size} bytes from the audio input and return them as a Python
|
|
string. Unlike most \UNIX{} device drivers, OSS audio devices in
|
|
blocking mode (the default) will block \function{read()} until the
|
|
entire requested amount of data is available.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{write}{data}
|
|
Write the Python string \var{data} to the audio device and return the
|
|
number of bytes written. If the audio device is in blocking mode (the
|
|
default), the entire string is always written (again, this is different
|
|
from usual \UNIX{} device semantics). If the device is in non-blocking
|
|
mode, some data may not be written---see \method{writeall()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{writeall}{data}
|
|
Write the entire Python string \var{data} to the audio device: waits
|
|
until the audio device is able to accept data, writes as much data as it
|
|
will accept, and repeats until \var{data} has been completely written.
|
|
If the device is in blocking mode (the default), this has the same
|
|
effect as \method{write()}; \method{writeall()} is only useful in
|
|
non-blocking mode. Has no return value, since the amount of data
|
|
written is always equal to the amount of data supplied.
|
|
\end{methoddesc}
|
|
|
|
The following methods each map to exactly one
|
|
\function{ioctl()} system call. The correspondence is obvious: for
|
|
example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT}
|
|
ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful
|
|
when consulting the OSS documentation). If the underlying
|
|
\function{ioctl()} fails, they all raise \exception{IOError}.
|
|
|
|
\begin{methoddesc}[audio device]{nonblock}{}
|
|
Put the device into non-blocking mode. Once in non-blocking mode, there
|
|
is no way to return it to blocking mode.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{getfmts}{}
|
|
Return 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 (used by Sun \code{.au} files and
|
|
\filenq{/dev/audio})}
|
|
\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}
|
|
Try to set the current audio format to \var{format}---see
|
|
\method{getfmts()} for a list. Returns the audio format that the device
|
|
was set to, which may not be the requested format. May also be used to
|
|
return the current audio format---do this by passing an ``audio format''
|
|
of
|
|
\constant{AFMT_QUERY}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{channels}{nchannels}
|
|
Set the number of output channels to \var{nchannels}. 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}
|
|
Try to set the audio sampling rate to \var{samplerate} samples per
|
|
second. Returns the rate actually set. Most sound devices don't
|
|
support arbitrary sampling rates. Common rates are:
|
|
\begin{tableii}{l|l}{textrm}{Rate}{Description}
|
|
\lineii{8000}{default rate for \filenq{/dev/audio}}
|
|
\lineii{11025}{speech recording}
|
|
\lineii{22050}{}
|
|
\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
|
|
\lineii{96000}{DVD quality audio (at 24 bits/sample)}
|
|
\end{tableii}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{sync}{}
|
|
Wait until the sound device has played every byte in its buffer. (This
|
|
happens implicitly when the device is closed.) The OSS documentation
|
|
recommends closing and re-opening the device rather than using
|
|
\method{sync()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[audio device]{reset}{}
|
|
Immediately stop playing or recording and return 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}{}
|
|
Tell the driver that there is likely to be a pause in the output, making
|
|
it possible for the device to handle the pause more intelligently. You
|
|
might use this after playing a spot sound effect, before waiting for
|
|
user input, or before doing disk I/O.
|
|
\end{methoddesc}
|
|
|
|
The following convenience methods combine several ioctls, or one ioctl
|
|
and some simple calculations.
|
|
|
|
\begin{methoddesc}[audio device]{setparameters}
|
|
{format, nchannels, samplerate \optional{, strict=False}}
|
|
|
|
Set the key audio sampling parameters---sample format, number of
|
|
channels, and sampling rate---in one method call. \var{format},
|
|
\var{nchannels}, and \var{samplerate} should be as specified in the
|
|
\method{setfmt()}, \method{channels()}, and \method{speed()}
|
|
methods. If \var{strict} is true, \method{setparameters()} checks to
|
|
see if each parameter was actually set to the requested value, and
|
|
raises \exception{OSSAudioError} if not. Returns a tuple (\var{format},
|
|
\var{nchannels}, \var{samplerate}) indicating the parameter values that
|
|
were actually set by the device driver (i.e., the same as the return
|
|
values of \method{setfmt()}, \method{channels()}, and \method{speed()}).
|
|
|
|
For example,
|
|
\begin{verbatim}
|
|
(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
|
|
\end{verbatim}
|
|
is equivalent to
|
|
\begin{verbatim}
|
|
fmt = dsp.setfmt(fmt)
|
|
channels = dsp.channels(channels)
|
|
rate = dsp.rate(channels)
|
|
\end{verbatim}
|
|
\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}
|
|
|
|
Audio device objects also support several read-only attributes:
|
|
|
|
\begin{memberdesc}[audio device]{closed}{}
|
|
Boolean indicating whether the device has been closed.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[audio device]{name}{}
|
|
String containing the name of the device file.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[audio device]{mode}{}
|
|
The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}.
|
|
\end{memberdesc}
|
|
|
|
|
|
\subsection{Mixer Device Objects \label{mixer-device-objects}}
|
|
|
|
The mixer object provides two file-like methods:
|
|
|
|
\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}
|
|
|
|
The remaining methods are specific to audio mixing:
|
|
|
|
\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 controls---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.controls() & (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} controls should suffice---but code that uses the
|
|
mixer should be flexible when it comes to choosing mixer controls. 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 controls. If a bit is set,
|
|
the corresponding control is stereo; if it is unset, the control is
|
|
either monophonic or not supported by the mixer (use in combination with
|
|
\method{controls()} to determine which).
|
|
|
|
See the code example for the \method{controls()} 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}{control}
|
|
Returns the volume of a given mixer control. 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 control is
|
|
monophonic, a 2-tuple is still returned, but both volumes are
|
|
the same.
|
|
|
|
Raises \exception{OSSAudioError} if an invalid control was is specified,
|
|
or \exception{IOError} if an unsupported control is specified.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{set}{control, (left, right)}
|
|
Sets the volume for a given mixer control 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{OSSAudioError} if an invalid mixer control was
|
|
specified, or if the specified volumes were out-of-range.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[mixer device]{get_recsrc}{}
|
|
This method returns a bitmask indicating which control(s) 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}
|
|
|
|
|
|
|