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

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

Модуль wave предоставляет удобный интерфейс к формату WAV. Поддерживаются только файлы, использующие WAVE_FORMAT_PCM. Обратите внимание, что это не включает файлы, использующие WAVE_FORMAT_EXTENSIBLE, даже если подформат 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

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