Source code for audiopump

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Run an audio graph off the interpreter thread.

`spawn` pulls a graph of audio samples (a `audiomixer.Mixer`, a
`synthio.Synthesizer`, effects) on a thread the interpreter is not on, so the
audio keeps an exact clock while a screen redraws or Python does anything
else. A platform driver supplies the thread and the output; `driver` says
which one bound. Where there is no thread, the pump runs in service mode:
`spawn` adopts the graph and nothing is pulled until you call `service`.

`Ring` lets Python push PCM into the graph, `DriftResampler` plays a ring that
something else fills on its own clock, `Events` schedules notes on the audio
clock, and `Tap` reads what is going out.

The CPython wheel and every MicroPython port carry this whole module.
CircuitPython carries only `Ring` and `DriftResampler`, because its playback
layer already pulls from its own audio thread.
"""

from __future__ import annotations
from types import TracebackType
from typing import Protocol, Self

__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""

class _AudioSample(Protocol):
    @property
    def sample_rate(self) -> int: ...
    @property
    def bits_per_sample(self) -> int: ...
    @property
    def channel_count(self) -> int: ...

STATUS_WORDS: int
"""How many 64-bit words the status block holds: 34."""
STATUS_BYTES: int
"""How many bytes the status block holds, which is the size of the buffer
`spawn` and `pull` take for ``status``: 272."""

SERVICE_MORE: int
"""`service` result: there is more to do."""
SERVICE_FULL: int
"""`service` result: the output ring has no room for another block."""
SERVICE_PARKED: int
"""`service` result: the pump is parked."""
SERVICE_DONE: int
"""`service` result: the pump has ended."""
C_SINK: bool
"""Whether `spawn` takes a C sink as ``sink``. False on CPython."""
SERVICE_MASK: int
"""Mask for the reason in a `service` result: ``result & SERVICE_MASK``."""
SERVICE_SHIFT: int
"""Shift for the block count in a `service` result:
``result >> SERVICE_SHIFT``."""

PRESS: int
"""`Events.at` operation: press a note on a `synthio.Synthesizer`."""
RELEASE: int
"""`Events.at` operation: release a note on a `synthio.Synthesizer`."""
RELEASE_ALL: int
"""`Events.at` operation: release every note on a `synthio.Synthesizer`."""
PLAY: int
"""`Events.at` operation: play a sample on an `audiomixer.MixerVoice`."""
STOP: int
"""`Events.at` operation: stop an `audiomixer.MixerVoice`."""
LEVEL: int
"""`Events.at` operation: set an `audiomixer.MixerVoice`'s level."""
STRIKE: int
"""`Events.at` operation: strike an `audiomodal.Bank` with a table of modes."""
CHOKE: int
"""`Events.at` operation: stop an `audiomodal.Bank` ringing."""

