traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Lots of wordsmithing and typographical improvement.

This commit is contained in:
Greg Ward 2003-05-23 02:44:46 +00:00
parent 6492785ee5
commit c316d0d391
1 changed files with 71 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
Doc/lib/libossaudiodev.tex
View File

@ -43,7 +43,7 @@ recent versions of FreeBSD.
{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
the OSS device driver; see \code{<sys/soundcard.h>} on either
Linux or FreeBSD for a listing .}
\end{seealso}
@ -67,13 +67,6 @@ 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
@ -85,6 +78,13 @@ 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.
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}}
@ -98,74 +98,81 @@ not specified, this module first looks in the environment variable
\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:
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, and
\item \method{speed()} to set the sample rate.
\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 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.
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}{}
Returns the file descriptor associated with the device.
Return 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.
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}
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()}.
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}
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.
Write the entire Python string \var{data} to the audio device. If the
device is in blocking mode (the default), behaves identically to
\method{write()}; in non-blocking mode, \method{writeall()} 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. Has
no return value, since the amount of data written is always equal to the
amount of data supplied.
\end{methoddesc}
Simple IOCTLs:
The following methods each map to exactly one
\function{ioctl()} system call. If the underlying \function{ioctl()}
fails, they all raise \exception{IOError}.
\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.
Put the device into non-blocking mode. Once in non-blocking mode, there
is no way to return it to blocking mode.
Raises \exception{IOError} if the IOCTL failed.
Corresponds to the \code{SNDCTL_DSP_NONBLOCK} ioctl.
\end{methoddesc}
\begin{methoddesc}[audio device]{getfmts}{}
Returns a bitmask of the audio output formats supported by the
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. This is the default format on
\file{/dev/audio} and is the format used by Sun .au files.}
{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.}
Association}
\lineii{AFMT_U8}
{Unsigned, 8-bit audio.}
{Unsigned, 8-bit audio}
\lineii{AFMT_S16_LE}
{Unsigned, 16-bit audio, little-endian byte order (as used by
Intel processors)}
@ -173,7 +180,7 @@ soundcard. On a typical Linux system, these formats are:
{Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
PowerPC, Sparc)}
\lineii{AFMT_S8}
{Signed, 8 bit audio.}
{Signed, 8 bit audio}
\lineii{AFMT_U16_LE}
{Signed, 16-bit little-endian audio}
\lineii{AFMT_U16_BE}
@ -182,14 +189,19 @@ soundcard. On a typical Linux system, these formats are:
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}.
Corresponds to the \code{SNDCTL_DSP_GETFMTS} ioctl.
\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.
Try to set the current audio format to \var{format}---see
\method{getfmts()} for a list. Return 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}.
Corresponds to the \code{SNDCTL_DSP_SETFMT} ioctl.
\end{methoddesc}
\begin{methoddesc}[audio device]{channels}{num_channels}
@ -200,31 +212,32 @@ 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
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}
\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}
\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}
\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