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

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

Модуль wave предоставляет удобный интерфейс к формату WAV. Он не поддерживает сжатие/распаковку, но поддерживает моно/стерео.

Модуль 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: Добавлена поддержка файлов без возможности перемещения по ним.

wave.openfp(file, mode): Синоним для open(), поддерживается для обратной совместимости.

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

1. Объекты Wave_read

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

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

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

Wave_read.getsampwidth(): Возвращает ширину выборки в байтах.

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

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

Wave_read.getcomptype(): Возвращает тип сжатия ('NONE' — единственный поддерживаемый тип).

Wave_read.getcompname(): Человекочитаемая версия getcomptype(). Обычно 'not compressed' соответствует 'NONE'.

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

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

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

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

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

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

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

Wave_read.setpos(pos): Установить указатель файла на указанную позицию.

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

2. Объекты Wave_write

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

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

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

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

Wave_write.setnchannels(n): Установить количество каналов.

Wave_write.setsampwidth(n): Установить ширину выборки в n байтах.

Wave_write.setframerate(n): Установить частоту кадров в n.

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

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

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

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

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

Wave_write.writeframesraw(data): Записать аудиокадры без коррекции nframes.

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

Wave_write.writeframes(data): Записать аудиокадры и убедиться, что nframes корректен. Вызовет ошибку, если поток вывода не допускает перемещения по нему, и общее количество кадров, записанных после записи data, не соответствует ранее заданному значению nframes.

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

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