ossaudiodev — Доступ к устройствам аудио, совместимым с OSS

Этот модуль позволяет получить доступ к аудиоинтерфейсу OSS (Open Sound System). OSS доступен для широкого спектра открытых и коммерческих Unix-подобных систем и является стандартным аудиоинтерфейсом для 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 read/write и семантикой аудиоустройств OSS). Он также поддерживает ряд методов, специфичных для аудио; полный список методов приведен ниже.

device — имя файла аудиоустройства для использования. Если не указано, модуль сначала ищет устройство в переменной окружения AUDIODEV. Если не найдено, используется /dev/dsp.

mode — один из 'r' для чтения (записи), 'w' для записи (воспроизведения) и 'rw' для обоих. Поскольку многие звуковые карты позволяют только одному процессу одновременно открывать устройство для записи или воспроизведения, открывать устройство рекомендуется только для необходимой активности. Кроме того, некоторые звуковые карты полудуплексные: они могут быть открыты для чтения или записи, но не для обоих одновременно.

Обратите внимание на необычный синтаксис вызова: первый аргумент необязателен, а второй обязателен. Это историческая особенность для совместимости со старым модулем linuxaudiodev, который заменяется модулем ossaudiodev.

ossaudiodev.openmixer([device])

Открывает устройство микшера и возвращает объект устройства микшера OSS. device — имя файла устройства микшера для использования. Если не указано, модуль сначала ищет устройство в переменной окружения MIXERDEV. Если не найдено, используется /dev/mixer.

Объекты аудиоустройств

Прежде чем записывать в или читать из аудиоустройства, необходимо вызвать три метода в правильном порядке:

1. setfmt() для установки формата вывода
2. channels() для установки количества каналов
3. 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)

Записывает байтовый объект data в аудиоустройство и возвращает количество записанных байт. Если аудиоустройство находится в режиме блокировки (по умолчанию), все данные всегда записываются (опять же, это отличается от обычной семантики устройств Unix). Если устройство находится в режиме без ожидания, некоторые данные могут не быть записаны — см. writeall().

Изменено в версии 3.5: Теперь принимается любой байтовый объект.

oss_audio_device.writeall(data)

Записывает байтовый объект data в аудиоустройство: ожидает, пока аудиоустройство сможет принять данные, записывает столько данных, сколько сможет принять, и повторяет, пока все данные data не будут записаны. Если устройство находится в режиме блокировки (по умолчанию), это имеет тот же эффект, что и write(); writeall() полезна только в режиме без ожидания. Не имеет значения возвращаемого значения, так как количество записанных данных всегда равно количеству предоставленных данных.

Изменено в версии 3.5: Теперь принимается любой байтовый объект.

Следующие методы соответствуют ровно одному вызову системной функции ioctl(). Соответствие очевидно: например, setfmt() соответствует системному вызову SNDCTL_DSP_SETFMT, а sync() — SNDCTL_DSP_SYNC (это может быть полезно при консультации документации OSS). Если базовый вызов ioctl() терпит неудачу, они все генерируют исключение OSError.

oss_audio_device.nonblock()

Переводит устройство в режим без ожидания. После перевода в режим без ожидания нет возможности вернуть его в режим ожидания.

oss_audio_device.getfmts()

Возвращает битовую маску аудиоформатов, поддерживаемых звуковой картой. Некоторые из форматов, поддерживаемых OSS:

Формат	Описание
AFMT_MU_LAW	логарифмическое кодирование (используется в файлах Sun .au и /dev/audio)
AFMT_A_LAW	логарифмическое кодирование
AFMT_IMA_ADPCM	сжатый формат 4:1, определённый Ассоциацией интерактивных мультимедиа
AFMT_U8	Беззнаковое аудио 8 бит
AFMT_S16_LE	Знаковое аудио 16 бит, порядок байт — little-endian (как используется процессорами Intel)
AFMT_S16_BE	Знаковое аудио 16 бит, порядок байт — big-endian (как используется в процессорах 68k, PowerPC, Sparc)
AFMT_S8	Знаковое аудио 8 бит
AFMT_U16_LE	Беззнаковое аудио 16 бит, порядок байт — little-endian
AFMT_U16_BE	Беззнаковое аудио 16 бит, порядок байт — big-endian

См. документацию 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	стандартная частота для /dev/audio
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()

Уведомить драйвер о том, что, вероятно, произойдёт пауза в выводе, что позволит устройству более разумно обработать паузу. Вы можете использовать это после воспроизведения звукового эффекта, перед ожиданием ввода от пользователя или перед выполнением операций ввода-вывода на диск.

Следующие удобные методы объединяют несколько ioctls или один ioctl и некоторые простые вычисления.

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

Установить ключевые параметры аудиодискретизации — формат выборки, количество каналов и частоту дискретизации — в одном вызове метода. format, nchannels и samplerate должны быть указаны, как в методах setfmt(), channels() и speed(). Если strict имеет значение true, 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

Режим ввода-вывода для файла, либо "r", либо "rw", либо "w".

Объекты устройств микшера

Объект микшера предоставляет два метода, подобных файлам:

oss_mixer_device.close()

Этот метод закрывает открытый файл устройства микшера. Любые дальнейшие попытки использовать микшер после закрытия этого файла приведут к исключению OSError.

oss_mixer_device.fileno()

Возвращает номер дескриптора файла открытого устройства микшера.

Остальные методы специфичны для микширования аудио:

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)