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 и семантикой аудиоустройств 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)

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

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

oss_audio_device.writeall(data)

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

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

Следующие методы соответствуют одному системному вызову 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
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()

Этот метод закрывает открытый файл устройства микшера. Любые дальнейшие попытки использования микшера после закрытия этого файла приведут к возникновению 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)