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

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

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

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

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

wave.open(file, mode=None)

Если 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.

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

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

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): Устанавливает количество каналов.

setsampwidth(n): Устанавливает ширину отсчёта в n байт.

setframerate(n): Устанавливает частоту кадров равной n.

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

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

setcomptype(type, name): Устанавливает тип сжатия и его описание. В настоящее время поддерживается только тип сжатия NONE, означающий отсутствие сжатия.

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

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.