\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) audiointerface.  OSS is available for a wide range of open-source andcommercial Unices, and is the standard audio interface for Linux andrecent 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 stringdescribing what went wrong. (If \module{ossaudiodev} receives an error from a system call such as\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, itraises \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.  Thisobject supports many file-like methods, such as \method{read()},\method{write()}, and \method{fileno()} (although there are subtledifferences between conventional \UNIX{} read/write semantics and those ofOSS audio devices).  It also supports a number of audio-specificmethods; see below for the complete list of methods. \var{device} is the audio device filename to use.  If it is notspecified, 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 orplayer open at a time, it is a good idea to open the device only for theactivity needed.  Further, some sound cards are half-duplex: they can beopened 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 forcompatibility 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 isnot 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 callthree 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 allthree audio parameters at once.  This is more convenient, but may not beas flexible in all cases. The audio device objects returned by \function{open()} define thefollowing methods and (read-only) attributes: \begin{methoddesc}[audio device]{close}{}Explicitly close the audio device.  When you are done writing to orreading from an audio device, you should explicitly close it.  A closeddevice 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 Pythonstring.  Unlike most \UNIX{} device drivers, OSS audio devices inblocking mode (the default) will block \function{read()} until theentire 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 thenumber of bytes written.  If the audio device is in blocking mode (thedefault), the entire string is always written (again, this is differentfrom usual \UNIX{} device semantics).  If the device is in non-blockingmode, 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: waitsuntil the audio device is able to accept data, writes as much data as itwill accept, and repeats until \var{data} has been completely written.If the device is in blocking mode (the default), this has the sameeffect as \method{write()}; \method{writeall()} is only useful innon-blocking mode.  Has no return value, since the amount of datawritten 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: forexample, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT}ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be usefulwhen 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, thereis 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 thesoundcard.  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 notethat most devices support only a subset of these formats.  Some olderdevices only support \constant{AFMT_U8}; the most common format usedtoday 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 devicewas set to, which may not be the requested format.  May also be used toreturn 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 1indicates monophonic sound, 2 stereophonic.  Some devices may have morethan 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 persecond.  Returns the rate actually set.  Most sound devices don'tsupport 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.  (Thishappens implicitly when the device is closed.)  The OSS documentationrecommends 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 astate where it can accept commands.  The OSS documentation recommendsclosing 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, makingit possible for the device to handle the pause more intelligently.  Youmight use this after playing a spot sound effect, before waiting foruser input, or before doing disk I/O.\end{methoddesc} The following convenience methods combine several ioctls, or one ioctland some simple calculations. \begin{methoddesc}[audio device]{setparameters}  {format, nchannels, samplerate \optional{, strict=False}} Set the key audio sampling parameters---sample format, number ofchannels, 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 tosee if each parameter was actually set to the requested value, andraises \exception{OSSAudioError} if not.  Returns a tuple (\var{format},\var{nchannels}, \var{samplerate}) indicating the parameter values thatwere actually set by the device driver (i.e., the same as the returnvalues 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 beplayed.\end{methoddesc} \begin{methoddesc}[audio device]{obuffree}{}Returns the number of samples that could be queued into the hardwarebuffer 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 touse 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}).  Thisbitmask 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 thefollowing 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 themixer should be flexible when it comes to choosing mixer controls.  Onthe Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does notexist.\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 iseither 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 exampleof getting data from a bitmask.\end{methoddesc} \begin{methoddesc}[mixer device]{reccontrols}{}Returns a bitmask specifying the mixer controls that may be used torecord.  See the code example for \method{controls()} for an example ofreading from a bitmask.\end{methoddesc} \begin{methoddesc}[mixer device]{get}{control}Returns the volume of a given mixer control.  The returned volume is a2-tuple \code{(left_volume,right_volume)}.  Volumes are specified asnumbers from 0 (silent) to 100 (full volume).  If the control ismonophonic, a 2-tuple is still returned, but both volumes arethe 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 wasspecified, 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) arecurrently 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 bitmaskindicating the new recording source (or sources) if successful; raises\exception{IOError} if an invalid source was specified.  To set the currentrecording source to the microphone input: \begin{verbatim}mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)\end{verbatim}\end{methoddesc}