diff options
| -rw-r--r-- | Doc/lib/libossaudiodev.tex | 240 |
1 files changed, 123 insertions, 117 deletions
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 @@ 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 @@ -65,121 +67,122 @@ 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. +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: - -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. +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. +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}{} @@ -213,9 +217,9 @@ Mixer interface \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 @@ 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. +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 @@ 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 +\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 @@ currently being used as a recording source. \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} |