# `wave` --- 讀寫 WAV 檔案

原始碼：Lib/wave.py

The `wave` module provides a convenient interface to the Waveform Audio "WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are supported.

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

The `wave` module defines the following function and exception:

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_read 物件

class wave.Wave_read

  讀取一個 WAV 檔案。

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

  close()

    Close the stream if it was opened by `wave`, and make the instance unusable. This is called automatically on object collection.

  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()

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

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

  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()

    Make sure nframes is correct, and close the file if it was opened by `wave`. This method is called upon object collection. It will raise an exception if the output stream is not seekable and nframes does not match the number of frames actually written.

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