# `sunau` --- 读写 Sun AU 文件

源代码: Lib/sunau.py

3.11 版後已棄用: The `sunau` module is deprecated (see PEP 594 for details).

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

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

域 | 内容
--- | ---
magic word | 四个字节 `.snd`
header size | 标头的大小，包括信息，以字节为单位。
data size | 数据的物理大小，以字节为单位。
编码 | 指示音频样本的编码方式。
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()` 之后再设置任何形参都是无效的。