ossaudiodev — Access to OSS-compatible audio devices访问OSS兼容的音频设备

Deprecated since version 3.11: The ossaudiodev module is deprecated (see PEP 594 for details).ossaudiodev模块已弃用（详见PEP 594）。

---

This module allows you to access the OSS (Open Sound System) audio interface. 此模块允许您访问OSS（开放式音响系统）音频接口。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.OSS可用于各种开源和商业Unice，是Linux和最新版本FreeBSD的标准音频接口。

Changed in version 3.3:版本3.3中更改： Operations in this module now raise OSError where IOError was raised.此模块中的操作现在在引发IOError的位置引发OSError。

See also

Open Sound System Programmer’s Guide开放式音响系统程序员指南

the official documentation for the OSS C APIOSS C API的官方文档

The module defines a large number of constants supplied by the OSS device driver; see <sys/soundcard.h> on either Linux or FreeBSD for a listing.该模块定义了OSS设备驱动程序提供的大量常量；有关列表，请参阅Linux或FreeBSD上的<sys/soundcard.h>。

ossaudiodev defines the following variables and functions:定义以下变量和函数：

exceptionossaudiodev.OSSAudioError

This exception is raised on certain errors. 在出现某些错误时会引发此异常。The argument is a string describing what went wrong.该参数是一个字符串，描述出了什么问题。

(If ossaudiodev receives an error from a system call such as open(), write(), or ioctl(), it raises OSError. （如果ossaudiodev从系统调用（例如open()、write()或ioctl()）收到错误，则会引发OSError。Errors detected directly by ossaudiodev result in OSSAudioError.)ossaudiodev直接检测到的错误将导致OSSAudioError。）

(For backwards compatibility, the exception class is also available as ossaudiodev.error.)（为了向后兼容，异常类也可用作ossaudiodev.error。）

ossaudiodev.open(mode)

ossaudiodev.open(device, mode)

Open an audio device and return an OSS audio device object. 打开音频设备并返回OSS音频设备对象。This object supports many file-like methods, such as read(), write(), and fileno() (although there are subtle differences between conventional Unix read/write semantics and those of OSS audio devices). 该对象支持许多类似文件的方法，例如read()、write()和fileno()（尽管传统的Unix读/写语义与OSS音频设备之间存在细微的差异）。It also supports a number of audio-specific methods; see below for the complete list of methods.它还支持许多特定于音频的方法；有关方法的完整列表，请参阅下文。

device is the audio device filename to use. 要使用的音频设备文件名。If it is not specified, this module first looks in the environment variable AUDIODEV for a device to use. 如果未指定，则该模块首先在环境变量AUDIODEV中查找要使用的设备。If not found, it falls back to /dev/dsp.如果找不到，则返回到/dev/dsp。

mode is one of 'r' for read-only (record) access, 'w' for write-only (playback) access and 'rw' for both. mode是'r'表示只读（记录）访问，'w'表示只写（播放）访问，而'rw'表示两者。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 first argument is optional, and the second is required. 注意异常的调用语法：第一个参数是可选的，第二个参数是必需的。This is a historical artifact for compatibility with the older linuxaudiodev module which ossaudiodev supersedes.这是一个与ossaudiodev取代的旧linuxaudiodev模块兼容的历史工件。

ossaudiodev.openmixer([device])

Open a mixer device and return an OSS mixer device object. 打开混音器设备并返回OSS混音器设备对象。device is the mixer device filename to use. device是要使用的混音器设备文件名。If it is not specified, this module first looks in the environment variable MIXERDEV for a device to use. 如果未指定，则该模块首先在环境变量MIXERDEV中查找要使用的设备。If not found, it falls back to /dev/mixer.如果找不到，则返回到/dev/mixer。

Audio Device Objects音频设备对象

Before you can write to or read from an audio device, you must call three methods 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 the setparameters() method to set all three audio parameters at once. 或者，可以使用setparameters()方法同时设置所有三个音频参数。This is more convenient, but may not be as flexible in all cases.这更方便，但在所有情况下可能都不那么灵活。

