diff options
Diffstat (limited to 'Doc/lib/libossaudiodev.tex')
| -rw-r--r-- | Doc/lib/libossaudiodev.tex | 401 |
1 files changed, 0 insertions, 401 deletions
diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex deleted file mode 100644 index 4c19aaf..0000000 --- a/Doc/lib/libossaudiodev.tex +++ /dev/null @@ -1,401 +0,0 @@ -\section{\module{ossaudiodev} --- - Access to OSS-compatible audio devices} - -\declaremodule{builtin}{ossaudiodev} -\platform{Linux, FreeBSD} -\modulesynopsis{Access to OSS-compatible audio devices.} - -\versionadded{2.3} - -This module allows you to access the OSS (Open Sound System) audio -interface. OSS is available for a wide range of open-source and -commercial Unices, and is the standard audio interface for Linux and -recent versions of FreeBSD. - -% Things will get more complicated for future Linux versions, since -% ALSA is in the standard kernel as of 2.5.x. Presumably if you -% use ALSA, you'll have to make sure its OSS compatibility layer -% is active to use ossaudiodev, but you're gonna need it for the vast -% majority of Linux audio apps anyways. -% -% Sounds like things are also complicated for other BSDs. In response -% to my python-dev query, Thomas Wouters said: -% -% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial -% > OSS installation manual tells you to remove references to OSS/Free from the -% > kernel :) -% -% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes -% from its <soundcard.h>: -% > * WARNING! WARNING! -% > * This is an OSS (Linux) audio emulator. -% > * Use the Native NetBSD API for developing new code, and this -% > * only for compiling Linux programs. -% -% There's also an ossaudio manpage on OpenBSD that explains things -% further. Presumably NetBSD and OpenBSD have a different standard -% audio interface. That's the great thing about standards, there are so -% many to choose from ... ;-) -% -% This probably all warrants a footnote or two, but I don't understand -% things well enough right now to write it! --GPW - -\begin{seealso} -\seetitle[http://www.opensound.com/pguide/oss.pdf] - {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 \code{<sys/soundcard.h>} on either - Linux or FreeBSD for a listing .} -\end{seealso} - -\module{ossaudiodev} defines the following variables and functions: - -\begin{excdesc}{OSSAudioError} -This exception is raised on certain errors. The argument is a string -describing what went wrong. - -(If \module{ossaudiodev} receives an error from a system call such as -\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it -raises \exception{IOError}. Errors detected directly by -\module{ossaudiodev} result in \exception{OSSAudioError}.) - -(For backwards compatibility, the exception class is also available as -\code{ossaudiodev.error}.) -\end{excdesc} - -\begin{funcdesc}{open}{\optional{device, }mode} -Open an audio device and return an OSS audio device object. This -object supports many file-like methods, such as \method{read()}, -\method{write()}, and \method{fileno()} (although there are subtle -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. - -\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 -\file{/dev/dsp}. - -\var{mode} is one of \code{'r'} for read-only (record) access, -\code{'w'} for write-only (playback) access and \code{'rw'} for both. -Since many sound cards 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 sound cards 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}} -Open a mixer device and return an OSS mixer device object. -\var{device} is the mixer device filename to use. If it is -not specified, this module first looks in the environment variable -\envvar{MIXERDEV} for a device to use. If not found, it falls back to -\file{/dev/mixer}. - -\end{funcdesc} - -\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 returned by \function{open()} define the -following methods and (read-only) attributes: - -\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: 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. -If the device is in blocking mode (the default), this has the same -effect as \method{write()}; \method{writeall()} is only useful in -non-blocking mode. 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. The correspondence is obvious: for -example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT} -ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful -when consulting the OSS documentation). 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. -\end{methoddesc} - -\begin{methoddesc}[audio device]{getfmts}{} -Return a bitmask of the audio output formats supported by the -soundcard. Some of the formats supported by OSS 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} - {Signed, 16-bit audio, little-endian byte order (as used by - Intel processors)} -\lineii{AFMT_S16_BE} - {Signed, 16-bit audio, big-endian byte order (as used by 68k, - PowerPC, Sparc)} -\lineii{AFMT_S8} - {Signed, 8 bit audio} -\lineii{AFMT_U16_LE} - {Unsigned, 16-bit little-endian audio} -\lineii{AFMT_U16_BE} - {Unsigned, 16-bit big-endian audio} -\end{tableii} -Consult the OSS documentation for a full list of audio formats, and note -that most devices support only a subset of these formats. Some older -devices only support \constant{AFMT_U8}; the most common format used -today is \constant{AFMT_S16_LE}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{setfmt}{format} -Try to set the current audio format to \var{format}---see -\method{getfmts()} for a list. Returns 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}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{channels}{nchannels} -Set the number of output channels to \var{nchannels}. 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} -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}{} -Wait until the sound device has played every byte in its buffer. (This -happens implicitly when the device is closed.) The OSS documentation -recommends closing and re-opening the device rather than using -\method{sync()}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{reset}{} -Immediately stop playing or recording and return 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}{} -Tell the driver that there is likely to be a pause in the output, making -it possible for the device to handle the pause more intelligently. You -might use this after playing a spot sound effect, before waiting for -user input, or before doing disk I/O. -\end{methoddesc} - -The following convenience methods combine several ioctls, or one ioctl -and some simple calculations. - -\begin{methoddesc}[audio device]{setparameters} - {format, nchannels, samplerate \optional{, strict=False}} - -Set the key audio sampling parameters---sample format, number of -channels, and sampling rate---in one method call. \var{format}, -\var{nchannels}, and \var{samplerate} should be as specified in the -\method{setfmt()}, \method{channels()}, and \method{speed()} -methods. If \var{strict} is true, \method{setparameters()} checks to -see if each parameter was actually set to the requested value, and -raises \exception{OSSAudioError} if not. Returns a tuple (\var{format}, -\var{nchannels}, \var{samplerate}) indicating the parameter values that -were actually set by the device driver (i.e., the same as the return -values of \method{setfmt()}, \method{channels()}, and \method{speed()}). - -For example, -\begin{verbatim} - (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate) -\end{verbatim} -is equivalent to -\begin{verbatim} - fmt = dsp.setfmt(fmt) - channels = dsp.channels(channels) - rate = dsp.rate(channels) -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[audio device]{bufsize}{} -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. -\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} - -Audio device objects also support several read-only attributes: - -\begin{memberdesc}[audio device]{closed}{} -Boolean indicating whether the device has been closed. -\end{memberdesc} - -\begin{memberdesc}[audio device]{name}{} -String containing the name of the device file. -\end{memberdesc} - -\begin{memberdesc}[audio device]{mode}{} -The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}. -\end{memberdesc} - - -\subsection{Mixer Device Objects \label{mixer-device-objects}} - -The mixer object provides two file-like methods: - -\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 \exception{IOError}. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{fileno}{} -Returns the file handle number of the open mixer device file. -\end{methoddesc} - -The remaining methods are specific to audio mixing: - -\begin{methoddesc}[mixer device]{controls}{} -This method returns a bitmask specifying the available mixer controls -(``Control'' being a specific mixable ``channel'', such as -\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This -bitmask indicates a subset of all available mixer controls---the -\constant{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: - -\begin{verbatim} -mixer=ossaudiodev.openmixer() -if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM): - # PCM is supported - ... code ... -\end{verbatim} - -For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and -\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the -mixer should be flexible when it comes to choosing mixer controls. On -the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not -exist. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{stereocontrols}{} -Returns a bitmask indicating stereo mixer controls. If a bit is set, -the corresponding control is stereo; if it is unset, the control is -either monophonic or not supported by the mixer (use in combination with -\method{controls()} to determine which). - -See the code example for the \method{controls()} 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 \method{controls()} for an example of -reading from a bitmask. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{get}{control} -Returns the volume of a given mixer control. The returned volume is a -2-tuple \code{(left_volume,right_volume)}. Volumes are specified as -numbers from 0 (silent) to 100 (full volume). If the control is -monophonic, a 2-tuple is still returned, but both volumes are -the same. - -Raises \exception{OSSAudioError} if an invalid control was is specified, -or \exception{IOError} if an unsupported control is specified. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{set}{control, (left, right)} -Sets the volume for a given mixer control 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{OSSAudioError} if an invalid mixer control was -specified, or if the specified volumes were out-of-range. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{get_recsrc}{} -This method returns a bitmask indicating which control(s) are -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 -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: - -\begin{verbatim} -mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC) -\end{verbatim} -\end{methoddesc} - - - |