Документация Python неофициальный перевод
Содержание страницы

wave – чтение и запись WAV-файловwave – Read and write WAV files

Исходный код: 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_readWave_read Objects

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

Для потоков вывода с произвольным доступом заголовок 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.