The audio device objects returned by open() define the following methods and (read-only) attributes:open()返回的音频设备对象定义了以下方法和（只读）属性：

oss_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.关闭的设备不能再次使用。

oss_audio_device.fileno()

Return the file descriptor associated with the device.返回与设备关联的文件描述符。

oss_audio_device.read(size)

Read size bytes from the audio input and return them as a Python string. 从音频输入中读取size字节，并将其作为Python字符串返回。Unlike most Unix device drivers, OSS audio devices in blocking mode (the default) will block read() until the entire requested amount of data is available.与大多数Unix设备驱动程序不同，处于阻塞模式（默认）的OSS音频设备将阻塞read()，直到请求的全部数据可用。

oss_audio_device.write(data)

Write a bytes-like object data to the audio device and return the number of bytes written. 将类字节对象data写入音频设备，并返回写入的字节数。If the audio device is in blocking mode (the default), the entire data is always written (again, this is different from usual Unix device semantics). 如果音频设备处于阻塞模式（默认），则始终写入整个数据（同样，这与通常的Unix设备语义不同）。If the device is in non-blocking mode, some data may not be written—see writeall().如果设备处于非阻塞模式，某些数据可能无法写入，请参阅writeall()。

Changed in version 3.5:版本3.5中更改： Writable bytes-like object is now accepted.可写的类字节对象现在被接受。

oss_audio_device.writeall(data)

Write a bytes-like object 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 data has been completely written. 向音频设备写入类字节对象data：等待音频设备能够接受数据，尽可能多地写入数据，并重复直到数据完全写入。If the device is in blocking mode (the default), this has the same effect as write(); writeall() is only useful in non-blocking mode. 如果设备处于阻塞模式（默认），则这与write()具有相同的效果；writeall()仅在非阻塞模式下有用。Has no return value, since the amount of data written is always equal to the amount of data supplied.没有返回值，因为写入的数据量始终等于提供的数据量。

Changed in version 3.5:版本3.5中更改： Writable bytes-like object is now accepted.可写的类字节对象现在被接受。

Changed in version 3.2:版本3.2中更改： Audio device objects also support the context management protocol, i.e. they can be used in a with statement.音频设备对象还支持上下文管理协议，即可以在with语句中使用。

The following methods each map to exactly one ioctl() system call. 以下方法每个都映射到一个ioctl()系统调用。The correspondence is obvious: for example, setfmt() corresponds to the SNDCTL_DSP_SETFMT ioctl, and sync() to SNDCTL_DSP_SYNC (this can be useful when consulting the OSS documentation). 对应关系很明显：例如，setfmt()对应于SNDCTL_DSP_SETFMT ioctl，sync()对应SNDCTL_DSP_SYNC（这在查阅OSS文档时很有用）。If the underlying ioctl() fails, they all raise OSError.如果底层ioctl()失败，它们都会引发OSError。

oss_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.一旦处于非阻塞模式，就无法将其返回到阻塞模式。

oss_audio_device.getfmts()

Return a bitmask of the audio output formats supported by the soundcard. 返回声卡支持的音频输出格式的位掩码。Some of the formats supported by OSS are:OSS支持的一些格式包括：

Format格式	Description描述
AFMT_MU_LAW	a logarithmic encoding (used by Sun .au files and /dev/audio)对数编码（Sun .au文件和/dev/audio使用）
AFMT_A_LAW	a logarithmic encoding对数编码
AFMT_IMA_ADPCM	a 4:1 compressed format defined by the Interactive Multimedia Association交互式多媒体协会定义的4:1压缩格式
AFMT_U8	Unsigned, 8-bit audio无符号8位音频
AFMT_S16_LE	Signed, 16-bit audio, little-endian byte order (as used by Intel processors)有符号、16位音频、小端字节顺序（英特尔处理器使用）
AFMT_S16_BE	Signed, 16-bit audio, big-endian byte order (as used by 68k, PowerPC, Sparc)有符号、16位音频、大端字节顺序（68k、PowerPC、Sparc使用）
AFMT_S8	Signed, 8 bit audio有符号，8位音频
AFMT_U16_LE	Unsigned, 16-bit little-endian audio无符号16位小端音频
AFMT_U16_BE	Unsigned, 16-bit big-endian audio无符号16位大端音频

