Wrap all paragraphs to 72 columns.
Two spaces between sentences.
Fix em-dashes -- should be "---" not " - ".
Spelling fix.
diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
index 2f89173..47a8d56 100644
--- a/Doc/lib/libossaudiodev.tex
+++ b/Doc/lib/libossaudiodev.tex
@@ -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}.
+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}.
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
+\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 @@
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
@@ -65,121 +67,122 @@
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.
+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.
+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 @@
\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 @@
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}{}
@@ -213,9 +217,9 @@
\begin{methoddesc}[mixer device]{controls}{}
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
-\code{SOUND_MIXER_*} constants defined at module level. To determine if,
+\code{SOUND_MIXER_PCM} or \code{SOUND_MIXER_SYNTH}). This
+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 @@
\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.
+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.
If an unknown channel is specified, \exception{error} is raised.
\end{methoddesc}
@@ -260,12 +266,12 @@
\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
+\exception{TypeError} if the argument format was incorrect, and
\exception{error} if the specified volumes were out-of-range.
\end{methoddesc}
@@ -275,9 +281,9 @@
\end{methoddesc}
\begin{methoddesc}[mixer device]{set_recsrc}{bitmask}
-Call this function to specify a recording source. Returns a 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
+\exception{IOError} if an invalid source was specified. To set the current
recording source to the microphone input:
\begin{verbatim}