wave — 读取和写入 WAV 文件

源代码: Lib/wave.py

---

wave 模块提供了 Waveform Audio “WAVE”（或“WAV”）文件格式的便捷接口。仅支持未压缩的 PCM 编码 wave 文件。

3.12 版本中的变化: 增加了对 WAVE_FORMAT_EXTENSIBLE 头的支持，前提是扩展格式为 KSDATAFORMAT_SUBTYPE_PCM。

wave 模块定义了以下函数和异常

wave.open(file, mode=None)

如果 file 是一个字符串，则按该名称打开文件；否则，将其视为文件类对象。mode 可以是

'rb'

只读模式。

'wb'

只写模式。

请注意，它不允许读/写 WAV 文件。

'rb' 模式返回一个 Wave_read 对象，而 '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 对象

class wave.Wave_read

读取 WAV 文件。

由 open() 返回的 Wave_read 对象具有以下方法

close()

如果流是由 wave 打开的，则关闭流，并使实例不可用。这会在对象被回收时自动调用。

getnchannels()

返回音频通道数（单声道为 1，立体声为 2）。

getsampwidth()

返回以字节为单位的采样宽度。

getframerate()

返回采样频率。

getnframes()

返回音频帧数。

getcomptype()

返回压缩类型（'NONE' 是唯一支持的类型）。

getcompname()

getcomptype() 的人类可读版本。通常 'not compressed' 与 'NONE' 相对应。

getparams()

返回一个 namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname)，相当于 get*() 方法的输出。

readframes(n)

读取并返回最多 n 帧音频，作为 bytes 对象。

rewind()

将文件指针倒回到音频流的开头。

以下两个方法是为与旧的 aifc 模块兼容而定义的，并没有任何有趣的功能。

getmarkers()

返回 None。

自 3.13 版本弃用，将于 3.15 版本移除: 该方法仅为了与 aifc 模块兼容而存在，该模块已在 Python 3.13 中移除。

getmark(id)

引发错误。

自 3.13 版本弃用，将于 3.15 版本移除: 该方法仅为了与 aifc 模块兼容而存在，该模块已在 Python 3.13 中移除。

以下两个方法定义了一个在它们之间兼容的“位置”术语，并且否则是实现相关的。

setpos(pos)

将文件指针设置为指定位置。

tell()

返回当前文件指针位置。

Wave_write 对象

class wave.Wave_write

写入 WAV 文件。

由 open() 返回的 Wave_write 对象。

对于可查找的输出流，wave 头部将自动更新以反映实际写入的帧数。对于不可查找的流，当写入第一个帧数据时，nframes 值必须准确。可以通过调用 setnframes() 或 setparams() 并传入在调用 close() 之前将写入的帧数，然后使用 writeframesraw() 写入帧数据，或者通过调用 writeframes() 并传入所有要写入的帧数据来获得准确的 nframes 值。在后一种情况下，writeframes() 将计算数据中的帧数并相应地设置 nframes，然后再写入帧数据。

3.4 版本中的变化: 增加了对不可查找文件的支持。

Wave_write 对象具有以下方法

close()

确保 nframes 正确，如果文件是由 wave 打开的，则关闭文件。此方法在对象回收时调用。如果输出流不可查找且 nframes 与实际写入的帧数不匹配，则会引发异常。

setnchannels(n)

设置通道数。

setsampwidth(n)

设置采样宽度为 n 字节。

setframerate(n)

设置帧率为 n。

3.2 版本中的变化: 对此方法的非整数输入将四舍五入到最接近的整数。

setnframes(n)

设置帧数为 n。如果实际写入的帧数不同，稍后将更改此值（如果输出流不可查找，此更新尝试将引发错误）。

setcomptype(type, name)

设置压缩类型和描述。目前，只支持压缩类型 NONE，表示不压缩。

setparams(tuple)

tuple 应为 (nchannels, sampwidth, framerate, nframes, comptype, compname)，其值对 set*() 方法有效。设置所有参数。

tell()

返回文件中当前位置，与 Wave_read.tell() 和 Wave_read.setpos() 方法具有相同的免责声明。

writeframesraw(data)

写入音频帧，不校正 nframes。

3.4 版本中的变化: 现在接受任何类字节对象。

writeframes(data)

写入音频帧并确保 nframes 正确。如果输出流不可查找，并且在写入 data 后已写入的总帧数与之前为 nframes 设置的值不匹配，则会引发错误。

3.4 版本中的变化: 现在接受任何类字节对象。

请注意，在调用 writeframes() 或 writeframesraw() 之后设置任何参数都是无效的，任何尝试这样做都会引发 wave.Error。