Consult the OSS documentation for a full list of audio formats, and note that most devices support only a subset of these formats. 有关音频格式的完整列表，请参阅OSS文档，并注意大多数设备只支持这些格式的一个子集。Some older devices only support AFMT_U8; the most common format used today is AFMT_S16_LE.一些较旧的设备仅支持AFMT_U8；今天最常用的格式是AFMT_S16_LE。

oss_audio_device.setfmt(format)

Try to set the current audio format to format—see getfmts() for a list. 尝试将当前音频格式设置为format。请参阅getfmts()获取列表。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 AFMT_QUERY.也可用于返回当前音频格式。通过传递AFMT_QUERY的“音频格式”来执行此操作。

oss_audio_device.channels(nchannels)

Set the number of output channels to nchannels. 将输出通道数设置为nchannels。A value of 1 indicates monophonic sound, 2 stereophonic. 值1表示单声道声音，2表示立体声声音。Some devices may have more than 2 channels, and some high-end devices may not support mono. 有些设备可能有2个以上的频道，有些高端设备可能不支持单声道。Returns the number of channels the device was set to.返回设备设置的通道数。

oss_audio_device.speed(samplerate)

Try to set the audio sampling rate to samplerate samples per second. 尝试将音频采样率设置为每秒采样率samplerate。Returns the rate actually set. Most sound devices don’t support arbitrary sampling rates. 返回实际设置的速率。大多数声音设备不支持任意采样率。Common rates are:常见费率为：

Rate速度	Description描述
8000	default rate for /dev/audio/dev/audio的默认速率
11025	speech recording语音录音
22050
44100	CD quality audio (at 16 bits/sample and 2 channels)CD质量音频（16位/样本和2个通道）
96000	DVD quality audio (at 24 bits/sample)DVD质量音频（24位/样本）

oss_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 sync().OSS文档建议关闭并重新打开设备，而不是使用sync()。

oss_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 reset().OSS文档建议在调用reset()后关闭并重新打开设备。

oss_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.您可以在播放点声音效果之后、等待用户输入之前或执行磁盘I/O之前使用此选项。

The following convenience methods combine several ioctls, or one ioctl and some simple calculations.以下方便的方法结合了几个ioctl，或一个ioctl和一些简单的计算。

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

Set the key audio sampling parameters—sample format, number of channels, and sampling rate—in one method call. 在一个方法调用中设置关键音频采样参数采样格式、通道数和采样率。format, nchannels, and samplerate should be as specified in the setfmt(), channels(), and speed() methods. format、nchannels和samplerate应与setfmt()、channels()和speed()方法中指定的相同。If strict is true, setparameters() checks to see if each parameter was actually set to the requested value, and raises OSSAudioError if not. 如果strict为true，setparameters()将检查每个参数是否实际设置为请求的值，否则将引发OSSAudioError。Returns a tuple (format, nchannels, samplerate) indicating the parameter values that were actually set by the device driver (i.e., the same as the return values of setfmt(), channels(), and speed()).返回一个元组（format、nchannels、samplerate），指示设备驱动程序实际设置的参数值（即，与setfmt()、channels()和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 to be 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".文件的I/O模式，"r"、"rw"或"w"。

Mixer Device Objects混合器设备对象

The mixer object provides two file-like methods:mixer对象提供两种类似文件的方法：

oss_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 OSError.关闭此文件后，任何进一步尝试使用混音器都会引发OSError。

oss_mixer_device.fileno()

