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

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

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

The "wave" module provides a convenient interface to the Waveform
Audio "WAVE" (or "WAV") file format.

The module supports uncompressed PCM and IEEE floating-point WAV
formats.

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

在 3.15 版的變更: Support for reading and writing
"WAVE_FORMAT_IEEE_FLOAT" files was added.

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

wave.open(file, mode=None)

   If *file* is a string, a *path-like object* or a *bytes-like
   object* open the file by that name, otherwise treat it as a file-
   like object.  *mode* can be:

   "'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) 檔案的支援。

   在 3.15 版的變更: Added support for *path-like objects* and *bytes-
   like objects*.

exception wave.Error

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

wave.WAVE_FORMAT_PCM

   Format code for uncompressed PCM audio.

wave.WAVE_FORMAT_IEEE_FLOAT

   Format code for IEEE floating-point audio.

wave.WAVE_FORMAT_EXTENSIBLE

   Format code for WAVE extensible headers.


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

class wave.Wave_read

   讀取一個 WAV 檔案。

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

   close()

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

   getnchannels()

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

   getsampwidth()

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

   getframerate()

      回傳取樣率。

   getnframes()

      回傳音訊訊框數。

   getformat()

      Returns the frame format code.

      This is one of "WAVE_FORMAT_PCM", "WAVE_FORMAT_IEEE_FLOAT", or
      "WAVE_FORMAT_EXTENSIBLE".

   getcomptype()

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

   getcompname()

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

   getparams()

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

   readframes(n)

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

   rewind()

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

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

   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)

      設定音訊的通道數量。

   getnchannels()

      回傳音訊的通道數量。

   setsampwidth(n)

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

      For "WAVE_FORMAT_IEEE_FLOAT", only 4-byte (32-bit) and 8-byte
      (64-bit) sample widths are supported.

   getsampwidth()

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

   setframerate(n)

      設定訊框速率為 *n*。

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

   getframerate()

      回傳訊框速率。

   setnframes(n)

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

   getnframes()

      回傳目前為止已寫入的音訊訊框數。

   setcomptype(type, name)

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

   getcomptype()

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

   getcompname()

      回傳人類可讀的壓縮類型名稱。

   setformat(format)

      Set the frame format code.

      Supported values are "WAVE_FORMAT_PCM" and
      "WAVE_FORMAT_IEEE_FLOAT".

      When setting "WAVE_FORMAT_IEEE_FLOAT", the sample width must be
      4 or 8 bytes.

   getformat()

      Return the current frame format code.

   setparams(tuple)

      The *tuple* should be "(nchannels, sampwidth, framerate,
      nframes, comptype, compname, format)", with values valid for the
      "set*()" methods. Sets all parameters.

      For backwards compatibility, a 6-item tuple without *format* is
      also accepted and defaults to "WAVE_FORMAT_PCM".

      For "format=WAVE_FORMAT_IEEE_FLOAT", *sampwidth* must be 4 or 8.

   getparams()

      回傳一個 "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)"，包含目前的輸出參數。

   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"。

      For "WAVE_FORMAT_IEEE_FLOAT" output, a "fact" chunk is written
      as required by the WAVE specification for non-PCM formats.
