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 — строка, открывает файл с этим именем, иначе рассматривает его как объектно-ориентированный файл. mode может быть:

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

Обратите внимание, что он не позволяет читать/записывать файлы WAV.

Значение mode 'rb' возвращает объект Wave_read, а значение mode 'wb' возвращает объект Wave_write. Если mode опущен, а в качестве file передан объектно-ориентированный файл, file.mode используется в качестве значения по умолчанию для 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(): Возвращает namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname), эквивалентный выводу методов 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: Теперь принимается любой объект-подобный байтам.

writeframes(data)

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

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

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