`wave.md`

236 строк · 15.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/wave.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `wave` – чтение и запись WAV-файлов89**Исходный код:** [Lib/wave.py](https://python-all.ru/src/main/Lib/wave.py)1011---1213Модуль `wave` предоставляет удобный интерфейс для работы с форматом файлов Waveform Audio «WAVE» (или «WAV»).1415Модуль поддерживает форматы WAV: несжатый PCM и IEEE с плавающей запятой.1617Изменено в версии 3.12: Добавлена поддержка заголовков `WAVE_FORMAT_EXTENSIBLE` при условии, что расширенный формат имеет значение `KSDATAFORMAT_SUBTYPE_PCM`.1819Изменено в версии 3.15: Добавлена поддержка чтения и записи файлов `WAVE_FORMAT_IEEE_FLOAT`.2021Модуль `wave` определяет следующие функцию и исключение:2223#### `wave.open(file, mode=None)`2425Если *file* – строка, [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object) или [объект, подобный байтовой строке](https://python-all.ru/3.16/glossary.html#term-bytes-like-object), то открывается файл с таким именем; в противном случае он считается файлоподобным объектом. *mode* может принимать следующие значения:2627**`'rb'`**2829Режим только для чтения.3031**`'wb'`**3233Режим только для записи.3435Обратите внимание: не поддерживаются WAV-файлы, открытые одновременно на чтение и запись.3637Значение *mode*, равное `'rb'`, возвращает объект [`Wave_read`](https://python-all.ru/3.16/library/wave.html#wave.Wave_read), а значение *mode*, равное `'wb'`, возвращает объект [`Wave_write`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write). Если *mode* опущен и в качестве *file* передан файлоподобный объект, то `file.mode` используется как значение по умолчанию для *mode*.3839Если передан файлоподобный объект, объект wave не закроет его при вызове метода `close()`; закрытие файлового объекта – ответственность вызывающей стороны.4041Функция `open()` может использоваться в операторе [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with). Когда блок `with` завершается, вызывается метод [`Wave_read.close()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_read.close) или [`Wave_write.close()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.close).4243Изменено в версии 3.4: Добавлена поддержка файлов без произвольного доступа.4445Изменено в версии 3.15: Добавлена поддержка [объектов, подобных путям](https://python-all.ru/3.16/glossary.html#term-path-like-object) и [объектов, подобных байтовым строкам](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).4647#### `exception wave.Error`4849Исключение, возникающее, когда какое-либо действие невозможно, поскольку оно нарушает спецификацию WAV или сталкивается с недостатком реализации.5051#### `wave.WAVE_FORMAT_PCM`5253Код формата для несжатого аудио PCM.5455#### `wave.WAVE_FORMAT_IEEE_FLOAT`5657Код формата для аудио IEEE с плавающей запятой.5859#### `wave.WAVE_FORMAT_EXTENSIBLE`6061Код формата для расширяемых заголовков WAVE.6263## Объекты Wave\_read6465#### `class wave.Wave_read`6667Чтение WAV-файла.6869Объекты Wave\_read, возвращаемые функцией [`open()`](https://python-all.ru/3.16/library/wave.html#wave.open), имеют следующие методы:7071#### `close()`7273Закрывает поток, если он был открыт с помощью `wave`, и делает экземпляр непригодным для использования. Автоматически вызывается при удалении объекта.7475#### `getnchannels()`7677Возвращает количество аудиоканалов (`1` для моно, `2` для стерео).7879#### `getsampwidth()`8081Возвращает ширину выборки в байтах.8283#### `getframerate()`8485Возвращает частоту дискретизации.8687#### `getnframes()`8889Возвращает количество аудиофреймов.9091#### `getformat()`9293Возвращает код формата фрейма.9495Это один из [`WAVE_FORMAT_PCM`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_PCM), [`WAVE_FORMAT_IEEE_FLOAT`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_IEEE_FLOAT) или [`WAVE_FORMAT_EXTENSIBLE`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_EXTENSIBLE).9697#### `getcomptype()`9899Возвращает тип сжатия (поддерживается только тип `'NONE'`).100101#### `getcompname()`102103Человекочитаемая версия [`getcomptype()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_read.getcomptype). Обычно `'not compressed'` соответствует `'NONE'`.104105#### `getparams()`106107Возвращает [`namedtuple()`](https://python-all.ru/3.16/library/collections.html#collections.namedtuple) `(nchannels, sampwidth, framerate, nframes, comptype, compname)`, эквивалентный выходным данным методов `get*()`.108109#### `readframes(n)`110111Читает и возвращает не более *n* кадров аудио в виде объекта [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes).112113#### `rewind()`114115Перемещает указатель файла в начало аудиопотока.116117Следующие два метода определяют термин «позиция», совместимый между ними, а в остальном зависящий от реализации.118119#### `setpos(pos)`120121Устанавливает указатель файла на указанную позицию.122123#### `tell()`124125Возвращает текущую позицию указателя файла.126127## Объекты Wave\_write128129#### `class wave.Wave_write`130131Записывает WAV-файл.132133Объекты Wave\_write, возвращаемые [`open()`](https://python-all.ru/3.16/library/wave.html#wave.open).134135Для потоков вывода с произвольным доступом заголовок `wave` будет автоматически обновлён, чтобы отражать фактически записанное количество кадров. Для потоков без произвольного доступа значение *nframes* должно быть точным на момент записи первых данных кадра. Точное значение *nframes* можно получить либо вызвав [`setnframes()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.setnframes) или [`setparams()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.setparams) с количеством кадров, которые будут записаны до вызова [`close()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.close), а затем используя [`writeframesraw()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.writeframesraw) для записи данных кадров, либо вызвав [`writeframes()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.writeframes) со всеми записываемыми данными кадров. В последнем случае `writeframes()` вычислит количество кадров в данных и соответствующим образом установит *nframes* перед записью данных кадров.136137Изменено в версии 3.4: Добавлена поддержка файлов без произвольного доступа.138139Объекты Wave\_write имеют следующие методы:140141#### `close()`142143Убеждается, что *nframes* корректен, и закрывает файл, если он был открыт через `wave`. Этот метод вызывается при сборке объекта. Он возбудит исключение, если выходной поток не поддерживает произвольный доступ и *nframes* не совпадает с фактически записанным количеством кадров.144145#### `setnchannels(n)`146147Устанавливает количество каналов.148149#### `getnchannels()`150151Возвращает количество каналов.152153#### `setsampwidth(n)`154155Устанавливает ширину семпла равной *n* байт.156157Для [`WAVE_FORMAT_IEEE_FLOAT`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_IEEE_FLOAT) поддерживается только ширина отсчёта 4 байта (32-бит) и 8 байт (64-бит).158159#### `getsampwidth()`160161Возвращает ширину семпла в байтах.162163#### `setframerate(n)`164165Устанавливает частоту дискретизации равной *n*.166167Изменено в версии 3.2: Нецелочисленный входной аргумент этого метода округляется до ближайшего целого.168169#### `getframerate()`170171Возвращает частоту дискретизации.172173#### `setnframes(n)`174175Устанавливает количество кадров равным *n*. Впоследствии это значение может измениться, если фактически записанное количество кадров будет отличаться (при попытке обновить значение будет вызвана ошибка, если выходной поток не поддерживает произвольный доступ).176177#### `getnframes()`178179Возвращает количество аудиокадров, записанных на данный момент.180181#### `setcomptype(type, name)`182183Устанавливает тип сжатия и описание. На данный момент поддерживается только тип сжатия `NONE`, то есть без сжатия.184185#### `getcomptype()`186187Возвращает тип сжатия (`'NONE'`).188189#### `getcompname()`190191Возвращает читаемое человеком название типа сжатия.192193#### `setformat(format)`194195Устанавливает код формата кадра.196197Поддерживаются значения [`WAVE_FORMAT_PCM`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_PCM) и [`WAVE_FORMAT_IEEE_FLOAT`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_IEEE_FLOAT).198199При установке [`WAVE_FORMAT_IEEE_FLOAT`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_IEEE_FLOAT) ширина отсчёта должна быть 4 или 8 байт.200201#### `getformat()`202203Возвращает текущий код формата кадра.204205#### `setparams(tuple)`206207*Кортеж* должен быть `(nchannels, sampwidth, framerate, nframes, comptype, compname, format)`, со значениями, допустимыми для методов `set*()`. Устанавливает все параметры.208209Для обратной совместимости также принимается кортеж из 6 элементов без *format* и по умолчанию равен [`WAVE_FORMAT_PCM`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_PCM).210211Для `format=WAVE_FORMAT_IEEE_FLOAT` *sampwidth* должен быть 4 или 8.212213#### `getparams()`214215Возвращает [`namedtuple()`](https://python-all.ru/3.16/library/collections.html#collections.namedtuple) `(nchannels, sampwidth, framerate, nframes, comptype, compname)` , содержащий текущие выходные параметры.216217#### `tell()`218219Возвращает текущую позицию в файле с теми же оговорками, что и для методов [`Wave_read.tell()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_read.tell) и [`Wave_read.setpos()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_read.setpos).220221#### `writeframesraw(data)`222223Записывает аудиокадры без коррекции *nframes*.224225Изменено в версии 3.4: Теперь принимается любой [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).226227#### `writeframes(data)`228229Записывает аудиокадры и проверяет, что *nframes* корректен. Будет вызвана ошибка, если выходной поток не поддерживает произвольный доступ, а общее количество кадров, записанных после записи *data*, не совпадает с ранее установленным значением для *nframes*.230231Изменено в версии 3.4: Теперь принимается любой [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).232233Обратите внимание, что устанавливать какие-либо параметры после вызова `writeframes()` или [`writeframesraw()`](https://python-all.ru/3.16/library/wave.html#wave.Wave_write.writeframesraw) недопустимо; любая попытка сделать это приведёт к возникновению [`wave.Error`](https://python-all.ru/3.16/library/wave.html#wave.Error).234235Для выходных данных [`WAVE_FORMAT_IEEE_FLOAT`](https://python-all.ru/3.16/library/wave.html#wave.WAVE_FORMAT_IEEE_FLOAT) записывается фрагмент `fact`, как того требует спецификация WAVE для форматов, отличных от PCM.236