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 isthe standard audio interface for Linux and recent versions of FreeBSD.
See also
The module defines a large number of constants supplied by the OSS devicedriver; see<sys/soundcard.h> on either Linux or FreeBSD for a listing.
ossaudiodev defines the following variables and functions:
This exception is raised on certain errors. The argument is a string describingwhat went wrong.
(Ifossaudiodev receives an error from a system call such asopen(),write(), orioctl(), it raisesOSError.Errors detected directly byossaudiodev result inOSSAudioError.)
(For backwards compatibility, the exception class is also available asossaudiodev.error.)
Open an audio device and return an OSS audio device object. This objectsupports many file-like methods, such asread(),write(), andfileno() (although there are subtle differences between conventional Unixread/write semantics and those of OSS audio devices). It also supports a numberof audio-specific methods; see below for the complete list of methods.
device is the audio device filename to use. If it is not specified, thismodule first looks in the environment variableAUDIODEV for a deviceto use. If not found, it falls back to/dev/dsp.
mode is one of'r' for read-only (record) access,'w' forwrite-only (playback) access and'rw' for both. Since many sound cardsonly allow one process to have the recorder or player open at a time, it is agood idea to open the device only for the activity needed. Further, somesound cards are half-duplex: they can be opened for reading or writing, butnot both at once.
Note the unusual calling syntax: thefirst argument is optional, and thesecond is required. This is a historical artifact for compatibility with theolderlinuxaudiodev module whichossaudiodev supersedes.
Open a mixer device and return an OSS mixer device object.device is themixer device filename to use. If it is not specified, this module first looksin the environment variableMIXERDEV for a device to use. If notfound, it falls back to/dev/mixer.
Before you can write to or read from an audio device, you must call threemethods in the correct order:
Alternately, you can use thesetparameters() method to set all three audioparameters at once. This is more convenient, but may not be as flexible in allcases.
The audio device objects returned byopen() define the following methodsand (read-only) attributes:
Explicitly close the audio device. When you are done writing to or reading froman audio device, you should explicitly close it. A closed device cannot be usedagain.
Return the file descriptor associated with the device.
Readsize bytes from the audio input and return them as a Python string.Unlike most Unix device drivers, OSS audio devices in blocking mode (thedefault) will blockread() until the entire requested amount of data isavailable.
Write the Python stringdata to the audio device and return the number ofbytes written. If the audio device is in blocking mode (the default), theentire string is always written (again, this is different from usual Unix devicesemantics). If the device is in non-blocking mode, some data may not be written—seewriteall().
Write the entire Python stringdata to the audio device: waits until the audiodevice is able to accept data, writes as much data as it will accept, andrepeats untildata has been completely written. If the device is in blockingmode (the default), this has the same effect aswrite();writeall()is only useful in non-blocking mode. Has no return value, since the amount ofdata written is always equal to the amount of data supplied.
Changed in version 3.2:Audio device objects also support the context manager protocol, i.e. they canbe used in awith statement.
The following methods each map to exactly oneioctl() system call. Thecorrespondence is obvious: for example,setfmt() corresponds to theSNDCTL_DSP_SETFMT ioctl, andsync() toSNDCTL_DSP_SYNC (this canbe useful when consulting the OSS documentation). If the underlyingioctl() fails, they all raiseOSError.
Put the device into non-blocking mode. Once in non-blocking mode, there is noway to return it to blocking mode.
Return a bitmask of the audio output formats supported by the soundcard. Someof the formats supported by OSS are:
| Format | Description |
|---|---|
| AFMT_MU_LAW | a logarithmic encoding (used by Sun.aufiles and/dev/audio) |
| AFMT_A_LAW | a logarithmic encoding |
| AFMT_IMA_ADPCM | a 4:1 compressed format defined by theInteractive Multimedia Association |
| AFMT_U8 | Unsigned, 8-bit audio |
| AFMT_S16_LE | Signed, 16-bit audio, little-endian byteorder (as used by Intel processors) |
| AFMT_S16_BE | Signed, 16-bit audio, big-endian byte order(as used by 68k, PowerPC, Sparc) |
| AFMT_S8 | Signed, 8 bit audio |
| AFMT_U16_LE | Unsigned, 16-bit little-endian audio |
| AFMT_U16_BE | Unsigned, 16-bit big-endian audio |
Consult the OSS documentation for a full list of audio formats, and note thatmost devices support only a subset of these formats. Some older devices onlysupportAFMT_U8; the most common format used today isAFMT_S16_LE.
Try to set the current audio format toformat—seegetfmts() for alist. Returns the audio format that the device was set to, which may not be therequested format. May also be used to return the current audio format—do thisby passing an “audio format” ofAFMT_QUERY.
Set the number of output channels tonchannels. A value of 1 indicatesmonophonic sound, 2 stereophonic. Some devices may have more than 2 channels,and some high-end devices may not support mono. Returns the number of channelsthe device was set to.
Try to set the audio sampling rate tosamplerate samples per second. Returnsthe rate actually set. Most sound devices don’t support arbitrary samplingrates. Common rates are:
| Rate | Description |
|---|---|
| 8000 | default rate for/dev/audio |
| 11025 | speech recording |
| 22050 | |
| 44100 | CD quality audio (at 16 bits/sample and 2channels) |
| 96000 | DVD quality audio (at 24 bits/sample) |
Wait until the sound device has played every byte in its buffer. (This happensimplicitly when the device is closed.) The OSS documentation recommends closingand re-opening the device rather than usingsync().
Immediately stop playing or recording and return the device to a state where itcan accept commands. The OSS documentation recommends closing and re-openingthe device after callingreset().
Tell the driver that there is likely to be a pause in the output, making itpossible for the device to handle the pause more intelligently. You might usethis after playing a spot sound effect, before waiting for user input, or beforedoing disk I/O.
The following convenience methods combine several ioctls, or one ioctl and somesimple calculations.
Set the key audio sampling parameters—sample format, number of channels, andsampling rate—in one method call.format,nchannels, andsamplerateshould be as specified in thesetfmt(),channels(), andspeed() methods. Ifstrict is true,setparameters() checks tosee if each parameter was actually set to the requested value, and raisesOSSAudioError if not. Returns a tuple (format,nchannels,samplerate) indicating the parameter values that were actually set by thedevice driver (i.e., the same as the return values ofsetfmt(),channels(), andspeed()).
For example,
(fmt,channels,rate)=dsp.setparameters(fmt,channels,rate)
is equivalent to
fmt=dsp.setfmt(fmt)channels=dsp.channels(channels)rate=dsp.rate(rate)
Returns the size of the hardware buffer, in samples.
Returns the number of samples that are in the hardware buffer yet to be played.
Returns the number of samples that could be queued into the hardware buffer tobe played without blocking.
Audio device objects also support several read-only attributes:
Boolean indicating whether the device has been closed.
String containing the name of the device file.
The I/O mode for the file, either"r","rw", or"w".
The mixer object provides two file-like methods:
This method closes the open mixer device file. Any further attempts to use themixer after this file is closed will raise anOSError.
Returns the file handle number of the open mixer device file.
Changed in version 3.2:Mixer objects also support the context manager protocol.
The remaining methods are specific to audio mixing:
This method returns a bitmask specifying the available mixer controls (“Control”being a specific mixable “channel”, such asSOUND_MIXER_PCM orSOUND_MIXER_SYNTH). This bitmask indicates a subset of all availablemixer controls—theSOUND_MIXER_* constants defined at module level.To determine if, for example, the current mixer object supports a PCM mixer, usethe following Python code:
mixer=ossaudiodev.openmixer()ifmixer.controls()&(1<<ossaudiodev.SOUND_MIXER_PCM):# PCM is supported...code...
For most purposes, theSOUND_MIXER_VOLUME (master volume) andSOUND_MIXER_PCM controls should suffice—but code that uses the mixershould be flexible when it comes to choosing mixer controls. On the GravisUltrasound, for example,SOUND_MIXER_VOLUME does not exist.
Returns a bitmask indicating stereo mixer controls. If a bit is set, thecorresponding control is stereo; if it is unset, the control is eithermonophonic or not supported by the mixer (use in combination withcontrols() to determine which).
See the code example for thecontrols() function for an example of gettingdata from a bitmask.
Returns a bitmask specifying the mixer controls that may be used to record. Seethe code example forcontrols() for an example of reading from a bitmask.
Returns the volume of a given mixer control. The returned volume is a 2-tuple(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 stillreturned, but both volumes are the same.
RaisesOSSAudioError if an invalid control was is specified, orOSError if an unsupported control is specified.
Sets the volume for a given mixer control to(left,right).left andright must be ints and between 0 (silent) and 100 (full volume). Onsuccess, the new volume is returned as a 2-tuple. Note that this may not beexactly the same as the volume specified, because of the limited resolution ofsome soundcard’s mixers.
RaisesOSSAudioError if an invalid mixer control was specified, or if thespecified volumes were out-of-range.
This method returns a bitmask indicating which control(s) are currently beingused as a recording source.
Call this function to specify a recording source. Returns a bitmask indicatingthe new recording source (or sources) if successful; raisesOSError if aninvalid source was specified. To set the current recording source to themicrophone input:
mixer.setrecsrc(1<<ossaudiodev.SOUND_MIXER_MIC)
22.8.sndhdr — Determine type of sound file
Enter search terms or a module, class or function name.
