audioeffects
Forty-five effects for any host that can pull an audiosample: compressors and EQs, reverbs and delays, modulation, drive and amp simulation, pitch shifters, and three ready-made racks. Pick one by name, hand it your audio, and play what comes out.
import audioeffects
comp = audioeffects.create("Compressor", source, 48000,
threshold_db=-20, ratio=3, character="optical")
tape = audioeffects.create("TapeDelay", comp.output, 48000,
time_ms=340, feedback=0.4, mix=0.25)
hall = audioeffects.create("Reverb", tape.output, 48000,
character="hall", mix=0.3)
audio_out.play(hall.output)
audioeffects.ALL lists every name create() accepts. create() takes the
audio source and the sample rate explicitly; a source can be a synthesizer,
an audioinstruments instrument’s output, a host input, or another
effect’s .output. Every effect hands back its chain tail as .output, keeps
its underlying nodes as attributes (.node, .mixer, .cutoff, …) so you
can bind parameters straight to them, and follows the common component
surface in docs/reference/component-api.md: set_macro(), program_change(),
latency_samples, tail_samples and the rest. Every class declares NAME,
MACRO_LABELS, MACRO_MODES and PATCHES; the provider rules are in
docs/reference/metadata.md. Constructing a class directly also works, and
reads the format off the source it is handed.
Nearly everything here needs the audiodsp tier of nodes
(audiodynamics, audiobiquad, audioecho, audioverb, audioconvolve,
audiomath, audioshaper, audioladder and friends), which a stock
CircuitPython board does not have.
For a complete program to start from, see audioeffects_simpletest.py.
What is in it
Each class below is a name you give to audioeffects.create(). The module
docstring of any of them lists its controls and limits.
Dynamics
Compressorevens out loud and quiet with four characters: a fast FET, a slow optical, a VCA and a vari-mu.Limiterstops the signal at a ceiling, with optional lookahead and true-peak detection.Expandermakes quiet passages quieter by a ratio, down to a floor you set.NoiseGateshuts the signal off when it falls under a threshold, with hold and a key filter.DeEsserturns down sibilance without dulling the rest of a voice.TransientShapergives you more attack or more sustain from one pair of knobs, with no threshold.MultibandCompressorcompresses two or three bands on their own and sums them back flat.
EQ and filters
ParametricEQis a shelving and bell EQ with three bells and a Q law you choose.GraphicEQis a ten-band octave graphic equalizer.LowPasscuts the highs above a corner, with resonance and a 12 or 24 dB/oct slope.HighPasscuts the lows below a corner, with the same resonance and slope choices.BandPasskeeps one band and drops the rest.Notchremoves one band, or a hum and its harmonics.LadderFilteris a four-pole Moog-style low-pass that can sing at high resonance.CombFilteris a tuned feedback comb that puts a pitch on whatever goes through it.DynamicEQis a bell that only appears when its band gets loud.
Reverb
Reverbis a plate, room, chamber or hall, built from a fixed network of delay lines.ConvolutionReverbputs your signal in a synthesized room, or in the room your own impulse was recorded in.
Delay
DigitalDelayis a clean delay whose Time knob bends the repeats instead of clicking.SlapbackDelayis the single short tape repeat behind a vintage rockabilly voice.TapeDelayis a tape echo with a motor or a sliding head, wow and flutter.AnalogDelayis a bucket-brigade echo whose repeats darken as Time grows.PingPongDelaybounces the repeats between the two speakers.MultiTapDelayreads one recording with several heads for rhythmic patterns.
Modulation
Chorusthickens a part with one analog-style swept voice.Flangersweeps a comb of notches through the sound.Phasersweeps an all-pass cascade for a softer, swirling version of the same idea.Tremolopulses the level, in bias-vary or optical style. Default is bias, Depth 0.5, Rate 5 Hz — not the optical standout and not L1’s Depth 1. Wet peak at the default is −1.341 dB vs a 16000-LSB tone, not the ~6 dBsynthio>>16ceiling; Depth 0 is still a wire. At 22.05 kHz the default’s L1 bar is measured at the constructor, not assumed. Optical L1/L2 are disconfirmed; O1–O4 unmeasured at the constructor. L1 holds on sine at every rate, and misses by 0.16 dB on SQUARE material at 44.1 kHz only (−79.844 against −80; 48 kHz holds at −82.01).AutoPanmoves the sound left and right on an LFO.Vibratowobbles the pitch.RingModmultiplies your signal by a carrier for bell-like and metallic tones.
Drive
Overdriveis a diode-limited, Tube Screamer style push.Distortionis hard clipping after a shaped gain stage.Fuzzis a germanium fuzz box, or a cascaded Big Muff style one.Saturationis the warmth of a tube stage, a tape machine or transformer iron.Bitcrusherlowers the word length and the sample rate for a lo-fi crunch.Exciteradds high harmonics to the top of the sound.CabinetSimruns the signal through a designed 4x12 or 1x12 cabinet.
Pitch and stereo
PitchShifterplays your part again a fixed interval up or down.Harmonizerblends up to three fixed intervals under the dry for instant harmony.Octaveradds an octave or two below the note you play.StereoWidenerwidens a stereo part with a Haas delay or Mid/Side scaling.
Racks
Rackchains the other effects in the order you name, and hands back a single effect.ShimmerHallis a pitch-shifted bloom around a long hall.AirSpaceis a swept filter into a wobbling tape echo into a chamber.
Chaining effects with 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", source, 48000, chain=(
("Compressor", {"threshold_db": -24.0, "ratio": 3.0}),
("TapeDelay", {"time_ms": 340.0, "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. It reports its whole graph’s latency (the children
summed) and tail (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.
Latency
latency_samples is how late the output arrives behind the input. The table
gives it in milliseconds at 48 kHz, read from each class’s own report, at the
default patch, at the worst of its shipped patches, and at the widest setting
any one macro can reach. Zero means the effect adds no delay to the dry path.
A delay’s repeats, a reverb’s tail and a compressor’s release are not
latency; tail_samples reports those.
Class |
Default patch |
Worst shipped patch |
Widest setting of any knob |
|---|---|---|---|
|
0 |
0 |
0 |
|
0 |
2.98 |
10 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
5.33 |
5.33 |
5.33 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
4 |
10 |
12 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0.04 |
0.04 |
0.04 |
|
0.08 |
0.08 |
0.08 |
|
0.02 |
0.02 |
0.02 |
|
0.02 |
0.17 |
0.98 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
|
0 |
0 |
0 |
Racks report the sum of their children. A Rack built from the five-effect
chain NoiseGate, Compressor, Overdrive, Chorus, Reverb (the usual
order on a guitar or a voice: clean up, level, colour, move, place) reports
0 ms at defaults, and 0 ms with each effect on its worst shipped
patch. Latency adds up along a chain, so the effects to watch are the few
with a number: ConvolutionReverb (5.33 ms while an impulse is loaded),
Limiter (up to 10 ms of lookahead, 2.98 ms on its true-peak patch),
Vibrato (its mean delay, 4 ms by default), and the drive effects that
oversample, which add a few samples.
Two things the figure does not say. PitchShifter, Harmonizer and
Octaver leave the dry untouched, so they report zero, yet the shifted
voice they add trails the dry by the shifter’s window. StereoWidener’s Haas
delay puts the right channel behind the left on purpose, and that is not
counted either.
Sound stability
The API is our contract with you: class names, signatures, metadata, and macro surfaces stay stable and change only deliberately. The sound is not part of that contract. These components sound great, but they are not all as accurate as they could be, and implementations will keep being refined as the library matures — so a component may render audibly differently from one release to the next. If a composition depends on the exact sound of a release, pin that release rather than tracking the latest; the code of every release stays available for exactly this reason.
Beneath the components sits a harder guarantee: the audiodsp core — the
CircuitPython-compatible synthio/audiocore/effects-module layer — is
held bit-exact to CircuitPython itself, verified by parity gates, and
that never changes release to release. Where we find CircuitPython and
audiodsp disagree, we treat it as a bug and report it upstream. The
components are where the sound evolves; the floor they stand on does
not.
Deliberately absent
Pitch correction - needs pitch detection (YIN or autocorrelation), and that is off the roadmap for good rather than pending.
PitchShifterwill shift by an interval you name; nothing here works out what interval to ask for.Sample-rate reduction as a stock Distortion mode - CircuitPython’s LOFI masks low bits and nothing else.
Bitcrusherholds both word length and hold rate onaudioshaper, and it is what the package serves.LFO-driven parameters update at the block rate (~187 Hz at 48 kHz), plenty for sweep rates but not audio-rate modulation.
RingModis the exception and does not use an LFO at all - see below.
A note on how low a filter can go
Anywhere in the band on audiobiquad, which is what the filters and
EQs here are built on. On synthio.Biquad - and so audiofilters.Filter and
a Note.filter chain - the low end is CircuitPython’s, on every target, and
it is worth knowing why.
CircuitPython keeps a biquad’s coefficients as Q15 integers, which is the
right trade on a microcontroller and costs low frequencies. Below about
300 Hz they quantize into something that is no longer the filter you asked
for: a LowPass at 100 Hz returned silence, a HighPass at 30 Hz
returned +21 dB of noise, and a low shelf at 80 Hz lifted the whole band
by 13.4 dB instead of its 1.5. A low-pass fed a DC burst can also park at a
fixed point for ever - half of full scale from a 40 Hz low-pass.
audiodsp widened that arithmetic once for every biquad. Since audiodsp#77 the
split is by ownership: synthio.Biquad is a node CircuitPython also has, so
it runs CircuitPython’s arithmetic everywhere (at the current floor that
80 Hz shelf reads -7.65 dB), and the widened kernel belongs to
audiobiquad, which is audiodsp’s own. There, coefficients get as many
fractional bits as each filter has room for, the recursion accumulates in
64 bits and keeps its feedback below the sample grid, and the trigonometry
is a proper series. Measured against the closed-form response, every mode
lands within 0.03 dB from 50 Hz to 22 kHz. Ten octave bands all read
+6.01 dB or better on a +6 dB request, read on ParametricEQ. The
MultibandCompressor sums to 0.12 dB from 30 Hz to 20 kHz on
audiobiquad’s float sections. Saturation builds its shelves there too,
and falls back to synthio.Biquad only where audiobiquad is missing.
audiodsp’s docs/upstream-diff.md,
“The biquads were Q15, so they could not go low”, has the arithmetic.
Nothing refuses a low frequency and nothing ever did, because a
LadderFilter sweeping down through 40 Hz is a legitimate thing to do.
The only remaining rule is the one that was always real: stay below
Nyquist, which check_hz enforces.
A note on patches
Some classes carry patches: named settings on the same 0-127 MIDI grid
audioinstruments uses, so a host or an app can offer presets and automate
knobs without knowing what any particular effect’s arguments mean.
mod = audioeffects.RingMod(source, patch=1) # "Textbook AM"
mod.set_macro(0, 96) # Frequency, MIDI scale
name, values = audioeffects.RingMod.PATCHES[2]
A class declares MACRO_LABELS (the knob names), MACRO_MODES (the public
control behavior), and PATCHES ({index: (name, (values,))}). Private
engineering mappings may remain in _MACRO_RANGES; consumers never inspect
them. set_macro(index, value) takes the MIDI
scale and accepts floats, so a host with finer resolution need not quantize;
macro(index) reads a knob back in its own units; program_change(index)
applies a patch and ignores an index the class does not have, the way an
instrument does.
Patch 0 is always the constructor’s own defaults, rendered onto the 7-bit
grid - close to a fresh instance, not identical to one, because 128 steps
cannot land exactly on every default. Constructor arguments are not
quantized: RingMod(src, frequency=440) gets 440 Hz, while patch 0’s nearest
grid point for the 220 Hz default is 215.7.
An effect rack is one audio component whose internal graph chains or mixes
multiple effect nodes; rack.py above is where this package ships them,
declaring the same required metadata at class scope like any other effect
class. See docs/dev/component-contract.md for the complete rack rule.
A note on chaining after a Mixer
Several classes here end in an audiomixer.Mixer - anything that splits
into parallel branches and sums them. On MicroPython and CPython you can
chain freely after one. On 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 fixes that for its own
builds; see audiodsp’s docs/upstream-diff.md, “Resetting a Mixer silenced it”.
A note on filters off a stock CircuitPython board
Every frequency in this library is the frequency you get - on audiodsp. On stock CircuitPython two engine bugs are still in the way, and they change what these classes sound like rather than breaking them, so they are worth knowing about:
A stereo
audiofilters.Filterruns one biquad state across the interleaved stream, so the recursion advances twice per frame and every filter sits an octave above where it was asked to sit - and the feedback path leaks each channel into the other. Fixed upstream after 10.2.1, so a current CircuitPython is fine; 10.2.1 itself is not.PEAKING_EQcomputesb2with the wrong sign, which costs the filter its unity-outside-the-band property: a +6 dB bell at 1 kHz / Q 1 is about +21 dB at DC, worse the lower the center. Still present upstream. It no longer reaches the catalogue’s bells:ParametricEQ,GraphicEQandDynamicEQare all built onaudiobiquad, which computes the sign correctly in its own float kernel and never went through this.Biquad coefficients are Q15 and the recursion accumulates in 32 bits, so nothing below roughly 300 Hz is the filter it was asked to be, and one polynomial covers sine and cosine only as far as π/2 - 12 kHz at 48 kHz - so nothing near Nyquist is either. Both ends fail quietly. Still present upstream, and the section above is what a filter does here instead.
This library used to compensate for both - halving every frequency on the
way in, and synthesizing bells out of notch and band-pass sections. It no
longer does, because the engine is right. See audiodsp’s docs/upstream-diff.md for
the measurements and the one-line coefficient fix.
Testing
tests/test_cpython_effects_library.py holds every class in
audioeffects.ALL to the contract - exports and metadata, the factory,
building and rendering, chaining, the patch surface - under CPython. What
each class sounds like is measured beside it, one module per family:
test_cpython_effects_dynamics_eq.py and ..._modulation.py, plus one
module per class that has its own, with
test_cpython_convolve_node.py for the audioconvolve node underneath the
convolvers. tests/parity/effects_library_smoke.py is the coarse half of
all that in portable Python, so MicroPython and patched CircuitPython can
walk the same catalogue - every class through create(), and every patch it
declares through program_change(). micropython-vst3’s tools/test-effects-lib.py
additionally runs them inside a real VST3 host, feeding a quiet-then-loud sine and asserting
per-class behaviour: compressors and limiters squeeze the loud half,
gates and expanders mute the quiet one, everything else passes signal.