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.

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

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

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 ioctl, а 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, определённый Interactive Multimedia Association
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)

Попробуйте установить текущий аудиоформат на формат — см. 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 истинно, 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".

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

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

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)