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:
objectPull-based sample player over a push transport.
transportis any PCMOutput-shaped device (format,open,close,write,service, and the volume/mute/codec surface) – typically what a board’saudio_outrole used to return directly, e.g.sdl2_audio.audio_out()or anI2SPCMOutput.- 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.
- audiodev.sample_out.sample_out(transport_factory, format=None, **kwargs)[source]
Wrap a backend’s
pcm_out(format, **kwargs)transport inAudioOut.transport_factoryis a module (or any object) exposingpcm_out, e.g.audiodev.sdl2_audio– sosample_out(sdl2_audio)is the sdl2 equivalent of CircuitPython’saudiobusio.I2SOut(...).