[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex,1.1,1.2
gward@users.sourceforge.net
gward@users.sourceforge.net
Sun, 09 Mar 2003 15:57:36 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv20251
Modified Files:
libossaudiodev.tex
Log Message:
Wrap all paragraphs to 72 columns.
Two spaces between sentences.
Fix em-dashes -- should be "---" not " - ".
Spelling fix.
Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** libossaudiodev.tex 9 Mar 2003 23:34:52 -0000 1.1
--- libossaudiodev.tex 9 Mar 2003 23:57:34 -0000 1.2
***************
*** 6,15 ****
\modulesynopsis{Access to OSS-compatible audio hardware.}
! % 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
get a feel for the interface is from the Open Sound System official
documentation:
--- 6,15 ----
\modulesynopsis{Access to OSS-compatible audio hardware.}
! % 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
get a feel for the interface is from the Open Sound System official
documentation:
***************
*** 17,52 ****
\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>}.
\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.
\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}.
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.
\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'}.
\end{funcdesc}
--- 17,53 ----
\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>}.
\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.
\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}.
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.
\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'}.
\end{funcdesc}
***************
*** 56,60 ****
Setting up the device
! To set up the device, three functions must be called in the correct sequence:
\code{setfmt} to set the output format,
--- 57,62 ----
Setting up the device
! To set up the device, three functions must be called in the correct
! sequence:
\code{setfmt} to set the output format,
***************
*** 66,96 ****
\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 \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.
\end{methoddesc}
--- 68,98 ----
\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 \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.
\end{methoddesc}
***************
*** 98,103 ****
\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.
--- 100,105 ----
\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.
***************
*** 105,173 ****
\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:
! 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.
\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.
\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.
\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
\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}.
\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}.
\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.
\end{methoddesc}
--- 107,176 ----
\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:
! 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.
\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.
\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.
\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
\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}.
\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}.
\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---i.e., after playing a spot sound effect, before waiting for
! user input, or before doing disk IO.
\end{methoddesc}
***************
*** 175,184 ****
\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.
\end{methoddesc}
--- 178,187 ----
\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.
\end{methoddesc}
***************
*** 188,197 ****
\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}
--- 191,201 ----
\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}
***************
*** 201,206 ****
\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}
--- 205,210 ----
\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}
***************
*** 214,220 ****
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,
for example, the current mixer object supports a PCM mixer, use the
following Python code:
--- 218,224 ----
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,
for example, the current mixer object supports a PCM mixer, use the
following Python code:
***************
*** 228,257 ****
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.
\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
\function{channels} to determine which).
! 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.
\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.
If an unknown channel is specified, \exception{error} is raised.
--- 232,263 ----
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.
\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
\function{channels} to determine which).
! 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.
\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.
If an unknown channel is specified, \exception{error} is raised.
***************
*** 261,270 ****
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.
Raises \exception{IOError} if an invalid mixer channel was specified;
! \exception{TypeError} if the argument format was incorrect, and
\exception{error} if the specified volumes were out-of-range.
\end{methoddesc}
--- 267,276 ----
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.
Raises \exception{IOError} if an invalid mixer channel was specified;
! \exception{TypeError} if the argument format was incorrect, and
\exception{error} if the specified volumes were out-of-range.
\end{methoddesc}
***************
*** 276,282 ****
\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:
--- 282,288 ----
\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: