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

Этот модуль позволяет получить доступ к аудиоинтерфейсу OSS (Open Sound System). OSS доступен для широкого спектра открытых и коммерческих Unix-подобных систем и является стандартным аудиоинтерфейсом для Linux и последних версий FreeBSD.

ossaudiodev определяет следующие переменные и функции:

exception ossaudiodev.OSSAudioError

Это исключение возникает при определенных ошибках. Аргументом является строка, описывающая причину ошибки.

(Если ossaudiodev получает ошибку от системного вызова, такого как open(), write(), или ioctl(), он вызывает IOError. Ошибки, обнаруженные непосредственно 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' для обоих режимов. Поскольку многие звуковые карты позволяют только одному процессу иметь открытым устройство записи или воспроизведения в одно время, рекомендуется открывать устройство только для необходимой активности. Кроме того, некоторые звуковые карты полудуплексные: их можно открыть для чтения или записи, но не для обоих одновременно.

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

ossaudiodev.openmixer([device])

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

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)

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

oss_audio_device.writeall(data)

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

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

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()

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

Следующие удобные методы объединяют несколько ioctl-команд или одну 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".

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

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

oss_mixer_device.close()

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

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, если указан недопустимый элемент управления, или IOError, если указан недопустимый элемент управления.

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)

Вызовите эту функцию, чтобы указать источник записи. Возвращает битовую маску, указывающую новый источник записи (или источники), если это было успешно; вызывает IOError, если был указан недопустимый источник. Для установки текущего источника записи на вход микрофона:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)