"wave" --- 讀寫 WAV 檔案
************************

**原始碼：**Lib/wave.py

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

"wave" 模組為波形音訊檔案格式「WAVE」（或稱「WAV」）提供了便捷的介面。
僅支援未壓縮的 PCM 編碼波形檔。

在 3.12 版的變更: 增加了標頭  "WAVE_FORMAT_EXTENSIBLE" 的支援，要求的
擴展格式為 "KSDATAFORMAT_SUBTYPE_PCM"。

"wave" 模組定義了以下的函式和例外:

wave.open(file, mode=None)

   如果 *file* 是一個字串，會打開對應名稱的檔案，否則會以類檔案物件處
   理。*mode* 可以是：

   "'rb'"
      唯讀模式。

   "'wb'"
      唯寫模式。

   請注意，不支援同時讀寫 WAV 檔案。

   *mode* 設定為 "'rb'" 時，會回傳一個 "Wave_read" 物件，*mode* 設定為
   "'wb'" 時，則回傳一個 "Wave_write" 物件。如果省略 *mode*，並且將類
   檔案 (file-like) 物件作為 *file* 參數傳遞，則 "file.mode" 會是
   *mode* 的預設值。

   如果你傳遞一個類檔案物件，當呼叫其 "close()" 方法時，wave 物件不會
   自動關閉該物件；關閉檔案物件的責任會在呼叫者上。

   "open()" 函式可以在 "with" 陳述式中使用。當 "with" 區塊完成時，會呼
   叫 "Wave_read.close()" 或是 "Wave_write.close()" 方法。

   在 3.4 版的變更: 增加對不可搜尋 (unseekable) 檔案的支援。

exception wave.Error

   當不符合 WAV 格式或無法操作時會引發錯誤。


Wave_read 物件
==============

class wave.Wave_read

   讀取一個 WAV 檔案。

   由 "open()" 回傳的 Wave_read 物件具有以下方法：

   close()

      關閉 "wave" 開啟的串流並使該實例無法使用。當物件回收時自動呼叫。

   getnchannels()

      回傳音訊聲道的數量（單聲道為 "1"，立體聲為 "2"）。

   getsampwidth()

      回傳以位元組表示的取樣寬度 (sample width)。

   getframerate()

      回傳取樣率。

   getnframes()

      回傳音訊幀數。

   getcomptype()

      回傳壓縮類型（僅支援 "'NONE'" 類型）。

   getcompname()

      "getcomptype()" 的人類可讀的版本。通常使用 "'not compressed'" 代
      替 "'NONE'"。

   getparams()

      回傳一個 "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)"，等同於 "get*()" 方法的輸出。

   readframes(n)

      讀取並回傳以 "bytes" 物件表示的最多 *n* 個音訊幀。

   rewind()

      重置檔案指標至音訊流的開頭。

   The following two methods are defined for compatibility with the
   old "aifc" module, and don't do anything interesting.

   getmarkers()

      回傳 "None"。

      Deprecated since version 3.13, will be removed in version 3.15:
      The method only existed for compatibility with the "aifc" module
      which has been removed in Python 3.13.

   getmark(id)

      引發錯誤。

      Deprecated since version 3.13, will be removed in version 3.15:
      The method only existed for compatibility with the "aifc" module
      which has been removed in Python 3.13.

   以下兩個方法所定義的「位置」，在它們之間是相容的，但其他情況下則取
   決於具體實作方式。

   setpos(pos)

      將檔案指標設定為指定的位置。

   tell()

      回傳目前的檔案指標位置。


Wave_write 物件
===============

class wave.Wave_write

   寫入一個 WAV 檔案。

   Wave_write 物件，由 "open()" 回傳。

   對於可搜尋 (seekable) 的輸出串流，"wave" 標頭將自動更新，以反映實際
   寫入的幀數。對於不可搜尋的串流，當寫入第一個幀資料時，*nframes* 的
   值必須是準確的。要取得準確的 *nframes* 值，可以通過呼叫
   "setnframes()" 或 "setparams()" 方法，並在呼叫 "close()" 之前設定將
   寫入的幀數量，然後使用 "writeframesraw()" 方法寫入幀資料；或者通過
   呼叫 "writeframes()" 方法一次性寫入所有的幀資料。在後一種情況下，
   "writeframes()" 方法將計算資料中的幀數量，並在寫入幀資料之前相應地
   設定 *nframes* 的值。

   在 3.4 版的變更: 增加對不可搜尋 (unseekable) 檔案的支援。

   Wave_write 物件具有以下方法：

   close()

      確保 *nframes* 正確，如果該檔案是由 "wave" 開啟的，則關閉該檔案
      。此方法在物件回收時被呼叫。如果輸出串流不可搜尋且 *nframes* 不
      符合實際寫入的幀數，則會引發例外。

   setnchannels(n)

      設定音訊的通道數量。

   setsampwidth(n)

      設定取樣寬度為 *n* 個位元組。

   setframerate(n)

      設定取樣頻率為 *n*。

      在 3.2 版的變更: 此方法的非整數輸入會被將四捨五入到最接近的整數
      。

   setnframes(n)

      設定幀數為 *n*。如果實際寫入的幀數不同，則稍後將進行更改（如果輸
      出串流不可搜尋，則此嘗試將引發錯誤）。

   setcomptype(type, name)

      設定壓縮類型和描述。目前只支援壓縮類型為 "NONE"，表示無壓縮。

   setparams(tuple)

      這個 *tuple* 應該是 "(nchannels, sampwidth, framerate, nframes,
      comptype, compname)"，值需要是符合 "set*()" 方法的參數。設定所有
      參數。

   tell()

      回傳檔案中的指標位置，其指標位置含意與 "Wave_read.tell()" 和
      "Wave_read.setpos()" 是一致的。

   writeframesraw(data)

      寫入音訊幀，不修正 *nframes*。

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

   writeframes(data)

      寫入音訊幀並確保 *nframes* 正確。如果輸出串流不可搜尋，並且在寫
      入 *data* 後已寫入的總幀數與先前設定的 *nframes* 值不符，則會引
      發錯誤。

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

      注意在呼叫 "writeframes()" 或 "writeframesraw()" 之後設置任何參
      數都是無效的，任何嘗試這樣做的操作都會引發 "wave.Error"。
