22.9. ossaudiodev – Доступ к аудиоустройствам, совместимым с OSS¶ossaudiodev – Access to OSS-compatible audio devices

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

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

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

Записывает байтоподобный объект данные в аудиоустройство и возвращает количество записанных байтов. Если аудиоустройство находится в блокирующем режиме (по умолчанию), все данные всегда записываются (опять же, это отличается от обычной семантики устройств 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, определённый Ассоциацией интерактивного мультимедиа
AFMT_U8	Беззнаковое 8-битное аудио
AFMT_S16_LE	Знаковое 16-битное аудио с порядком байтов от младшего к старшему (используется процессорами Intel)
AFMT_S16_BE	Знаковое 16-битное аудио с порядком байтов от старшего к младшему (используется 68k, PowerPC, Sparc)
AFMT_S8	Знаковое 8-битное аудио
AFMT_U16_LE	Беззнаковое 16-битное аудио с порядком от младшего к старшему
AFMT_U16_BE	Беззнаковое 16-битное аудио с порядком от старшего к младшему

Обратитесь к документации 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".

22.9.2. Объекты микшерных устройств¶Mixer Device Objects

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

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

Возвращает громкость указанного регулятора микшера. Возвращаемая громкость – это кортеж из двух элементов (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)