audio — Audio Module

The audio module is used to record audio samples from a microphone. PDM samples captured from the microphone are filtered and decimated to PCM samples which can be passed to a user callback or read directly into a buffer.

Functions

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

Initializes the audio module. Must be called first before using the audio module.

channels is the number of audio channels. May be 1 or 2. Audio samples are interleaved when more than one channel is used. Multi-channel capture is only supported on boards with more than one microphone.

frequency is the PCM sample frequency in Hz. The set of supported frequencies is port/board specific.

gain_db is the microphone gain to apply, in decibels.

highpass is the high pass filter coefficient (STM32) or a boolean enabling the high pass filter (Alif). Ignored on ports that do not implement a high pass filter.

samples is the number of PCM samples to accumulate per callback. If set to -1 the value is computed automatically from the decimation factor and number of channels. Must be a multiple of 16. Available on the STM32 and Alif ports.

buffers is the number of internal PCM buffers used to queue samples between the DMA ISR and the user. Available on the Alif and RP2 ports.

overflow controls whether a buffer overflow raises RuntimeError. When False the oldest buffer is overwritten and streaming continues. Available on the Alif and RP2 ports.

clkdiv overrides the PIO clock divider used to drive the PDM clock. When 0 the divider is computed from the requested frequency. Available on the RP2 port.

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

Starts audio capture.

callback is called from the scheduler with a single argument pcmbuf each time a new PCM buffer is ready. pcmbuf is a signed 16-bit bytearray of PCM samples whose length is determined by the decimation factor, the number of channels and the samples argument passed to audio.init(). In single-channel mode each entry is one 16-bit sample; in dual-channel mode samples are interleaved in pairs.

On ports that support audio.get_buffer() (Alif and RP2), passing a non-callable value (e.g. None) starts capture without a callback so buffers can be drained with audio.get_buffer() instead.

audio.stop_streaming() → None

Stops audio capture and clears any installed callback.

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

Returns the next available PCM buffer. Blocks until a buffer is ready or until timeout milliseconds have elapsed (0 means wait forever). Raises RuntimeError if streaming is not enabled, if a buffer overflow has occurred while overflow is True, or if a streaming callback is installed.

Available on the Alif and RP2 ports.

audio.read_pdm(buf: bytearray) → None

Reads raw PDM samples from the microphone directly into buf. buf must be an array/bytearray whose element size matches the number of channels (1 byte for mono, 2 bytes for stereo).

Available on the STM32 port (SAI-based boards) only.

audio.samples() → int

Returns the total number of PCM samples captured since the last call to audio.start_streaming().

Available on the RP2 port only.

audio.overflow() → bool

Returns True if a buffer overflow has occurred since the last call to audio.start_streaming().

Available on the RP2 port only.