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.

Если вы передаете объект-подобный файлу, объект 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): Кортеж должен быть (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.