22.4. "wave" --- 读写WAV格式文件
********************************

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

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

:mod:>>`<<wave`模块提供了一个处理WAV声音格式文件的便利接口，虽然不支持
压缩和解压，但支持单声道和多声道。

:mod:>>`<<wave`模块定义了以下函数和异常:

wave.open(file, mode=None)

   如果*file*是一个字符串，打开对应文件名的文件。否则就把它作为文件对
   象来处理，>>*<<mode*这个参数可以是一下几个值：

   "'rb'"
      只读。

   "'wb'"
      只写。

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

   A *mode* of "'rb'" returns a "Wave_read" object, while a *mode* of
   "'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*.

   如果操作的是文件对象，当使用wave对象的:meth:>>`<<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 版更改: Added support for unseekable files.

wave.openfp(file, mode)

   同:func:*.open*,用于向后兼容。

exception wave.Error

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


22.4.1. Wave_read对象
=====================

由:func:>>`<<.open`返回的Wave_read对象，有以下几种方法:

Wave_read.close()

   关闭:mod:>>`<<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 "namedtuple()" "(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 "bytes" object.

Wave_read.rewind()

   设置当前文件指针位置。

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

Wave_read.getmarkers()

   返回``None``.

Wave_read.getmark(id)

   引发错误异常。

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

Wave_read.setpos(pos)

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

Wave_read.tell()

   返回当前文件指针位置。


22.4.2. 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.

由:func:>>`<<.open`返回的Wave_write对象，有以下几种方法:

在 3.4 版更改: Added support for unseekable files.

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)``, 每项元素对应相应的:meth:>>`<<set*`方法的参数
   .

Wave_write.tell()

   返回当前文件指针，其指针含义和:meth:>>`<<Wave_read.tell`以及
   :meth:>>`<<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.

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