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

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

Изменено в версии 3.3: Операции в этом модуле теперь вызывают OSError, когда раньше вызвалось IOError.

См.также

Руководство программиста открытой звуковой системы: официальная документация для 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' для обоих. Поскольку многие звуковые карты позволяют только одному процессу одновременно открывать записывающее устройство или проигрыватель, рекомендуется открывать устройство только для необходимых действий. Кроме того, некоторые звуковые карты являются полудуплексными: их можно открыть для чтения или записи, но не для того и другого одновременно.

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

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): Записывает байтоподобный объект data на аудиоустройство и возвращает количество записанных байтов. Если аудиоустройство находится в режиме блокировки (по умолчанию), всегда записываются все данные (опять же, это отличается от обычной семантики устройства Unix). Если устройство находится в неблокирующем режиме, некоторые данные могут не записываться, см. writeall().

Изменено в версии 3.5: Доступен для записи байтоподобный объект.

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

Изменено в версии 3.5: Доступен для записи байтоподобный объект.

Изменено в версии 3.2: Объекты аудиоустройств также поддерживают протокол управления контекстом, т. е. их можно использовать в операторе with.

Каждый из следующих методов соответствует ровно одному системному вызову ioctl(). Соответствие очевидно: например, setfmt() соответствует ioctl 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, определённый в Interactive Multimedia Association (IMA)
`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 истинно, 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".

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

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

oss_mixer_device.close(): Данный метод закрывает открытый файл устройства микшера. Любые дальнейшие попытки использовать микшер после закрытия данного файла вызовут ошибку OSError.

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

Изменено в версии 3.2: Объекты Mixer также поддерживают протокол управления контекстом.

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

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 поддерживается
    ... код ...

Для большинства целей достаточно 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)

Возвращает громкость данного элемента управления микшера. Возвращаемый том — это кортеж из двух строк (left_volume,right_volume). Объемы указываются числами от 0 (без звука) до 100 (полный объем). Если элемент управления монофонический, двойка все равно возвращается, но обе громкости одинаковы.

Вызывает OSSAudioError, если указан недопустимый элемент управления, или OSError, если указан неподдерживаемый элемент управления.

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

Устанавливает громкость для данного элемента управления микшера на (left,right). left и right должны быть целыми и находиться в диапазоне от 0 (без звука) до 100 (полная громкость). В случае успеха новый том возвращается в виде двух кортежей. Обратите внимание, что это может не совпадать с указанной громкостью из-за ограниченного разрешения микшеров некоторых звуковых карт.

Вызывает OSSAudioError, если был указан неверный элемент управления микшером или если указанные объемы вышли за допустимые пределы.

oss_mixer_device.get_recsrc(): Данный метод возвращает битовую маску, указывающую, какие элементы управления в настоящее время используются в качестве источника записи.

oss_mixer_device.set_recsrc(bitmask)

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

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)

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

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

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

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