audio --- 音訊模組

audio 模組用於從麥克風錄製音訊取樣。從麥克風擷取的 PDM 取樣會經過濾波與降取樣，轉換成 PCM 取樣，再傳遞給使用者回呼函式或直接讀入緩衝區。

函式

audio.init(channels: int = 1, frequency: int = 16000, gain_db: int = 24, highpass: float | bool = 0.9883, samples: int = -1, buffers: int = 16, overflow: bool = True, clkdiv: int = 0) → None

初始化音訊模組。在使用音訊模組之前必須先呼叫此函式。

channels 是音訊聲道數量。可為 1 或 2。當使用一個以上的聲道時，音訊取樣會交錯排列。多聲道擷取僅在具有多個麥克風的開發板上支援。

frequency 是以 Hz 為單位的 PCM 取樣頻率。支援的頻率組合視 port／開發板而定。

gain_db 是要套用的麥克風增益，單位為分貝。

highpass 是高通濾波器係數（STM32）或啟用高通濾波器的布林值（Alif）。在未實作高通濾波器的 port 上會被忽略。

samples 是每次回呼要累積的 PCM 取樣數量。若設為 -1，則會根據降取樣係數與聲道數量自動計算其值。必須是 16 的倍數。可在 STM32 與 Alif port 上使用。

buffers 是用於在 DMA ISR 與使用者之間排入取樣佇列的內部 PCM 緩衝區數量。可在 Alif 與 RP2 port 上使用。

overflow 控制緩衝區溢位是否引發 RuntimeError。當設為 False 時，最舊的緩衝區會被覆寫，串流會繼續進行。可在 Alif 與 RP2 port 上使用。

clkdiv 覆寫用於驅動 PDM 時脈的 PIO 時脈除數。當設為 0 時，除數會根據要求的頻率計算得出。可在 RP2 port 上使用。

audio.start_streaming(callback: Callable[[bytearray], None] | None) → None

開始音訊擷取。

每當有新的 PCM 緩衝區就緒時，callback 就會由排程器以單一引數 pcmbuf 呼叫。pcmbuf 是一個帶正負號的 16 位元 bytearray PCM 取樣，其長度由降取樣係數、聲道數量以及傳遞給 audio.init() 的 samples 引數決定。在單聲道模式中，每個項目為一個 16 位元取樣；在雙聲道模式中，取樣會成對交錯排列。

在支援 audio.get_buffer() 的 port（Alif 與 RP2）上，傳入不可呼叫的值（例如 None）會在沒有回呼函式的情況下開始擷取，如此便可改用 audio.get_buffer() 來取出緩衝區。

audio.stop_streaming() → None

停止音訊擷取並清除任何已安裝的回呼函式。

audio.get_buffer(timeout: int = 0) → bytearray

傳回下一個可用的 PCM 緩衝區。會封鎖直到有緩衝區就緒，或直到經過 timeout 毫秒為止（0 表示永遠等待）。若串流未啟用、若在 overflow 為 True 時發生緩衝區溢位，或若已安裝串流回呼函式，則引發 RuntimeError。

可在 Alif 與 RP2 port 上使用。

audio.read_pdm(buf: bytearray) → None

從麥克風讀取原始 PDM 取樣，直接讀入 buf。buf 必須是元素大小與聲道數量相符的 array／bytearray（單聲道為 1 位元組，立體聲為 2 位元組）。

僅可在 STM32 port（採用 SAI 的開發板）上使用。

audio.samples() → int

傳回自上次呼叫 audio.start_streaming() 以來所擷取的 PCM 取樣總數。

僅可在 RP2 port 上使用。

audio.overflow() → bool

若自上次呼叫 audio.start_streaming() 以來發生過緩衝區溢位，則傳回 True。

僅可在 RP2 port 上使用。