Returns the file handle number of the open mixer device file.返回打开的混音器设备文件的文件句柄号。

Changed in version 3.2:版本3.2中更改： Mixer objects also support the context management protocol.Mixer对象还支持上下文管理协议。

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 SOUND_MIXER_PCM or SOUND_MIXER_SYNTH). 此方法返回指定可用混音器控件的位掩码（“Control”是特定的可混音“通道”，如SOUND_MIXER_PCM或SOUND_MIXER_SYNTH）。This bitmask indicates a subset of all available mixer controls—the SOUND_MIXER_* constants defined at module level. 此位掩码指示所有可用混频器的子集，这些混频器控制在模块级定义的SOUND_MIXER_*常数。To determine if, for example, the current mixer object supports a PCM mixer, use the following Python code:例如，要确定当前混合器对象是否支持PCM混合器，请使用以下Python代码：

mixer=ossaudiodev.openmixer()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
    # PCM is supported
    ... code ...

For most purposes, the SOUND_MIXER_VOLUME (master volume) and SOUND_MIXER_PCM controls should suffice—but code that uses the mixer should be flexible when it comes to choosing mixer controls. 对于大多数用途，SOUND_MIXER_VOLUME（主音量）和SOUND_MIXER_PCM控件应该足够了，但在选择混音器控件时，使用混音器的代码应该是灵活的。On the Gravis Ultrasound, for example, SOUND_MIXER_VOLUME does not exist.例如，在重力超声上，SOUND_MIXER_VOLUME不存在。

oss_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 controls() to determine which).如果设置了位，则对应的控制是立体声的；如果未设置，则该控件为单声道或不受混音器支持（与controls()结合使用以确定是哪个）。

See the code example for the controls() function for an example of getting data from a bitmask.有关从位掩码获取数据的示例，请参阅controls()函数的代码示例。

oss_mixer_device.reccontrols()

Returns a bitmask specifying the mixer controls that may be used to record. 返回一个位掩码，指定可用于录制的混音器控件。See the code example for controls() for an example of reading from a bitmask.有关从位掩码读取的示例，请参阅controls()的代码示例。

oss_mixer_device.get(control)

Returns the volume of a given mixer control. 返回给定混音器控件的音量。The returned volume is a 2-tuple (left_volume,right_volume). 返回的卷是一个2元组(left_volume,right_volume)。Volumes are specified as numbers from 0 (silent) to 100 (full volume). 卷指定为从0（无声）到100（完整卷）的数字。If the control is monophonic, a 2-tuple is still returned, but both volumes are the same.如果控件是单声道的，则仍然返回2元组，但两个卷都相同。

Raises OSSAudioError if an invalid control is specified, or OSError if an unsupported control is specified.如果指定了无效的控件，则引发OSSAudioError；如果指定了不受支持的控件，将引发OSError。

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

Sets the volume for a given mixer control to (left,right). 将给定混合器控件的音量设置为(left,right)。left and right must be ints and between 0 (silent) and 100 (full volume). left和right必须是整数，并且介于0（无声）和100（全音量）之间。On success, the new volume is returned as a 2-tuple. 成功后，新卷将作为2元组返回。Note that this may not be exactly the same as the volume specified, because of the limited resolution of some soundcard’s mixers.请注意，这可能与指定的音量不完全相同，因为某些声卡的混音器分辨率有限。

Raises OSSAudioError if an invalid mixer control was specified, or if the specified volumes were out-of-range.如果指定的混音器控件无效，或者指定的卷超出范围，则引发OSSAudioError。

oss_mixer_device.get_recsrc()

This method returns a bitmask indicating which control(s) are currently being used as a recording source.此方法返回一个位掩码，指示当前将哪个控件用作记录源。

oss_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 OSError if an invalid source was specified. 如果成功，返回指示新记录源的位掩码；如果指定了无效的源，则引发OSError。To set the current recording source to the microphone input:要将当前录制源设置为麦克风输入：

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)