21.5. "wave" — 读写WAV格式文件
******************************

**源代码:** Lib/wave.py

======================================================================

"wave" 模块提供了一个处理 WAV 声音格式的便利接口。它不支持压缩/解压，
但是支持单声道/立体声。

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

wave.open(file[, mode])

   If *file* is a string, open the file by that name, otherwise treat
   it as a seekable file-like object.  *mode* can be any of

   "'r'", "'rb'"
      只读模式。

   "'w'", "'wb'"
      只写模式。

   注意不支持同时读写WAV文件。

   A *mode* of "'r'" or "'rb'" returns a "Wave_read" object, while a
   *mode* of "'w'" or "'wb'" returns a "Wave_write" object.  If *mode*
   is omitted and a file-like object is passed as *file*, "file.mode"
   is used as the default value for *mode* (the "'b'" flag is still
   added if necessary).

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

wave.openfp(file, mode)

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

exception wave.Error

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


21.5.1. 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()

   Returns a tuple "(nchannels, sampwidth, framerate, nframes,
   comptype, compname)", equivalent to output of the "get*()" methods.

Wave_read.readframes(n)

   Reads and returns at most *n* frames of audio, as a string of
   bytes.

Wave_read.rewind()

   设置当前文件指针位置。

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

Wave_read.getmarkers()

   返回 "None"。

Wave_read.getmark(id)

   引发错误异常。

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

Wave_read.setpos(pos)

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

Wave_read.tell()

   返回当前文件指针位置。


21.5.2. Wave_write 对象
=======================

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

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.

Wave_write.setnchannels(n)

   设置声道数。

Wave_write.setsampwidth(n)

   设置采样字节长度为 *n*。

Wave_write.setframerate(n)

   设置采样频率为 *n*。

Wave_write.setnframes(n)

   Set the number of frames to *n*. This will be changed later if more
   frames are written.

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*。

Wave_write.writeframes(data)

   Write audio frames and make sure *nframes* is correct.

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