ossaudiodev —- 访问兼容OSS的音频设备
从版本 3.11 开始标记为过时,将在版本 3.13 中移除。: ossaudiodev 模块已被弃用(请参阅 PEP 594 了解详情)。
该模块允许您访问 OSS(开放式音响系统)音频接口。 OSS 可用于广泛的开源和商业 Unices,并且是 Linux 和最新版本的 FreeBSD 的标准音频接口。
在 3.3 版更改: 此模块中过去会引发 IOError 的操作现在将引发 OSError。
参见
OSS C API 的官方文档
该模块定义了大量由OSS设备驱动提供的常量; 请参阅``<sys/soundcard.h>`` Linux 或 FreeBSD 上的列表。
ossaudiodev 定义了下列变量和函数:
exception ossaudiodev.OSSAudioError
此异常会针对特定错误被引发。 其参数为一个描述错误信息的字符串。
(如果 ossaudiodev 从系统调用例如 open()
, write()
或 ioctl()
接收到错误,它将引发 OSError。 由 ossaudiodev 直接检测到的错误将引发 OSSAudioError。)
(为了向下兼容,此异常类也可通过 ossaudiodev.error
访问。)
ossaudiodev.open(mode)
ossaudiodev.open(device, mode)
打开一个音频设备并返回 OSS 音频设备对象。 此对象支持许多文件类方法,例如 read()
, write()
和 fileno()
(不过传统的 Unix 读/写语义与 OSS 音频设备的存在一些细微的差异)。 它还支持一些音频专属的方法;完整的方法列表见下文。
device 是要使用的音频设备文件名。 如果未指定,则此模块会先在环境变量 AUDIODEV
中查找要使用的设备。 如果未找到,它将回退为 /dev/dsp
。
mode 可以为 'r'
表示只读(录音)访问,'w'
表示只写(回放)访问以及 'rw'
表示同时读写。 由于许多声卡在同一时间只允许单个进程打开录音机或播放器,因此好的做法是只根据活动的需要打开设备。 并且,有些声卡是半双工的:它们可以被打开用于读取或写入,但不能同时读写。
请注意这里特殊的调用语法: first 参数是可选的,而第二个参数则是必需的。 这是出于历史原因要与 ossaudiodev 所替代的 linuxaudiodev
模块保持兼容。
ossaudiodev.openmixer([device])
打开一个混音设备并返回 OSS 混音设备对象。 device 是要使用的混音设备文件名。 如果未指定,则此模块会先在环境变量 MIXERDEV
中查找要使用的设备。 如果未找到,它将回退为 /dev/mixer
。
音频设备对象
在你写入或读取音频设备之前,你必须按照正确的顺序调用三个方法:
setfmt()
设置输出格式channels()
设置声道数量speed()
设置采样率
或者,你也可以使用 setparameters()
方法一次性地设置全部三个音频参数。 这更为便捷,但可能不会在所有场景下都一样灵活。
open() 所返回的音频设备对象定义了下列方法和(只读)属性:
oss_audio_device.close()
显式地关闭音频设备。 当你完成写入或读取音频设备后,你应当显式地关闭它。 已关闭的设备不可被再次使用。
oss_audio_device.fileno()
返回与设备相关联的文件描述符。
oss_audio_device.read(size)
从音频输入设备读取 size 个字节并返回为 Python 字节串。 与大多数 Unix 设备驱动不同,处于阻塞模式(默认)的 OSS 音频设备将阻塞 read() 直到所请求大小的数据全部可用。
oss_audio_device.write(data)
将一个 bytes-like object data 写入音频设备并返回写入的字节数。 如果音频设备处于阻塞模式(默认),则总是会写入完整数据(这还是不同于通常的 Unix 设备语义)。 如果设备处于非阻塞模式,则可能会有部分数据未被写入 —- 参见 writeall()。
在 3.5 版更改: 现在接受可写的 字节类对象。
oss_audio_device.writeall(data)
将一个 bytes-like object data 写入音频设备:等待直到音频设备能够接收数据,将根据其所能接收的数据量尽可能多地写入,并重复操作直至 data 被完全写入。 如果设备处于阻塞模式(默认),则其效果与 write() 相同;writeall() 仅适用于非阻塞模式。 它没有返回值,因为写入的数据量总是等于所提供的数据量。
在 3.5 版更改: 现在接受可写的 字节类对象。
在 3.2 版更改: 音频设备对象还支持上下文管理协议,就是说它们可以在 with 语句中使用。
下列方法各自映射一个 ioctl()
系统调用。 对应关系很明显:例如,setfmt()
对应 SNDCTL_DSP_SETFMT
ioctl,而 sync()
对应 SNDCTL_DSP_SYNC
(这在查阅 OSS 文档时很有用)。 如果下层的 ioctl()
失败,它们将引发 OSError。
oss_audio_device.nonblock()
将设备转为非阻塞模式。 一旦处于非阻塞模式,将无法将其转回阻塞模式。
oss_audio_device.getfmts()
返回声卡所支持的音频输出格式的位掩码。 OSS 支持的一部分格式如下:
格式 | 描述 |
---|---|
| 一种对数编码格式(被 Sun |
| 一种对数编码格式 |
| 一种 4:1 压缩格式,由 Interactive Multimedia Association 定义 |
| 无符号的 8 位音频 |
| 有符号的 16 位音频,采用小端字节序(如 Intel 处理器所用的) |
| 有符号的 16 位音频,采用大端字节序(如 68k, PowerPC, Sparc 所用的) |
| 有符号的 8 位音频 |
| 无符号的 16 位小端字节序音频 |
| 无符号的 16 位大端字节序音频 |
请参阅 OSS 文档获取音频格式的完整列表,还要注意大多数设备都只支持这些列表的一个子集。 某些较旧的设备仅支持 AFMT_U8
;目前最为常用的格式是 AFMT_S16_LE
。
oss_audio_device.setfmt(format)
尝试将当前音频格式设为 format —- 请参阅 getfmts() 获取格式列表。 返回为设备设置的音频格式,这可能并非所请求的格式。 也可被用来返回当前音频格式 —- 这可以通过传入特殊的 “音频格式” AFMT_QUERY
来实现。
oss_audio_device.channels(nchannels)
将输出声道数设为 nchannels。 值为 1 表示单声道,2 表示立体声。 某些设备可能拥有 2 个以上的声道,并且某些高端设备还可能不支持单声道。 返回为设备设置的声道数。
oss_audio_device.speed(samplerate)
尝试将音频采样率设为每秒 samplerate 次采样。 返回实际设置的采样率。 大多数设备都不支持任意的采样率。 常见的采样率为:
采样率 | 描述 |
---|---|
8000 |
|
11025 | 语音录音 |
22050 | |
44100 | CD品质的音频(16位采样和2通道) |
96000 | DVD品质的音频(24位采样) |
oss_audio_device.sync()
等待直到音频设备播放完其缓冲区中的所有字节。 (这会在设备被关闭时隐式地发生。) OSS 建议关闭再重新打开设备而不是使用 sync()。
oss_audio_device.reset()
立即停止播放或录制并使设备返回可接受命令的状态。 OSS 文档建议在调用 reset() 之后关闭并重新打开设备。
oss_audio_device.post()
告知设备在输出中可能有暂停,使得设备可以更智能地处理暂停。 你可以在播放一个定点音效之后、等待用户输入之前或执行磁盘 I/O 之前使用此方法。
下列便捷方法合并了多个 ioctl,或是合并了一个 ioctl 与某些简单的运算。
oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False])
在一次方法调用中设置关键的音频采样参数 —- 采样格式、声道数和采样率。 format, nchannels 和 samplerate 应当与在 setfmt(), channels() 和 speed() 方法中所指定的一致。 如果 strict 为真值,则 setparameters() 会检查每个参数是否确实被设置为所请求的值,如果不是则会引发 OSSAudioError。 返回一个元组 (format, nchannels, samplerate) 指明由设备驱动实际设置的参数值 (即与 setfmt(), channels() 和 speed() 的返回值相同)。
例如,:
(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
等价于
fmt = dsp.setfmt(fmt)
channels = dsp.channels(channels)
rate = dsp.rate(rate)
oss_audio_device.bufsize()
返回硬件缓冲区的大小,以采样数表示。
oss_audio_device.obufcount()
返回硬件缓冲区中待播放的采样数。
oss_audio_device.obuffree()
返回可以被加入硬件缓冲区队列以非阻塞模式播放的采样数。
音频设备对象还支持几个只读属性:
oss_audio_device.closed
指明设备是否已被关闭的布尔值。
oss_audio_device.name
包含设备文件名称的字符串。
oss_audio_device.mode
文件的 I/O 模式,可以为 "r"
, "rw"
或 "w"
。
混音器设备对象
混音器对象提供了两个文件类方法:
oss_mixer_device.close()
此方法会关闭打开的混音器设备文件。 在文件被关闭后任何继续使用混音器的尝试都将引发 OSError。
oss_mixer_device.fileno()
返回打开的混音器设备文件的文件处理句柄号。
在 3.2 版更改: 混音器设备还支持上下文管理协议。
其余方法都是混音专属的:
oss_mixer_device.controls()
此方法返回一个表示可用的混音控件的位掩码 (“控件” 是专用的可混合 “声道”,例如 SOUND_MIXER_PCM
或 SOUND_MIXER_SYNTH
)。 该掩码会指定所有可用混音控件的一个子集 —- 它们是在模块层级上定义的 SOUND_MIXER_*
常量。 举例来说,要确定当前混音器对象是否支持 PCM 混音器,就使用以下 Python 代码:
mixer=ossaudiodev.openmixer()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
# PCM is supported
... code ...
对于大多数目的来说,SOUND_MIXER_VOLUME
(主音量) 和 SOUND_MIXER_PCM
控件应该足够了 —- 但使用混音器的代码应当在选择混音器控件时保持灵活。 例如在 Gravis Ultrasound 上,SOUND_MIXER_VOLUME
是不存在的。
oss_mixer_device.stereocontrols()
返回一个表示立体声混音控件的位掩码。 如果设置了比特位,则对应的控件就是立体声的;如果未设置,则控件为单声道或者不被混音器所支持(请配合 controls() 使用以确定是哪种情况)。
请查看 controls() 函数的代码示例了解如何从位掩码获取数据。
oss_mixer_device.reccontrols()
返回一个指明可被用于录音的混音器控件的位掩码。 请查看 controls() 的代码示例了解如何读取位掩码。
oss_mixer_device.get(control)
返回给定混音控件的音量。 返回的音量是一个 2 元组 (left_volume,right_volume)
。 音量被表示为从 0 (静音) 到 100 (最大音量) 的数字。 如果控件是单声道的,仍然会返回一个 2 元组,但两个音量必定相同。
如果指定了无效的控件则会引发 OSSAudioError,或者如果指定了不受支持的控件则会引发 OSError。
oss_mixer_device.set(control, (left, right))
将给定混音控件的音量设为 (left,right)
。 left
和 right
必须为整数并在 0 (静音) 至 100 (最大音量) 之间。 当执行成功的,新的音量将以 2 元组形式返回。 请注意这可能不完全等于所指定的音量,因为某些声卡的混音器有精度限制。
如果指定了无效的混音控件,或者指定的音量超出限制则会引发 OSSAudioError。
oss_mixer_device.get_recsrc()
此方法返回一个表示当前被用作录音源的的控件的位掩码。
oss_mixer_device.set_recsrc(bitmask)
调用此函数来指定一个录音源。 如果成功则返回一个指明新录音源的位掩码;如果指定了无效的源则会引发 OSError。 如果要将当前录音源设为麦克风输入:
mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)