sunau --- 讀寫 Sun AU 檔案

原始碼:Lib/sunau.py

自從版本 3.11 後不推薦使用,將會自版本 3.13 中移除。: sunau 模組 (module) 即將被棄用(詳見 PEP 594)。


sunau 模組 (module) 提供了一個處理 Sun AU 聲音格式的便利介面。請注意此模組與 aifcwave 的介面是相容的。

音訊檔案由標頭 (header) 和資料組成。標頭包含以下欄位:

欄位

內容

magic word

四個位元組 .snd

header size

標頭的大小,包括資訊,以位元組為單位。

data size

資料的物理大小,以位元組為單位。

encoding

表示音訊取樣的編碼方式。

sample rate

取樣頻率。

# of channels

取樣中的聲道數。

info

音訊檔案描述的 ASCII 字串(會以空位元組填補 (pad))。

除了 info 欄位以外,所有其他標頭中欄位的大小都是 4 位元組,他們都是以 big-endian 位元組順序所編碼的 32-bit(位元)unsigned integers(無符號整數)

sunau 模組定義了以下函式:

sunau.open(file, mode)

file 是一個字串,則以此名開啟檔案,否則把它當作一個可以被搜尋的 file-like object(類檔案物件)。mode 可以是以下任一

'r'

唯讀模式。

'w'

唯寫模式。

請注意這並不允許讀/寫檔案。

mode 若設為 'r' 則會回傳一個 AU_read 物件,若設為 'w''wb' 則回傳 AU_write 物件。

sunau 模組定義了以下例外:

exception sunau.Error

在不符合 Sun AU 規格或實作上有所不足而無法達成某些目的時會引發的錯誤。

sunau 模組定義了以下資料條目:

sunau.AUDIO_FILE_MAGIC

每個 Sun AU 檔案都會作為開頭的一個整數,以 big-endian 形式儲存。這也是 .snd 所直接轉譯成一個整數的字串。

sunau.AUDIO_FILE_ENCODING_MULAW_8
sunau.AUDIO_FILE_ENCODING_LINEAR_8
sunau.AUDIO_FILE_ENCODING_LINEAR_16
sunau.AUDIO_FILE_ENCODING_LINEAR_24
sunau.AUDIO_FILE_ENCODING_LINEAR_32
sunau.AUDIO_FILE_ENCODING_ALAW_8

此模組有支援的 AU 標頭中 encoding 欄位值。

sunau.AUDIO_FILE_ENCODING_FLOAT
sunau.AUDIO_FILE_ENCODING_DOUBLE
sunau.AUDIO_FILE_ENCODING_ADPCM_G721
sunau.AUDIO_FILE_ENCODING_ADPCM_G722
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

額外已知的 AU 標頭中 encoding 欄位值,但不被此模組支援。

AU_read 物件

如上述 open() 所回傳的 AU_read 物件擁有以下 method(方法):

AU_read.close()

關閉串流 (stream),並使該實例無法被使用。(這會自動在刪除時呼叫。)

AU_read.getnchannels()

回傳音訊聲道數量(單聲道為 1,雙聲道為 2)。

AU_read.getsampwidth()

回傳取樣位元組長度。

AU_read.getframerate()

回傳取樣頻率。

AU_read.getnframes()

回傳音訊總幀數。

AU_read.getcomptype()

回傳壓縮種類。支援的壓縮種類有 'ULAW''ALAW''NONE'

AU_read.getcompname()

可被人類讀懂 (human-readable) 的 getcomptype()。有被支援的種類分別有這些名稱 'CCITT G.711 u-law''CCITT G.711 A-law''not compressed'

AU_read.getparams()

回傳一個 namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname),與 get*() methods 的輸出相同。

AU_read.readframes(n)

讀取並以 bytes 物件形式回傳音檔中至多 n 幀,資料會以線性格式 (linear format) 回傳,如果原始資料是 u-LAW 格式,則它會被轉換。

AU_read.rewind()

重置檔案指標 (file pointer) 至音訊開頭。

以下兩個 methods 都定義了在它們之間相容的 "position",否則會與實作相依。

AU_read.setpos(pos)

設定檔案指標至指定的位置,只有 tell() 的回傳值應被做為 pos 使用。

AU_read.tell()

回傳當前檔案指標位置,要注意回傳值和真實檔案中的位置無關。

以下兩個函式單純是為了和 aifc 相容而定義,並沒有做什麼特別的。

AU_read.getmarkers()

回傳 None

AU_read.getmark(id)

引發錯誤。

AU_write 物件

如上述 open() 所回傳的 AU_write 物件擁有以下 methods:

AU_write.setnchannels(n)

設定聲道數。

AU_write.setsampwidth(n)

設定取樣寬度(以位元組為單位)。

在 3.4 版的變更: 新增對於 24-bit 取樣的支援。

AU_write.setframerate(n)

設定影格率 (frame rate)。

AU_write.setnframes(n)

設定幀數,該值可以在寫入更多幀後修改。

AU_write.setcomptype(type, name)

設定壓縮種類和敘述,輸出只支援 'NONE''ULAW'

AU_write.setparams(tuple)

tuple 應為 (nchannels, sampwidth, framerate, nframes, comptype, compname) 形式,各個值應該要是 set*() methods 能有效接受的值。該函數會一次設定所有參數。

AU_write.tell()

回傳當前檔案中的位置,帶有和 AU_read.tell()AU_read.setpos() 方法相同的免責聲明 (disclaimer)。

AU_write.writeframesraw(data)

寫入音訊資料但不更新 nframes

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

AU_write.writeframes(data)

寫入音訊資料並更新 nframes 以確保其正確性。

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

AU_write.close()

確保 nframes 是正確的,並關閉檔案。

此 method 會在刪除時呼叫。

請注意,在呼叫 writeframes()writeframesraw() 後設定任何參數都是無效的。