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.

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

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

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

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

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

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

setparams(tuple): 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.