[docs] def spawn( sample: _AudioSample, blocks: int, status: bytearray | memoryview, sink: str | bool | bytes | None = None, ring: bytearray | memoryview | None = None, core: int = -1, prio: int = 21, stack: int = 16384, psram: bool = False, timeout_ms: int = 200, pace: bool = False, loop: bool = False, sink_room: int = 0, sink_gain: float | None = None, ) -> int: """Start pulling a graph on a thread of its own. Only one pump can run at a time; call `shutdown` before spawning another. A graph made of an `audiocore.WaveFile`, `audiomp3.MP3Decoder` or `audiovorbis.VorbisDecoder` is refused, because those read their files through the interpreter inside the pull: fill a `Ring` from the interpreter instead. Args: sample: The tail of the graph to pull. blocks: How many blocks to pull before stopping. A large number such as 0x7FFFFFFF plays until `stop` or `shutdown`. status: A writable buffer of at least `STATUS_BYTES` bytes that the pump fills with counters, as `STATUS_WORDS` little-endian 64-bit words. Word 0 is blocks pulled, 1 bytes seen, 2 an FNV-1a digest of every byte, 3 the last pull's result, 4 whether the loop is running, 5 the error (0 none, 1 buffer, 2 null, 3 done, 6 the C sink closed), 14 sink timeouts and 24 the fault code. Read it with ``struct.unpack``. sink: Where the audio goes. True sends it to the board's I2S output when the driver has opened one; a path writes it to a file on a desktop. Bytes holding a C sink that another native module published, such as a USB speaker's ``c_sink()``, send it there from the pump's own thread: the graph must be signed 16-bit at the sink's rate and channel count, and the pump ends with error 6 when the sink closes. None sends it nowhere. ring: A writable buffer of at least 64 bytes to write the audio into instead, which `drain` empties. core: The CPU core to run on, on ports that have cores. -1 lets the driver choose. prio: The thread's priority, on ports that have one. stack: The thread's stack in bytes, on ports that need one. psram: Whether the thread's stack goes in PSRAM, where the port has it. timeout_ms: How long the pump waits on a full sink before counting a timeout. pace: On a desktop, pull at the graph's own sample rate in real time. loop: Rewind the tail and carry on when it reports it is done, as ``audiobusio.I2SOut.play(sample, loop=True)`` does. sink_room: For a C sink, the bytes of room it must have before the pump writes a block. The pump then keeps the sink's capacity less this much queued, which is the delay it adds, however large the sink's own buffer is. 0 writes whenever anything fits. sink_gain: For a C sink, the level the audio goes to it at, 0.0 to 1.0. None is 1.0. `sink_gain` changes it while the pump plays. Returns: The core the thread runs on, or -1 when it has no core affinity, or -2 in service mode, where no thread was made. Raises: ValueError: A pump is already spawned, the status or ring buffer is too small, the graph contains a file-backed source, ``sink=True`` when the driver has no output open, or a C sink whose format is not the graph's. OSError: The thread could not be made, or a file ``sink`` could not be opened. """
[docs] def pull( sample: _AudioSample, blocks: int, status: bytearray | memoryview, sink: str | bool | bytes | None = None, ring: bytearray | memoryview | None = None, /, ) -> None: """Run the pump's loop on the calling thread until it ends. It is the same loop `spawn` runs, with the same arguments, so it can be measured on the interpreter thread. Wrap it in ``micropython.heap_lock()`` to check that a pull does not allocate. """
[docs] def sink_gain(level: float | None, /) -> None: """Set the level a C sink's audio goes out at, 0.0 to 1.0. It takes effect within a few milliseconds and steps to the new level, so move it in small steps to fade. It does nothing to audio going to the board's own output, a file or a ring. Args: level: 0.0 for silence to 1.0 for the graph's samples as they are. None is 1.0. """
[docs] def service(max_blocks: int = 0, /) -> int: """Advance the pump where there is no thread to do it. Args: max_blocks: The most blocks to produce. 0 means as many as the output ring has room for. Returns: ``blocks << SERVICE_SHIFT | why``, where ``why`` is one of `SERVICE_MORE`, `SERVICE_FULL`, `SERVICE_PARKED` and `SERVICE_DONE`. Unpack it with ``why = r & SERVICE_MASK`` and ``blocks = r >> SERVICE_SHIFT``. It is one small integer, so a call under ``micropython.heap_lock()`` does not allocate. On a threaded port it does nothing and returns `SERVICE_MORE` with no blocks. """
[docs] def drain(out: bytearray | memoryview, /) -> int: """Copy audio from the ring given to `spawn` into a buffer. Args: out: A writable buffer. Returns: How many bytes were copied. 0 when there is no ring or it is empty. """
[docs] def join(timeout_ms: int = 30000, /) -> bool: """Wait for the pump to end, and release its thread and sink. Returns: True when the pump had ended or was never running; False when it was still running at the deadline. In service mode it does not pull anything itself, so it reports False until `service` has finished the graph. """
[docs] def stop() -> None: """Ask the pump to stop after the block it is on. Follow with `join`."""
[docs] def shutdown() -> None: """Stop the pump, release the graph and close the sink. It is safe to call twice, and a soft reset does it for you."""
[docs] def running() -> bool: """Whether a pump is running."""
[docs] def park(timeout_us: int = 100000, *, fade: bool = False) -> bool: """Hold the pump at a block boundary so the graph can be rewired. The pump does not touch the graph again until `unpark`. Args: timeout_us: How long to wait for the pump to reach a boundary, in microseconds. fade: True makes the park a hold with a deadline: the block the pump holds goes out faded, and the pump feeds silence until `unpark`. Returns: True once the pump is parked, or has ended. """
[docs] def unpark() -> None: """Let a parked pump carry on."""
[docs] def retarget( sample: _AudioSample, *, loop: bool | None = None, fade: bool = False, timeout_us: int = 100000, ) -> bool | None: """Point the pump at a different tail while it runs. Everything that can raise happens first, on the calling thread; then the pump either sees the whole new tail or the whole old one. Args: sample: The new tail. loop: Whether the new tail loops. It takes effect with the swap, so it is right for the tail that plays. None leaves the flag as `spawn` set it. fade: True fades the old tail's next block to silence, swaps, and fades the new tail's first block in, a dip of one block each way, instead of a cut that clicks. timeout_us: With ``fade``, how long to wait for the swap. Returns: With ``fade``, True once the pump has stopped pulling the old tail so it can be released, or False if the swap will happen at the next block instead. Without ``fade``, None. Raises: ValueError: The graph contains a file-backed source, or the sample was deinitialised. """
[docs] def reset(sample: _AudioSample, /) -> None: """Rewind a graph, as the pump does when a looping tail ends."""
[docs] def info(sample: _AudioSample, /) -> tuple[int, int, int, int, bool, bool]: """Describe a graph's output, so a sink can be opened to match it. Returns: ``(sample_rate, channel_count, bits_per_sample, max_buffer_length, samples_signed, single_buffer)``. """
[docs] def now() -> int: """Frames the pump has pulled since `spawn`. This is what an event's frame is compared against, so schedule with it. It wraps at 2**32 frames, which is 24.9 hours at 48 kHz, and `Events.at` takes a wrapped value. """
[docs] def events(queue: Events | None = ..., /) -> Events | None: """Attach or detach the queue the pump applies at block boundaries. Args: queue: An `Events` to attach, or None to detach. Leave the argument out to only read. Returns: The attached queue, or None. Raises: TypeError: ``queue`` is not an `Events` or None. """
[docs] def tap(tap: Tap | None = ..., /) -> Tap | None: """Attach or detach the `Tap` that copies what goes out. Args: tap: A `Tap` to attach, or None to detach. Leave the argument out to only read. Returns: The attached tap, or None. Raises: TypeError: ``tap`` is not a `Tap` or None. """
[docs] def threaded() -> bool: """Whether `spawn` puts the loop on a thread of its own. False in service mode, where `service` is the driver."""
[docs] def backpressure() -> bool: """Whether a full output ring makes the pump wait for room instead of dropping the block. This is True on a threaded port whose driver can end the wait with a wake, and in service mode, where the loop hands the thread back on a full ring. It is False only on a threaded build whose driver has no way to wake the pump, where a free-running pump would lose audio. """
[docs] def driver() -> str: """Which platform driver bound: ``"esp32"``, ``"pthread"``, ``"win32"`` or ``"none"``. ``"none"`` is a real answer, not a failure: one thread, no hardware, and `service` is the driver."""
[docs] def fades() -> tuple[int, int, int]: """What fading has done since `spawn`. Returns: ``(fades, clean_holds, silence_bytes)``: blocks that went out faded, fading parks that ended in time and were never heard, and the bytes of silence a held park fed the output. """
[docs] def fault() -> int: """Why the last pull gave up: 0 when it has not. The pull never raises, because there is no interpreter on its thread, so it publishes a code and stops. `lock_reset` clears it."""
[docs] def lock_stats() -> tuple[int, int, int, int, int, int, int]: """What the pump lock has cost since `spawn`. Returns: ``(pump_takes, pump_wait_us, pump_wait_us_max, ctrl_takes, ctrl_wait_us, ctrl_wait_us_max, ctrl_held_us_max)``: how often and how long the pump thread and the control calls waited for the lock. """
[docs] def lock_reset() -> None: """Zero the lock statistics and clear the fault code."""
[docs] class Ring: """A ring buffer Python writes PCM into, which is an audio sample. The pump pulls blocks out of it through the same protocol as any other node, so a pushed stream can be the tail by itself or sit behind a mixer with effects on it. One producer writes and one consumer pulls, and neither takes a lock to do it. An underrun plays a whole block of silence and counts it, leaving the audio in the ring to refill. An overrun makes `write` take what fits and count it. Neither raises or blocks. The audio is signed 16-bit. Args: sample_rate: Frames per second. channel_count: 1 or 2. frames: Frames in one block, the amount the pump pulls at a time. capacity: How many blocks deep the ring is, at least 2. Depth is latency. Raises: ValueError: An argument is out of range, or the ring would be over 16 MB. """ def __init__( self, *, sample_rate: int = 48000, channel_count: int = 2, frames: int = 256, capacity: int = 4, ) -> None: ... sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2."""
[docs] def write(self, buffer: bytes | bytearray | memoryview, /) -> int: """Push PCM into the ring. Args: buffer: Signed 16-bit samples, interleaved. Returns: How many bytes were taken, in whole frames. It is less than the buffer's length when the ring is full, and the caller keeps the rest. """
[docs] def space(self) -> int: """How many bytes `write` will take now, in whole frames."""
[docs] def level(self) -> int: """How many bytes are queued."""
[docs] def stats(self) -> tuple[int, int, int, int, int, int, int, int, int, int]: """Counters. Returns: ``(wrote, read, starved, underruns, overruns, pulls, in_digest, out_digest, capacity, block_size)``. The 64-bit values are only reliable once the pump has stopped; `level` and `space` are the live questions. """
[docs] def clear(self) -> None: """Drop everything queued."""
[docs] def from_usb(self, endpoint: int, packet: int | None, /) -> None: """Make a USB sound card's isochronous OUT endpoint write straight into this ring from the USB interrupt, so the pump plays it. Only on ports whose ``machine.USBDevice`` streams isochronous endpoints. While it runs the interrupt is the ring's one producer, so do not also `write`. Args: endpoint: The endpoint number. packet: The packet size in bytes, or None to stop. """
[docs] def deinit(self) -> None: """Release the ring. Every later use raises `ValueError`."""
[docs] class DriftResampler: """Plays a `Ring` that something else fills on its own clock. It steers its resampling ratio so the ring holds `target` frames, which keeps the producer's clock and the output's clock from drifting apart. Play the resampler, not the ring: it is the ring's only reader. The ring's block must be 16 to 1024 frames. It is an audio sample, signed 16-bit, with the ring's channel count. Args: ring: The `Ring` to play. sample_rate: The output rate, from the ring's own rate (the default) up to twice it. target: The fill to hold, in frames. It must cover a block and fit in the ring less the filter's look-ahead of 16 frames. The default is half the ring. max_ppm: How far the ratio may move from nominal, in parts per million, 0 to 10000. bandwidth: How fast the loop follows the clocks once locked, in Hz, 0.001 to 0.1. It starts eight times faster and narrows over about a minute. The default is 0.01. Raises: TypeError: ``ring`` is not a `Ring`. ValueError: An argument is out of range. """ def __init__( self, ring: Ring, *, sample_rate: int | None = None, target: int | None = None, max_ppm: int = 1000, bandwidth: float | None = None, ) -> None: ... sample_rate: int """Frames per second of the output. Writable, to 1 or more.""" target: int """The fill to hold, in frames. It can be set while playing; the fill moves there at the loop's pace. Setting it out of range raises `ValueError`.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def ppm(self) -> float: """The ratio's offset from nominal, in parts per million.""" @property def fill(self) -> float: """The smoothed fill it is holding, in frames.""" @property def rate(self) -> float: """Ring frames consumed per output frame.""" @property def underruns(self) -> int: """Blocks of silence played because the ring ran dry, after which it waits for `target` again."""
[docs] def reset(self) -> None: """Start over and forget the rate."""
[docs] def deinit(self) -> None: """Release the resampler. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] class Events: """A queue of frame-stamped operations the pump applies at block boundaries, so a sequenced bar keeps time on the audio clock instead of the interpreter's. Scheduling is a call on the interpreter thread and does every type and range check there; applying is a handful of stores on the pump's thread. A scheduled `synthio.Note` or sample stays alive until it is applied. Attach the queue with `events`. Args: capacity: How many operations the queue holds, 1 to 4096. Raises: ValueError: ``capacity`` is out of range. """ def __init__(self, *, capacity: int = 64) -> None: ...
[docs] def at(self, frame: int, op: int, target: object, arg: object = None, loop: bool = False, /) -> int: """Schedule an operation. Args: frame: When to apply it, in frames since `spawn`, as `now` counts. It is masked to 32 bits, so ``now() + n`` is fine across the wrap. Do not schedule more than about 12 hours ahead. op: The operation, and what ``target`` and ``arg`` are for it: - `PRESS` and `RELEASE`: ``target`` is a `synthio.Synthesizer`, ``arg`` a `synthio.Note` or a MIDI note number from 0 to 127. - `RELEASE_ALL`: ``target`` is a `synthio.Synthesizer`. - `PLAY`: ``target`` is an `audiomixer.MixerVoice`, ``arg`` a sample whose format matches the mixer's. ``loop`` says whether it loops. - `STOP`: ``target`` is an `audiomixer.MixerVoice`. - `LEVEL`: ``target`` is an `audiomixer.MixerVoice`, ``arg`` the level. - `STRIKE`: ``target`` is an `audiomodal.Bank`, ``arg`` an ``array('f')`` of ``frequency, decay, gain`` for each mode. - `CHOKE`: ``target`` is an `audiomodal.Bank`. target: What the operation acts on. arg: The operation's argument. loop: Whether `PLAY` loops. Returns: A token for `cancel`, or 0 when the queue was full and the operation was dropped, which is counted rather than raised. Raises: TypeError: ``target`` or ``arg`` is the wrong type for ``op``. ValueError: ``op`` is unknown, a MIDI note is out of range, the voice is not in a mixer, or a strike's table is the wrong shape. """
[docs] def cancel(self, token: int, /) -> bool: """Remove a scheduled operation that has not been applied. Returns: Whether the token was still queued. """
[docs] def clear(self) -> int: """Remove everything queued, counting it as cancelled. Returns: How many operations were removed. """
[docs] def pending(self) -> int: """How many operations are queued."""
[docs] def stats(self) -> tuple[int, int, int, int, int, int, int, int]: """Counters. Returns: ``(scheduled, applied, late, cancelled, dropped, refused, depth, capacity)``: ``late`` operations were applied after their frame, ``dropped`` found the queue full and ``refused`` found their target gone when due. """
[docs] class Tap: """A copy of the audio going out, for a meter or a scope, without being in the path. The pump writes each block it sends into the tap's ring, and a reader takes the latest audio. Attach it with `tap`. The audio is signed 16-bit. Args: frames: How many frames to keep, at least 16. The size is rounded up to a power of two in bytes, to at most 4 MB. channel_count: 1 or 2. Raises: ValueError: An argument is out of range. """ def __init__(self, *, frames: int = 2048, channel_count: int = 2) -> None: ...
[docs] def readinto(self, buffer: bytearray | memoryview, /) -> int: """Copy the newest audio into a buffer. Args: buffer: A writable buffer. It is filled with whole frames, up to the tap's size. Returns: How many bytes were written. 0 when nothing has gone out since the last read, or when the pump kept overwriting the audio while it was copied, which `stats` counts. """
[docs] def stats(self) -> tuple[int, int, int, int, int, int]: """Counters. Returns: ``(bytes_written, blocks, reads, torn, capacity, frame_size)``. """