Run audio off the interpreter thread
audiopump runs the same pull a player runs, in C, on a thread the
interpreter is not on: a task pinned to the other core on esp32, a native
thread on unix and Windows, and the calling thread on a port that has no
threads at all. A graph pulled that way keeps an exact clock while a screen
redraws, a USB stack runs and Python does whatever it likes.
The thread and the output it writes to come from a platform driver, which
this repository doesn’t carry; the end of this section says where it comes
from. The example below is for a board whose driver has opened its output. On
a build without one, such as unix built from this repository alone,
sink=True raises ValueError: no i2s sink open, and the service() form
under Which builds carry it is the one to use.
import audiopump, audiomixer, synthio
synth = synthio.Synthesizer(sample_rate=48000, channel_count=2)
mixer = audiomixer.Mixer(voice_count=1, sample_rate=48000,
channel_count=2, buffer_size=2048)
mixer.voice[0].play(synth)
status = bytearray(audiopump.STATUS_BYTES)
audiopump.spawn(mixer, 0x7FFFFFFF, status, sink=True)
synth.press(60) # while it plays; no parking, no ceremony
mixer.voice[0].level = 0.6
audiopump.shutdown() # and a soft reset does this for you
spawn(sample, blocks, status, …) starts it; pull() runs the same loop on
the calling thread, so micropython.heap_lock() around it is a real gate on
“the pull does not allocate”; service() advances it where there is no
thread; retarget(sample, loop=…) points it at a different tail;
shutdown() stops it. status is a bytearray of counters — blocks, bytes,
a digest of everything pulled, the worst block, what the sink clocked, the
error and the fault — read back with struct.unpack. Everything that can
refuse happens on the calling thread. The pull itself never raises, because
there is no interpreter on that thread to raise on, so it publishes a fault
code and stops.
What status holds, which builds carry the pump, and what each source can be
are in the audiopump reference. To change what
plays while the pump runs, see
Change what plays without a click.
Render on several threads
The pump is one thread pulling one graph. On CPython you can also render on as many threads of your own as you like, as long as no node is used from two threads at once. Give each thread its own synthesizer, effects and mixer, and each renders exactly the bytes it would render alone, LFOs included: synthio’s block clock belongs to the render in progress on each thread, not to the process.
On a free-threaded build (3.15t has wheels), the native extension declares
that it doesn’t need the GIL, so those threads run in parallel and importing
audiodsp leaves the GIL off. Every call into a native node holds a lock on
that node, so reconfiguring a node while another thread renders it won’t
crash the interpreter. What comes out of that is still undefined, though,
because it breaks the rule above.
tests/test_cpython_free_threading.py
is the stress test that holds both, sixteen instruments on sixteen threads.