How it works
audioeffects is a pure-Python library of 45 audio effects, including ready-made racks. It runs on CPython, MicroPython and CircuitPython by building on audiodsp’s audio nodes. If you have not run one yet, start with Install and Your first program.
The mental model
your program
`-- audioeffects.create(name, source, sample_rate)
`-- public effect class -> effect graph -> stable effect.output
|
`-- mixer or audio sink
Every effect shares a live-component vocabulary: macros, patches, MIDI-style
control methods, state reset, deinit(), format properties and the output
property, and it transforms an upstream source. The source can be anything an
audio sink can pull: a synthesizer, a sample, a host input, another effect, or
an instrument from audioinstruments.
The complete contract, including latency, tail and real-time rules, is in
the runtime API.
Your host chooses the final sink: on a board that may be audio_out.play(),
while a desktop host or audio pump can pull the graph itself. Keep the
component’s output rather than reaching into its internal nodes. An effect
may rebuild its implementation after a parameter change, but its output wire
stays the same for the component’s lifetime
(why).
How the factory works
audioeffects.ALL is derived from the package’s exported provider classes.
audioeffects.create() finds the class whose stable NAME matches the
requested effect. Its factory checks that the source exposes a matching sample
rate and channel count, constructs the graph, applies an optional patch, and
returns the live component. Prefer this package factory when a host discovers
components by name; constructing a class directly remains useful in local code
after audioeffects.configure() records a default format.
This separation is deliberate: consumers deal in stable names and the common contract, while the library can change an effect’s internal graph or module organization without changing a host integration.
Metadata, macros and patches
Providers declare their public shape as module or class data:
MACRO_LABELSandMACRO_MODESdescribe up to 16 controls.PATCHESmaps contiguous program numbers to named, MIDI-scale settings.
tools/validate_metadata.py checks those declarations; the runtime API and
tools/validate_api.py check that a constructed provider implements the live
surface. If a host needs finer automation, macro values may be floats even
though patch values are the 0-127 MIDI grid. The declarations are specified in
the metadata manifest.
Pages in this section
Sound stability, in audiodsp’s documentation: what stays the same between releases