wave — чтение и запись WAV-файлов

Исходный код: Lib/wave.py

Модуль wave предоставляет удобный интерфейс для работы с форматом файлов Waveform Audio «WAVE» (или «WAV»). Поддерживаются только WAV-файлы с несжатым кодированием PCM.

Изменено в версии 3.12: Добавлена поддержка заголовков WAVE_FORMAT_EXTENSIBLE при условии, что расширенный формат — KSDATAFORMAT_SUBTYPE_PCM.

Модуль wave определяет следующую функцию и исключение:

wave.open(file, mode=None)

Если file — строка, файл с таким именем открывается; в противном случае file рассматривается как файловый объект. Параметр mode может принимать значения:

'rb': Режим только для чтения.
'wb': Режим только для записи.

Обратите внимание: режим чтения и записи WAV-файлов не поддерживается.

При значении mode 'rb' возвращается объект Wave_read, а при значении mode 'wb' — объект Wave_write. Если mode не указан, а в качестве file передан файловый объект, для mode по умолчанию используется file.mode.

Если передан файловый объект, объект wave не закроет его при вызове метода close(); закрыть файловый объект должен вызывающий код.

Функцию open() можно использовать в инструкции with. После завершения блока with вызывается метод Wave_read.close() или Wave_write.close().

Изменено в версии 3.4: Добавлена поддержка файлов, не поддерживающих перемещение по ним.

exception wave.Error: Ошибка, возникающая, когда выполнить операцию невозможно из-за нарушения спецификации WAV или недостатка реализации.

Объекты Wave_read

class wave.Wave_read

Чтение WAV-файла.

Объекты Wave_read, возвращаемые функцией open(), имеют следующие методы:

close(): Закрыть поток, если он был открыт функцией wave, и сделать экземпляр непригодным для использования. Этот метод вызывается автоматически при удалении объекта сборщиком мусора.

getnchannels(): Возвращает количество аудиоканалов (1 для моно, 2 для стерео).

getsampwidth(): Возвращает ширину отсчёта в байтах.

getframerate(): Возвращает частоту дискретизации.

getnframes(): Возвращает количество аудиокадров.

getcomptype(): Возвращает тип сжатия (поддерживается только 'NONE').

getcompname(): Удобочитаемое представление типа сжатия, возвращаемого методом getcomptype(). Обычно 'not compressed' соответствует 'NONE'.

getparams(): Возвращает (nchannels, sampwidth, framerate, nframes, comptype, compname) типа namedtuple(), эквивалентный результату вызова методов get*().

readframes(n): Считывает и возвращает не более n аудиокадров в виде объекта bytes.

rewind(): Перемещает указатель файла в начало аудиопотока.

Следующие два метода определены для совместимости со старым модулем aifc и не выполняют ничего полезного.

getmarkers(): Возвращает None.

Устарело с версии 3.13, будет удалено в версии 3.15: Метод существовал только для совместимости с модулем aifc, удалённым в Python 3.13.

getmark(id): Вызывает ошибку.

Устарело с версии 3.13, будет удалено в версии 3.15: Метод существовал только для совместимости с модулем aifc, удалённым в Python 3.13.

Следующие два метода задают совместимое между ними понятие «позиции», реализация которого в остальном зависит от реализации.

setpos(pos): Перемещает указатель файла в указанную позицию.

tell(): Возвращает текущую позицию указателя файла.

Объекты Wave_write

class wave.Wave_write

Запись WAV-файла.

Объекты Wave_write возвращаются функцией open().

Для выходных потоков, поддерживающих перемещение по ним, заголовок wave автоматически обновляется в соответствии с фактически записанным количеством кадров. Для потоков, не поддерживающих перемещение по ним, значение nframes должно быть точным к моменту записи первых данных кадра. Точного значения nframes можно добиться, вызвав setnframes() или setparams() с количеством кадров, которое будет записано до вызова close(), а затем используя writeframesraw() для записи данных кадров; либо вызвав writeframes() со всеми данными кадров, которые нужно записать. В последнем случае writeframes() вычислит количество кадров в данных и установит соответствующее значение nframes перед записью данных кадров.

Изменено в версии 3.4: Добавлена поддержка файлов, не поддерживающих перемещение по ним.

Объекты Wave_write имеют следующие методы:

close(): Проверяет правильность значения nframes и закрывает файл, если он был открыт функцией wave. Этот метод вызывается при удалении объекта сборщиком мусора. Если выходной поток не поддерживает перемещение по нему и значение nframes не совпадает с фактически записанным количеством кадров, будет вызвано исключение.

setnchannels(n): Задаёт количество каналов.

getnchannels(): Возвращает количество каналов.

setsampwidth(n): Задаёт ширину отсчёта в n байтах.

getsampwidth(): Возвращает ширину отсчёта в байтах.

setframerate(n): Задаёт частоту кадров n.

Изменено в версии 3.2: Не целочисленное значение, переданное этому методу, округляется до ближайшего целого.

getframerate(): Возвращает частоту кадров.

setnframes(n): Задаёт количество кадров равным n. Позже оно будет изменено, если фактически записанное количество кадров окажется другим (эта попытка обновления вызовет ошибку, если выходной поток не поддерживает перемещение по нему).

getnframes(): Возвращает количество аудиокадров, записанных на данный момент.

setcomptype(type, name): Задаёт тип и описание сжатия. В настоящее время поддерживается только тип сжатия NONE, то есть без сжатия.

getcomptype(): Возвращает тип сжатия ('NONE').

getcompname(): Возвращает удобочитаемое название типа сжатия.

setparams(tuple): Кортеж должен иметь формат (nchannels, sampwidth, framerate, nframes, comptype, compname), а его значения должны быть допустимы для методов set*(). Задаёт все параметры.

getparams(): Возвращает (nchannels, sampwidth, framerate, nframes, comptype, compname) типа namedtuple(), содержащий текущие параметры вывода.

tell(): Возвращает текущую позицию в файле с той же оговоркой, что и для методов Wave_read.tell() и Wave_read.setpos().

writeframesraw(data): Записывает аудиокадры, не корректируя значение nframes.

Изменено в версии 3.4: Теперь принимается любой объект, подобный bytes.

writeframes(data)

Записывает аудиокадры и проверяет правильность значения nframes. Если выходной поток не поддерживает перемещение по нему, а общее количество кадров, записанных после передачи data, не совпадает с ранее заданным значением nframes, будет вызвана ошибка.

Изменено в версии 3.4: Теперь принимается любой объект, подобный bytes.

Обратите внимание: после вызова writeframes() или writeframesraw() задавать параметры нельзя; любая попытка сделать это вызовет wave.Error.