Chain effects
Every effect takes a source and has an output, so one effect’s output is
the next one’s source. This chain compresses a synthesizer, puts a tape
delay behind it and a hall reverb behind that:
import audioeffects
import synthio
RATE = 48000
synth = synthio.Synthesizer(sample_rate=RATE)
comp = audioeffects.create("Compressor", synth, RATE,
threshold_db=-20, ratio=3, character="optical")
tape = audioeffects.create("TapeDelay", comp.output, RATE,
time_ms=340, feedback=0.4, mix=0.25)
hall = audioeffects.create("Reverb", tape.output, RATE,
character="hall", mix=0.3)
audio_out.play(hall.output) # or pull hall.output yourself
Keyword arguments after the sample rate are the effect’s construction options. Each class’s module docstring lists its controls and limits, and the effects reference groups the classes by what they do.
Ask the end of the chain how much it adds: hall.latency_samples is how late
the output arrives behind the input, and hall.tail_samples is how long the
sound goes on after the input stops (None means no bound).
As a rack
A rack is one component with the shape of a single effect, however many
effects sit inside it. Rack takes a chain of effect names, or
(name, options) pairs, in the order the signal passes through them:
rack = audioeffects.create("Rack", synth, RATE, chain=(
("Compressor", {"threshold_db": -20, "ratio": 3}),
("TapeDelay", {"time_ms": 340, "mix": 0.25}),
("Reverb", {"character": "hall", "mix": 0.3}),
))
The chain is plain data, so a host can store a rack as a literal. Racks nest:
an entry may itself be ("Rack", {"chain": (...)}). A rack owns its children
and borrows the source. Its latency is the children’s summed, its tail is
None as soon as any child’s is unbounded, and reset() clears every child’s
history. ShimmerHall and AirSpace are fixed racks whose macros move their
children’s controls.
After an effect that ends in a mixer
Several effects end in an audiomixer.Mixer, because they split into parallel
branches and sum them. On MicroPython and on a desktop you can chain freely
after one. On stock CircuitPython you cannot: its Mixer stops its voices when
it is reset, and every effect resets its source when you play() it, so the
chain goes silent. audiodsp’s builds fix that. The
effects reference has the details under “A note on
chaining after a Mixer”.