Audio Device Objects¶

Before you can write to or read from an audio device, you must call threemethods in the correct order:

1. setfmt() to set the output format

2. channels() to set the number of channels

3. speed() to set the sample rate

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:

oss_audio_device.close()¶

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.

oss_audio_device.fileno()¶

Return the file descriptor associated with the device.

oss_audio_device.read(size)¶

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.

oss_audio_device.write(data)¶

Write abytes-like objectdata to the audio device and return thenumber of bytes written. If the audio device is in blocking mode (thedefault), the entire data is always written (again, this is different fromusual Unix device semantics). If the device is in non-blocking mode, somedata may not be written—seewriteall().

Changed in version 3.5:Writablebytes-like object is now accepted.

oss_audio_device.writeall(data)¶

Write abytes-like objectdata to the audio device: waits untilthe audio device is able to accept data, writes as much data as it willaccept, and repeats untildata has been completely written. If the deviceis in blocking mode (the default), this has the same effect aswrite();writeall() is only useful in non-blocking mode. Hasno return value, since the amount of data written is always equal to theamount of data supplied.

Changed in version 3.5:Writablebytes-like object is now accepted.

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.

oss_audio_device.nonblock()¶

Put the device into non-blocking mode. Once in non-blocking mode, there is noway to return it to blocking mode.

oss_audio_device.getfmts()¶

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.

oss_audio_device.setfmt(format)¶

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.

oss_audio_device.channels(nchannels)¶

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.

oss_audio_device.speed(samplerate)¶

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)

oss_audio_device.sync()¶

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().

oss_audio_device.reset()¶

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().

oss_audio_device.post()¶

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.

oss_audio_device.setparameters(format,nchannels,samplerate[,strict=False])¶

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)

oss_audio_device.bufsize()¶

Returns the size of the hardware buffer, in samples.

oss_audio_device.obufcount()¶

Returns the number of samples that are in the hardware buffer yet to be played.

oss_audio_device.obuffree()¶

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:

oss_audio_device.closed¶

Boolean indicating whether the device has been closed.

oss_audio_device.name¶

String containing the name of the device file.

oss_audio_device.mode¶

The I/O mode for the file, either"r","rw", or"w".

Mixer Device Objects¶

The mixer object provides two file-like methods:

oss_mixer_device.close()¶

This method closes the open mixer device file. Any further attempts to use themixer after this file is closed will raise anOSError.

oss_mixer_device.fileno()¶

Returns the file handle number of the open mixer device file.

The remaining methods are specific to audio mixing:

oss_mixer_device.controls()¶

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.

oss_mixer_device.stereocontrols()¶

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.

oss_mixer_device.reccontrols()¶

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.

oss_mixer_device.get(control)¶

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 is specified, orOSError if an unsupported control is specified.

oss_mixer_device.set(control,(left,right))¶

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.

oss_mixer_device.get_recsrc()¶

This method returns a bitmask indicating which control(s) are currently beingused as a recording source.

oss_mixer_device.set_recsrc(bitmask)¶

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)