# `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` 会被用作 mode 的默认值。

  如果操作的是文件对象，当使用 wave 对象的 `close()` 方法时，并不会真正关闭文件对象，这需要调用者负责来关闭文件对象。

  The `open()` function may be used in a `with` statement. When the `with` block completes, the `Wave_read.close()` or `Wave_write.close()` method is called.

  在 3.4 版更改: 添加了对不可搜索文件的支持。

`wave.``openfp`(file, mode)

  同 `open()`，用于向后兼容。

  Deprecated since version 3.7, will be removed in version 3.9.

exception `wave.``Error`

  当不符合WAV格式或无法操作时引发的错误。

## Wave_read对象

由 `open()` 返回的 Wave_read 对象，有以下几种方法:

`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)

  读取并返回以 `bytes` 对象表示的最多 n 帧音频。

`Wave_read.``rewind`()

  设置当前文件指针位置。

后面两个方法是为了和 `aifc` 保持兼容，实际不做任何事情。

`Wave_read.``getmarkers`()

  返回 `None`。

`Wave_read.``getmark`(id)

  引发错误异常。

以下两个方法都使用指针，具体实现由其底层决定。

`Wave_read.``setpos`(pos)

  设置文件指针到指定位置。

`Wave_read.``tell`()

  返回当前文件指针位置。

## Wave_write 对象

For seekable output streams, the `wave` header will automatically be updated to reflect the number of frames actually written. For unseekable streams, the nframes value must be accurate when the first frame data is written. An accurate nframes value can be achieved either by calling `setnframes()` or `setparams()` with the number of frames that will be written before `close()` is called and then using `writeframesraw()` to write the frame data, or by calling `writeframes()` with all of the frame data to be written. In the latter case `writeframes()` will calculate the number of frames in the data and set nframes accordingly before writing the frame data.

由 `open()` 返回的 Wave_write 对象，有以下几种方法:

在 3.4 版更改: 添加了对不可搜索文件的支持。

`Wave_write.``close`()

  Make sure nframes is correct, and close the file if it was opened by `wave`. This method is called upon object collection. It will raise an exception if the output stream is not seekable and nframes does not match the number of frames actually written.

`Wave_write.``setnchannels`(n)

  设置声道数。

`Wave_write.``setsampwidth`(n)

  设置采样字节长度为 n。

`Wave_write.``setframerate`(n)

  设置采样频率为 n。

  在 3.2 版更改: A non-integral input to this method is rounded to the nearest integer.

`Wave_write.``setnframes`(n)

  Set the number of frames to n. This will be changed later if the number of frames actually written is different (this update attempt will raise an error if the output stream is not seekable).

`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 版更改: Any bytes-like object is now accepted.

`Wave_write.``writeframes`(data)

  Write audio frames and make sure nframes is correct. It will raise an error if the output stream is not seekable and the total number of frames that have been written after data has been written does not match the previously set value for nframes.

  在 3.4 版更改: Any bytes-like object is now accepted.

注意在调用 `writeframes()` 或 `writeframesraw()` 之后再设置任何格式参数是无效的，而且任何这样的尝试将引发 `wave.Error`。