"sunau" --- 读写 Sun AU 文件
****************************

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

从 3.11 版起不建议使用，将在 3.13 版中移除: "sunau" 模块已被弃用（请参
阅 **PEP 594** 了解详情）。

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

"sunau" 模拟提供了一个处理 Sun AU 声音格式的便利接口。请注意此模块与
"aifc" 和 "wave" 是兼容接口的。

音频文件由标头和数据组成。标头的字段为：

+-----------------+-------------------------------------------------+
| 域              | 目录                                            |
|=================|=================================================|
| magic word      | 四个字节 ".snd"                                 |
+-----------------+-------------------------------------------------+
| header size     | 标头的大小，包括信息，以字节为单位。            |
+-----------------+-------------------------------------------------+
| data size       | 数据的物理大小，以字节为单位。                  |
+-----------------+-------------------------------------------------+
| encoding        | 指示音频样本的编码方式。                        |
+-----------------+-------------------------------------------------+
| sample rate     | 采样率                                          |
+-----------------+-------------------------------------------------+
| # of channels   | 采样中的通道数。                                |
+-----------------+-------------------------------------------------+
| info            | 提供音频文件描述的ASCII字符串（用空字节填充）。 |
+-----------------+-------------------------------------------------+

除了 info 字段，所有标头字段的大小都是 4 字节。 它们都是采用大端字节序
编码的 32 位无符号整数。

"sunau" 模块定义了以下函数:

sunau.open(file, mode)

   如果 *file* 是一个字符串，打开相应名称的文件，否则就把它作为可定位
   的文件型对象来处理。 *mode* 可以是

   "'r'"
      只读模式。

   "'w'"
      只写模式。

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

   *mode* 为 "'r'" 时返回一个 "AU_read" 对象，而 *mode* 为 "'w'" 或
   "'wb'" 时返回一个 "AU_write" 对象。

"sunau" 模块定义了以下异常:

exception sunau.Error

   当 Sun AU 规范或实现的低效导致无法操作时引发的错误。

"sunau" 模块定义了以下数据条目:

sunau.AUDIO_FILE_MAGIC

   位于每个有效的 Sun AU 文件开头的整数，以大端序形式存储。 这是一个被
   当作整数来解读的字符串 ".snd"。

sunau.AUDIO_FILE_ENCODING_MULAW_8
sunau.AUDIO_FILE_ENCODING_LINEAR_8
sunau.AUDIO_FILE_ENCODING_LINEAR_16
sunau.AUDIO_FILE_ENCODING_LINEAR_24
sunau.AUDIO_FILE_ENCODING_LINEAR_32
sunau.AUDIO_FILE_ENCODING_ALAW_8

   AU 标头中被此模块所支持的 encoding 字段值。

sunau.AUDIO_FILE_ENCODING_FLOAT
sunau.AUDIO_FILE_ENCODING_DOUBLE
sunau.AUDIO_FILE_ENCODING_ADPCM_G721
sunau.AUDIO_FILE_ENCODING_ADPCM_G722
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

   AU 标头中附加的已知但不被此模块所支持的 encoding 字段值。


AU_read 对象
============

由上面的 "open()" 所返回的 AU_read 对象具有以下几种方法:

AU_read.close()

   关闭流，并使实例不可用。 （此方法会在删除对象时自动调用。）

AU_read.getnchannels()

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

AU_read.getsampwidth()

   返回采样字节长度。

AU_read.getframerate()

   返回采样频率。

AU_read.getnframes()

   返回音频总帧数。

AU_read.getcomptype()

   返回压缩类型。 受支持的压缩类型有 "'ULAW'", "'ALAW'" 和 "'NONE'"。

AU_read.getcompname()

   "getcomptype()" 的人类可读的版本。 受支持的类型将为相应的名称
   "'CCITT G.711 u-law'", "'CCITT G.711 A-law'" 和 "'not compressed'"
   。

AU_read.getparams()

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

AU_read.readframes(n)

   读取至多 *n* 帧音频并作为 "bytes" 对象返回。 数据将以线性格式返回。
   如果原始数据为 u-LAW 格式，则它将被转换。

AU_read.rewind()

   重置文件指针至音频开头.

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

AU_read.setpos(pos)

   设置文件指针到特定位置。 只有从 "tell()" 返回的值才可被用作 *pos*。

AU_read.tell()

   返回当前文件指针的位置。 请注意该返回值与文件中的实例位置无关。

以下两个函数是为了与 "aifc" 保持兼容而定义的，实际不做任何事情。

AU_read.getmarkers()

   返回 "None"。

AU_read.getmark(id)

   引发错误异常。


AU_write 对象
=============

由上面的 "open()" 所返回的 AU_write 对象具有以下几种方法:

AU_write.setnchannels(n)

   设置声道数。

AU_write.setsampwidth(n)

   设置采样宽度（字节长度。）

   在 3.4 版本发生变更: 增加了对 24 位采样的支持。

AU_write.setframerate(n)

   设置帧速率。

AU_write.setnframes(n)

   设置总帧数。 如果写入了更多的帧，此值将会被更改。

AU_write.setcomptype(type, name)

   设置压缩类型和描述。 对于输出只支持 "'NONE'" 和 "'ULAW'"。

AU_write.setparams(tuple)

   *tuple* 应该是 "(nchannels, sampwidth, framerate, nframes,
   comptype, compname)"，每项的值可用于 "set*()" 方法。 设置所有形参。

AU_write.tell()

   返回文件中的当前位置，其含义与 "AU_read.tell()" 和
   "AU_read.setpos()" 方法的一致。

AU_write.writeframesraw(data)

   写入音频数据但不更新 *nframes*。

   在 3.4 版本发生变更: 现在可接受任意 *bytes-like object*。

AU_write.writeframes(data)

   写入音频数据并更新 *nframes*。

   在 3.4 版本发生变更: 现在可接受任意 *bytes-like object*。

AU_write.close()

   确保 *nframes* 正确，并关闭文件。

   此方法会在删除时被调用。

请注意在调用 "writeframes()" 和 "writeframesraw()" 之后再设置任何形参
都是无效的。
