ossaudiodev —- Access to OSS-compatible audio devices

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.

在 3.3 版更改: Operations in this module now raise OSError where IOErrorwas raised.

参见

• Open Sound System Programmer's Guide
• the official documentation for the OSS C API

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:

• exception ossaudiodev.OSSAudioError
• This exception is raised on certain errors. The argument is a string describingwhat went wrong.

(If ossaudiodev receives an error from a system call such asopen(), write(), or ioctl(), it raises OSError.Errors detected directly by ossaudiodev result in OSSAudioError.)

(For backwards compatibility, the exception class is also available asossaudiodev.error.)

• ossaudiodev.open(mode)
• ossaudiodev.open(device, mode)
• Open an audio device and return an OSS audio device object. This objectsupports many file-like methods, such as read(), 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 variable AUDIODEV 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: the first argument is optional, and thesecond is required. This is a historical artifact for compatibility with theolder linuxaudiodev module which ossaudiodev supersedes.

• ossaudiodev.openmixer([device])
• 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 variable MIXERDEV for a device to use. If notfound, it falls back to /dev/mixer.

Audio Device Objects

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

• setfmt() to set the output format

• channels() to set the number of channels

• speed() to set the sample rate

Alternately, you can use the setparameters() 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 by open() 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.

• ossaudio_device.read(_size)

• Read size 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 block read() until the entire requested amount of data isavailable.

• ossaudio_device.write(_data)

• Write a bytes-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—-see writeall().

在 3.5 版更改: 现在支持可写的 字节类对象。

• ossaudio_device.writeall(_data)
• Write a bytes-like objectdata to the audio device: waits untilthe audio device is able to accept data, writes as much data as it willaccept, and repeats until data 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.

在 3.5 版更改: 现在支持可写的 字节类对象。

在 3.2 版更改: Audio device objects also support the context management protocol, i.e. they canbe used in a with statement.

The following methods each map to exactly one ioctl() system call. Thecorrespondence is obvious: for example, setfmt() corresponds to theSNDCTL_DSP_SETFMT ioctl, and sync() to SNDCTL_DSP_SYNC (this canbe useful when consulting the OSS documentation). If the underlyingioctl() fails, they all raise OSError.

• 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:

文件格式

描述

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 onlysupport AFMT_U8; the most common format used today isAFMT_S16_LE.

• ossaudio_device.setfmt(_format)

• Try to set the current audio format to format—-see getfmts() 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" of AFMT_QUERY.

• ossaudio_device.channels(_nchannels)

• Set the number of output channels to nchannels. 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.

• ossaudio_device.speed(_samplerate)

• Try to set the audio sampling rate to samplerate samples per second. Returnsthe rate actually set. Most sound devices don't support arbitrary samplingrates. Common rates are:

采样率

描述

8000

/dev/audio 的默认采样率

11025

语音录音

22050

44100

CD品质的音频（16位采样和2通道）

96000

DVD品质的音频（24位采样）

• 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 using sync().

• 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 calling reset().

• 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.

• ossaudio_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, and samplerate_should be as specified in the setfmt(), channels(), andspeed() methods. If _strict 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 of setfmt(),channels(), and speed()).

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 an OSError.

• oss_mixer_device.fileno()

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

在 3.2 版更改: Mixer objects also support the context management protocol.

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 as SOUNDMIXER_PCM orSOUND_MIXER_SYNTH). This bitmask indicates a subset of all availablemixer controls—-the SOUND_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()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
    # PCM is supported
    ... code ...

For most purposes, the SOUND_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 the controls() 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 for controls() for an example of reading from a bitmask.

• ossmixer_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.

Raises OSSAudioError if an invalid control is specified, orOSError if an unsupported control is specified.

• ossmixer_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.

Raises OSSAudioError 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.

• ossmixer_device.set_recsrc(_bitmask)

• Call this function to specify a recording source. Returns a bitmask indicatingthe new recording source (or sources) if successful; raises OSError if aninvalid source was specified. To set the current recording source to themicrophone input:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)