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

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

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

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)

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

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

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

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)