audiodev.sample_out

CircuitPython-shaped sample playback, off the interpreter thread where it can.

This is the public audio_out contract (see docs/guides/audio.md): a board’s audio_out role returns an AudioOut wrapping a backend transport (sdl2/win/wasm/i2s/emulated), and app code plays anything satisfying CircuitPython’s audiosample pull protocol – a synthio.Synthesizer, an audiomixer.Mixer, an audiocore.RawSample/WaveFile, or any effect chained on top of one – with the same play()/stop()/pause()/ resume()/playing shape CircuitPython’s own AudioOut/I2SOut use, unchanged. Nothing below changes a line of that.

Where the pull happens is not part of that contract, and it has moved. When the firmware carries audiopump this class hands the graph to the pump – a C thread the interpreter is not on, a pinned FreeRTOS task on esp32 – and does no pulling at all; the interpreter is left shovelling bytes on the desktop and doing nothing whatsoever on a board, where the pump writes each block straight into I2S. No app asks for it and no board configures it: the firmware either has the module or it has not. Where it has not – stock MicroPython, CircuitPython, CPython – every word of the paragraph below is still true and every byte is the same, because the old path is what runs.

The old path, and what it costs: every real output backend at the bottom is a push+queued transport, and audio-thread callbacks into Python are unsafe (documented in sdl2_audio.py). This class then pulls PCM from a sample via audiocore.get_buffer/reset_buffer on a lookahead schedule and pushes it into the wrapped transport’s write(), all on the interpreter thread. That used to be argued here as “the only sound architecture”, on the grounds that pulling a synthio graph allocates on the GC heap and so cannot be done from a C callback. The premise was wrong: the pull is allocation-free under a cold micropython.heap_lock() across 313 targets, byte-exact off the interpreter thread, and safe under audiodsp’s pump lock with no park. What made the old path necessary was never the DSP – it was that nobody had written the thread.

Requires audiocore when AudioOut is constructed. Importing audiodev and using a raw PCM transport remain independent of audiodsp.

No resampling: transport.format is the fixed playback rate/bit-depth/ channel-count (whatever the backend/device was opened with). A sample whose own sample_rate differs plays at the wrong pitch rather than raising – exactly like real DAC hardware and exactly like CircuitPython’s own AudioOut/I2SOut, which never resample either. bits_per_sample and channel_count do have to match: unlike a hardware clock mismatch, a software queue interprets the raw bytes it’s given, so a format mismatch there would misread every sample rather than merely mis-pitch it.

class audiodev.sample_out.AudioOut(transport, *, chunk_ms=40, lookahead_chunks=2, max_catchup_chunks=5, pump=True)[source]

Bases: object

Pull-based sample player over a push transport.

transport is any PCMOutput-shaped device (format, open, close, write, service, and the volume/mute/codec surface) – typically what a board’s audio_out role used to return directly, e.g. sdl2_audio.audio_out() or an I2SPCMOutput.

stalls

How many times the pump started feeding past the cap because the transport had stopped consuming – episodes, not ticks. A number above 0 means the sink was not draining: a wrapper that does not forward prebuffer_bytes (omnipython#54), or a device that died.

property pumped

True while this player’s audio is being pulled by the pump.

property pump_refused

Why the pump would not take this graph, or None.

A console line is not enough. An app that keeps time off the audio clock when the pump takes it, and off a timer when it does not, is a DIFFERENT app either way – and on a board the only thing that says which is one print nobody is watching. This is what a UI shows.

play(sample, *, loop=False)[source]

Start playing sample. Replaces whatever was already playing.

service()[source]

Call from the app tick. Required for continuous playback – no different from the service() every other audiodev backend already requires; see docs/guides/audio.md.

attach(app, period_ms=None)[source]

Subscribe service to app’s shared timer; returns self.

audiodev.sample_out.sample_out(transport_factory, format=None, **kwargs)[source]

Wrap a backend’s pcm_out(format, **kwargs) transport in AudioOut.

transport_factory is a module (or any object) exposing pcm_out, e.g. audiodev.sdl2_audio – so sample_out(sdl2_audio) is the sdl2 equivalent of CircuitPython’s audiobusio.I2SOut(...).