"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()" 後設定任何參數都
是無效的。
