[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex,1.7,1.8
gward@users.sourceforge.net
gward@users.sourceforge.net
Thu, 22 May 2003 19:44:52 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv15847
Modified Files:
libossaudiodev.tex
Log Message:
Lots of wordsmithing and typographical improvement.
Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** libossaudiodev.tex 3 May 2003 19:45:47 -0000 1.7
--- libossaudiodev.tex 23 May 2003 02:44:46 -0000 1.8
***************
*** 44,48 ****
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}
--- 44,48 ----
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}
***************
*** 68,78 ****
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
--- 68,71 ----
***************
*** 86,89 ****
--- 79,89 ----
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}
***************
*** 99,111 ****
\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
--- 99,112 ----
\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 are returned by \function{open()} define the
***************
*** 113,170 ****
\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
--- 114,177 ----
\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. 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}
! 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}{}
! Put the device into non-blocking mode. Once in non-blocking mode, there
! is no way to return it to blocking mode.
! Corresponds to the \code{SNDCTL_DSP_NONBLOCK} ioctl.
\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
***************
*** 174,178 ****
PowerPC, Sparc)}
\lineii{AFMT_S8}
! {Signed, 8 bit audio.}
\lineii{AFMT_U16_LE}
{Signed, 16-bit little-endian audio}
--- 181,185 ----
PowerPC, Sparc)}
\lineii{AFMT_S8}
! {Signed, 8 bit audio}
\lineii{AFMT_U16_LE}
{Signed, 16-bit little-endian audio}
***************
*** 183,194 ****
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}
--- 190,206 ----
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}
! 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}
***************
*** 201,216 ****
\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
--- 213,229 ----
\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}{}
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
***************
*** 219,223 ****
\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
--- 232,236 ----
\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
***************
*** 225,229 ****
\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
--- 238,242 ----
\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