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(), поддерживается для обратной совместимости.

Устарело начиная с версии 3.7, будет удалено в версии 3.9.

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

Объекты 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(): Возвращает текущую позицию указателя файла.

Объекты 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.