Wrap all paragraphs to 72 columns.
Two spaces between sentences. Fix em-dashes -- should be "---" not " - ". Spelling fix.
This commit is contained in:
Greg Ward
parent
620e343c0a
commit
33bcd987dd
|
|
@ -5,49 +5,50 @@
|
|||
\platform{OSS}
|
||||
\modulesynopsis{Access to OSS-compatible audio hardware.}
|
||||
|
||||
% I know FreeBSD uses OSS - what about Net- and Open-?
|
||||
% I know FreeBSD uses OSS -- what about Net- and Open-?
|
||||
This module allows you to access the Open Sound System audio interface.
|
||||
The Open Sound System interface is present on Linux and FreeBSD.
|
||||
|
||||
This module provides a very "bare bones" wrapper over the IOCTLs used to
|
||||
access the audio hardware. The best - albeit rather daunting - way to
|
||||
access the audio hardware. The best---albeit rather daunting---way to
|
||||
get a feel for the interface is from the Open Sound System official
|
||||
documentation:
|
||||
|
||||
\url{http://www.opensound.com/pguide/oss.pdf}
|
||||
|
||||
The module defines a number of constants which may be used to program the
|
||||
device. These constants are the same as those defined in the C include file
|
||||
\code{<sys/soundcard.h>}.
|
||||
The module defines a number of constants which may be used to program
|
||||
the device. These constants are the same as those defined in the C
|
||||
include file \code{<sys/soundcard.h>}.
|
||||
|
||||
\code{ossaudiodev} defines the following variables and functions:
|
||||
|
||||
\begin{excdesc}{error}
|
||||
This exception is raised on errors. The argument is a string
|
||||
describing what went wrong.
|
||||
This exception is raised on errors. The argument is a string describing
|
||||
what went wrong.
|
||||
\end{excdesc}
|
||||
|
||||
\begin{funcdesc}{open}{\optional{device, }mode}
|
||||
This function opens the audio device and returns an OSS audio device
|
||||
object. This object can then be used to do I/O on. The \var{device}
|
||||
parameter is the audio device filename to use. If it is not specified, this
|
||||
module first looks in the environment variable \code{AUDIODEV} for a device
|
||||
to use. If not found, it falls back to \file{/dev/dsp}.
|
||||
parameter is the audio device filename to use. If it is not specified,
|
||||
this module first looks in the environment variable \code{AUDIODEV} for
|
||||
a device to use. If not found, it falls back to \file{/dev/dsp}.
|
||||
|
||||
The \var{mode} parameter is one of \code{'r'} for record-only access,
|
||||
\code{'w'} for play-only 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.
|
||||
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\optional{, mode}}} This function
|
||||
opens the mixer device and returns an OSS mixer device object. The \var{device}
|
||||
parameter is the mixer device filename to use. If it is not specified, this
|
||||
module first looks in the environment variable \code{MIXERDEV} for a device to
|
||||
use. If not found, it falls back to \file{/dev/mixer}. You may specify
|
||||
\code{'r'}, \code{'rw'} or \code{'w'} for \var{mode}; the default is \code{'r'}.
|
||||
opens the mixer device and returns an OSS mixer device object. The
|
||||
\var{device} parameter is the mixer device filename to use. If it is
|
||||
not specified, this module first looks in the environment variable
|
||||
\code{MIXERDEV} for a device to use. If not found, it falls back to
|
||||
\file{/dev/mixer}. You may specify \code{'r'}, \code{'rw'} or
|
||||
\code{'w'} for \var{mode}; the default is \code{'r'}.
|
||||
|
||||
\end{funcdesc}
|
||||
|
||||
|
|
@ -55,7 +56,8 @@ use. If not found, it falls back to \file{/dev/mixer}. You may specify
|
|||
|
||||
Setting up the device
|
||||
|
||||
To set up the device, three functions must be called in the correct sequence:
|
||||
To set up the device, three functions must be called in the correct
|
||||
sequence:
|
||||
|
||||
\code{setfmt} to set the output format,
|
||||
\code{channels} to set the number of channels, and
|
||||
|
|
@ -66,8 +68,8 @@ 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.
|
||||
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}{}
|
||||
|
|
@ -75,111 +77,112 @@ 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.
|
||||
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 \code{writeall}.
|
||||
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 \code{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 \code{write}; in nonblocking
|
||||
mode, waits until the device becomes available before feeding it more data.
|
||||
Returns None, since the amount of data written is always equal to the amount
|
||||
of data supplied.
|
||||
Writes the entire Python string \var{data} to the audio device. If the
|
||||
device is opened in blocking mode, behaves identially to \code{write};
|
||||
in nonblocking mode, waits until the device becomes available before
|
||||
feeding it more data. Returns 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.
|
||||
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:
|
||||
Returns a bitmask of the audio output formats supported by the
|
||||
soundcard. On a typical Linux system, these formats are:
|
||||
|
||||
AFMT_MU_LAW - a logarithmic encoding. This is the default format on /dev/audio
|
||||
and is the format used by Sun .au files.
|
||||
AFMT_A_LAW - a logarithmic encoding
|
||||
AFMT_IMA_ADPCM - a 4:1 compressed format defined by the Interactive Multimedia
|
||||
Association.
|
||||
AFMT_U8 - Unsigned, 8-bit audio.
|
||||
AFMT_S16_LE - Unsigned, 16-bit audio, little-endian byte order (as used by Intel
|
||||
processors)
|
||||
AFMT_S16_BE - Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
|
||||
PowerPC, Sparc)
|
||||
AFMT_S8 - Signed, 8 bit audio.
|
||||
AFMT_U16_LE - Signed, 16-bit little-endian audio
|
||||
AFMT_U16_BE - Signed, 16-bit big-endian audio
|
||||
AFMT_MU_LAW---a logarithmic encoding. This is the default format on
|
||||
/dev/audio and is the format used by Sun .au files.
|
||||
AFMT_A_LAW---a logarithmic encoding
|
||||
AFMT_IMA_ADPCM---a 4:1 compressed format defined by the Interactive
|
||||
Multimedia Association.
|
||||
AFMT_U8---Unsigned, 8-bit audio.
|
||||
AFMT_S16_LE---Unsigned, 16-bit audio, little-endian byte order (as used
|
||||
by Intel processors)
|
||||
AFMT_S16_BE---Unsigned, 16-bit audio, big-endian byte order (as used by
|
||||
68k, PowerPC, Sparc)
|
||||
AFMT_S8---Signed, 8 bit audio.
|
||||
AFMT_U16_LE---Signed, 16-bit little-endian audio
|
||||
AFMT_U16_BE---Signed, 16-bit big-endian audio
|
||||
|
||||
Most systems support only a subset of these formats. Many devices only support
|
||||
AFTM_U8; the most common format used today is AFMT_S16_LE.
|
||||
Most systems support only a subset of these formats. Many devices only
|
||||
support AFTM_U8; the most common format used today is AFMT_S16_LE.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}[audio device]{setfmt}{format}
|
||||
Used to set the current audio format to \var{format} - see \code{getfmts} for a
|
||||
list. May also be used to return the current audio format - do this by passing
|
||||
an ``audio format'' of \code{AFMT_QUERY}. Returns the audio format that the
|
||||
device was set to, which may not be the requested format.
|
||||
Used to set the current audio format to \var{format}---see
|
||||
\code{getfmts} for a list. May also be used to return the current audio
|
||||
format---do this by passing an ``audio format'' of \code{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.
|
||||
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:
|
||||
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
|
||||
8000---default rate
|
||||
11025---speech recording
|
||||
22050
|
||||
44100 - Audio CD-quality (at 16 bits/sample and 2 channels)
|
||||
96000 - DVD-quality
|
||||
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
|
||||
\code{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 \code{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 \code{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 \code{reset}.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}[audio device]{post}
|
||||
To be used like a lightweight \code{sync}, the \code{post} IOCTL informs the
|
||||
audio device that there is a likely to be a pause in the audio output - ie,
|
||||
after playing a spot sound effect, before waiting for user input, or before
|
||||
doing disk IO.
|
||||
To be used like a lightweight \code{sync}, the \code{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 IO.
|
||||
\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 \code{speed}, \code{channels} and
|
||||
\code{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.
|
||||
Initialise the sound device in one method. \var{samplerate},
|
||||
\var{channels} and \var{format} should be as specified in the
|
||||
\code{speed}, \code{channels} and \code{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}{}
|
||||
|
|
@ -187,12 +190,13 @@ 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.
|
||||
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.
|
||||
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}}
|
||||
|
|
@ -200,8 +204,8 @@ be played without blocking.
|
|||
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.
|
||||
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}{}
|
||||
|
|
@ -214,7 +218,7 @@ Mixer interface
|
|||
This method returns a bitmask specifying the available mixer controls
|
||||
(``Control'' being a specific mixable ``channel'', such as
|
||||
\code{SOUND_MIXER_PCM} or \code{SOUND_MIXER_SYNTH}). This
|
||||
bitmask indicates a subset of all available mixer channels - the
|
||||
bitmask indicates a subset of all available mixer channels---the
|
||||
\code{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:
|
||||
|
|
@ -227,32 +231,34 @@ if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM):
|
|||
\end{verbatim}
|
||||
|
||||
For most purposes, the \code{SOUND_MIXER_VOLUME} (Master volume) and
|
||||
\code{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, \code{SOUND_MIXER_VOLUME} does not exist.
|
||||
\code{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, \code{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
|
||||
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
|
||||
\function{channels} to determine which).
|
||||
|
||||
See the code example for the \function{channels} function for an example of
|
||||
getting data from a bitmask.
|
||||
See the code example for the \function{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 \function{controls} for an example of reading from
|
||||
a bitmask.
|
||||
Returns a bitmask specifying the mixer controls that may be used to
|
||||
record. See the code example for \function{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 of \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.
|
||||
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}
|
||||
|
|
@ -260,9 +266,9 @@ If an unknown channel is specified, \exception{error} is raised.
|
|||
\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.
|
||||
(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
|
||||
|
|
|
|||
Loading…
Reference in New Issue