# `sunau` --- 讀寫 Sun AU 檔案

原始碼：Lib/sunau.py

3.11 版後已棄用: `sunau` 模組 (module) 即將被棄用（詳見 PEP 594）。

`sunau` 模組 (module) 提供了一個處理 Sun AU 聲音格式的便利介面。請注意此模組與 `aifc` 和 `wave` 的介面是相容的。

音訊檔案由標頭 (header) 和資料組成。標頭包含以下欄位：

欄位 | 內容
--- | ---
magic word | 四個位元組 `.snd`。
header size | 標頭的大小，包括資訊，以位元組為單位。
data size | 資料的物理大小，以位元組為單位。
encoding | 表示音訊取樣的編碼方式。
sample rate | 取樣頻率。
# of channels | 取樣中的聲道數。
info | 音訊檔案描述的 ASCII 字串（會以空位元組填補 (pad)）。

除了 info 欄位以外，所有其他標頭中欄位的大小都是 4 位元組，他們都是以 big-endian 位元組順序所編碼的 32-bit（位元）unsigned integers（無符號整數）

`sunau` 模組定義了以下函式：

`sunau.``open`(file, mode)

  如 file 是一個字串，則以此名開啟檔案，否則把它當作一個可以被搜尋的 file-like object（類檔案物件）。mode 可以是以下任一

  `'r'`

    唯讀模式。

  `'w'`

    唯寫模式。

  請注意這並不允許讀/寫檔案。

  mode 若設為 `'r'` 則會回傳一個 `AU_read` 物件，若設為 `'w'` 或 `'wb'` 則回傳 `AU_write` 物件。

`sunau` 模組定義了以下例外：

exception `sunau.``Error`

  在不符合 Sun AU 規格或實作上有所不足而無法達成某些目的時會引發的錯誤。

`sunau` 模組定義了以下資料條目：

`sunau.``AUDIO_FILE_MAGIC`

  每個 Sun AU 檔案都會作為開頭的一個整數，以 big-endian 形式儲存。這也是 `.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 物件擁有以下 method（方法）：

`AU_read.``close`()

  關閉串流 (stream)，並使該實例無法被使用。（這會自動在刪除時呼叫。）

`AU_read.``getnchannels`()

  回傳音訊聲道數量（單聲道為 1，雙聲道為 2）。

`AU_read.``getsampwidth`()

  回傳取樣位元組長度。

`AU_read.``getframerate`()

  回傳取樣頻率。

`AU_read.``getnframes`()

  回傳音訊總幀數。

`AU_read.``getcomptype`()

  回傳壓縮種類。支援的壓縮種類有 `'ULAW'`、`'ALAW'` 和 `'NONE'`。

`AU_read.``getcompname`()

  可被人類讀懂 (human-readable) 的 `getcomptype()`。有被支援的種類分別有這些名稱 `'CCITT G.711 u-law'`、`'CCITT G.711 A-law'` 和 `'not compressed'`。

`AU_read.``getparams`()

  回傳一個 `namedtuple()` `(nchannels, sampwidth, framerate, nframes, comptype, compname)`，與 `get*()` methods 的輸出相同。

`AU_read.``readframes`(n)

  讀取並以 `bytes` 物件形式回傳音檔中至多 n 幀，資料會以線性格式 (linear format) 回傳，如果原始資料是 u-LAW 格式，則它會被轉換。

`AU_read.``rewind`()

  重置檔案指標 (file pointer) 至音訊開頭。

以下兩個 methods 都定義了在它們之間相容的 "position"，否則會與實作相依。

`AU_read.``setpos`(pos)

  設定檔案指標至指定的位置，只有 `tell()` 的回傳值應被做為 pos 使用。

`AU_read.``tell`()

  回傳當前檔案指標位置，要注意回傳值和真實檔案中的位置無關。

以下兩個函式單純是為了和 `aifc` 相容而定義，並沒有做什麼特別的。

`AU_read.``getmarkers`()

  回傳 `None`。

`AU_read.``getmark`(id)

  引發錯誤。

## AU_write 物件

如上述 `open()` 所回傳的 AU_write 物件擁有以下 methods：

`AU_write.``setnchannels`(n)

  設定聲道數。

`AU_write.``setsampwidth`(n)

  設定取樣寬度（以位元組為單位）。

  3.4 版更變: 新增對於 24-bit 取樣的支援。

`AU_write.``setframerate`(n)

  設定影格率 (frame rate)。

`AU_write.``setnframes`(n)

  設定幀數，該值可以在寫入更多幀後修改。

`AU_write.``setcomptype`(type, name)

  設定壓縮種類和敘述，輸出只支援 `'NONE'` 和 `'ULAW'`。

`AU_write.``setparams`(tuple)

  tuple 應為 `(nchannels, sampwidth, framerate, nframes, comptype, compname)` 形式，各個值應該要是 `set*()` methods 能有效接受的值。該函數會一次設定所有參數。

`AU_write.``tell`()

  回傳當前檔案中的位置，帶有和 `AU_read.tell()` 與 `AU_read.setpos()` 方法相同的免責聲明 (disclaimer)。

`AU_write.``writeframesraw`(data)

  寫入音訊資料但不更新 nframes。

  3.4 版更變: 現在可接受任意 bytes-like object。

`AU_write.``writeframes`(data)

  寫入音訊資料並更新 nframes 以確保其正確性。

  3.4 版更變: 現在可接受任意 bytes-like object。

`AU_write.``close`()

  確保 nframes 是正確的，並關閉檔案。

  此 method 會在刪除時呼叫。

請注意，在呼叫 `writeframes()` 或 `writeframesraw()` 後設定任何參數都是無效的。