ossaudiodev — Доступ до OSS-сумісних аудіопристроїв

Застаріло починаючи з версії 3.11: Модуль ossaudiodev застарів (докладніше див. PEP 594).

---

Цей модуль дозволяє отримати доступ до аудіоінтерфейсу OSS (Open Sound System). OSS доступний для широкого діапазону відкритих і комерційних Unices і є стандартним аудіоінтерфейсом для 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.

Об’єкти звукових пристроїв

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

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)

Записати bytes-like object data на аудіопристрій і повернути кількість записаних байтів. Якщо аудіопристрій знаходиться в режимі блокування (за замовчуванням), усі дані завжди записуються (знову ж таки, це відрізняється від звичайної семантики пристрою Unix). Якщо пристрій у неблокуючому режимі, деякі дані можуть не записуватися — див. writeall().

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

oss_audio_device.writeall(data)

Записати bytes-like object data в аудіопристрій: чекає, доки аудіопристрій зможе прийняти дані, записує стільки даних, скільки прийме, і повторює, доки data не буде повністю записано. Якщо пристрій перебуває в режимі блокування (за замовчуванням), це має той самий ефект, що й write(); writeall() корисний лише в неблокуючому режимі. Не має значення, що повертається, оскільки кількість записаних даних завжди дорівнює кількості наданих даних.

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

Змінено в версії 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
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".

Об’єкти мікшерного пристрою

Об’єкт 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 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 мають мати цілі значення та бути в межах від 0 (без звуку) до 100 (повна гучність). У разі успіху новий том повертається як 2-кортеж. Зауважте, що це може не збігатися з указаною гучністю через обмежену роздільну здатність деяких мікшерів звукової карти.

Викликає OSSAudioError, якщо було вказано недійсний елемент керування мікшером або якщо вказані гучності вийшли за межі діапазону.

oss_mixer_device.get_recsrc()

Цей метод повертає бітову маску, яка вказує на те, який(-і) елемент(и) наразі використовується як джерело запису.

oss_mixer_device.set_recsrc(bitmask)

Викличте цю функцію, щоб вказати джерело запису. Повертає бітову маску, що вказує на нове джерело (або джерела) запису в разі успіху; викликає OSError, якщо вказано недійсне джерело. Щоб встановити поточне джерело запису на вхід мікрофона:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)