# `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.