Change what plays without a click
Swapping one graph for another mid-waveform is a seam you can hear, and a
change that holds the pump for longer than its ring lets the speaker run dry,
which cuts the sound off and clicks again when it comes back. You can swap the
whole graph the pump plays, with a fade, or swap one part of it through an
audioroute.Port without touching the rest.
Swap the whole graph with a fade
Both audiopump calls that change what plays can fade instead:
rack = build_the_next_patch() # off the lock, as long as it takes
audiopump.retarget(rack.output, fade=True) # old fades out, new fades in
old_rack.deinit() # safe: True means it is let go
audiopump.park(fade=True) # hold the graph while you rewire it
rewire() # however long this takes, the speaker is fed
audiopump.unpark()
retarget(tail, fade=True) sends the current tail’s next block out faded to
silence, swaps, and fades the new tail’s first block in: one block each way,
5.3 ms at 256 frames and 48 kHz. A freshly built graph’s first block is often
its slowest, and with the fade that lands in the gap rather than in a cut. It
returns True once the pump has stopped pulling the old tail, so you can
release it; False if it stopped waiting (the pump is parked, asleep on a full
ring, or timeout_us, 100 ms by default, ran out). The swap still happens on
the next block, and the old tail is kept until then.
park(fade=True) is a park with a deadline. The pump pulls one block ahead
and keeps it. If you unpark() before the speaker’s queue is down to that
block, it goes out untouched and nothing is audible. If the queue gets there
first, the block goes out faded, the pump feeds the speaker silence for as
long as the park lasts, and the first block after unpark() fades in. It
needs a pump on a thread of its own and a ring, or a sink whose driver counts
what it clocked; where nothing can say how full the queue is, it fades at once.
fades() says what happened since spawn(): (fades, clean holds, silence bytes). The status block’s digest is still the graph’s own audio; only what
goes to the speaker, the ring and the tap is faded. Without fade=, both calls
behave exactly as before.
Swap one part of the graph through a port
audioroute.Port is a zero-copy pass-through you can re-point while it is
playing. Its get_buffer hands back its source’s own pointer, length and result; its
play(source) swaps that source atomically against a pull in flight. Hold a
port, wire it into a mixer voice or a rack, and change what is behind it as
often as you like — the object the consumer took never changes.
import audioroute
port = audioroute.Port(overdrive)
mixer.voice[0].play(port) # take it once
port.play(bitcrusher) # heard on the next block; nothing rewires
port.source # what it is playing right now
To switch once the old source has had time to finish something, such as a
level walking down over 20 ms, give after a number of frames. The port
keeps playing what it plays for that many more frames and switches at the
start of the next pull. Until then source is still the old one, and a
play() replaces the waiting switch. A port nothing has pulled since it was
pointed at what it plays now switches at once, since that hasn’t started.
Pointing it at the same source again doesn’t count as a new start.
mixer.voice[0].level = 0.0 # walks down over 960 frames
port.play(dry, after=960 + 256) # switches once the walk has landed
Port has no stop(), deliberately — a port always has a source. A port
pulled while it is already inside itself, which is what a component wrapping
its own output builds, publishes a loop fault and hands back an error
instead of recursing until the stack is gone.
Why it exists, and what its pull costs: Additions beyond CircuitPython.