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。