How audiodsp works
audiodsp brings CircuitPython’s audio-programming surface to MicroPython and
CPython. It supplies familiar top-level modules—audiocore, synthio,
audiomixer, audiofilters, and related effect modules—so an audio graph can
keep the same import names across those runtimes.
The repository is an audio core, not a complete sound application. It provides sources, processors, mixing, and the portable audio pump; a board or desktop integration provides the physical output device. Instruments and effects are separate libraries built on it: audioinstruments and audioeffects.
Start by choosing a runtime
On CPython the wheel gives you the modules as top-level imports, just as
they are on a board. On MicroPython, audiodsp is compiled into firmware
through manifest.py. Install
has the commands for each, and Your first program
renders a block of audio. A host can pull the graph for offline rendering,
give it to a mixer or pump, or attach it to a platform-specific audio output.
audiomp3 is in the wheel too, decoding with the same C as a board.
The mental model
Python graph
|-- source: RawSample, WaveFile, Synthesizer, MidiTrack, ...
|-- processors: filters, delays, dynamics, routing, ...
`-- mixer or audiopump
|
`-- platform driver / host pull loop / offline renderer
shared C DSP and sample protocol
|-- MicroPython user modules
|-- CPython _audiodsp extension and Python compatibility shims
`-- additive CircuitPython extension path
The audiosample pull protocol is the spine of the design: an upstream source
returns audio blocks when a downstream consumer asks. Nodes therefore compose
without Python copying every sample. audiopump owns the portable live-audio
loop mechanics; a particular port supplies its clock, threading, and sink.
For a new pump port, the pump-port guide is authoritative.
Repository map
Path |
Purpose |
|---|---|
Core CircuitPython-compatible source, synthesis, and mixing modules. |
|
|
Effects, DSP, routing, and audio utility modules compiled into native targets. |
Portable pump loop, rings, events, taps, and lifecycle guards. |
|
DSP and sample-protocol C shared by the MicroPython and CPython targets. |
|
Small CircuitPython compatibility shims needed by the MicroPython port. |
|
|
|
Cross-runtime |
|
Desktop-only, NumPy-based offline composition renderer. |
|
|
User-module build glue for Make and CMake MicroPython ports. |
|
CPython fixtures, in-repository parity gates, and parity tools that need sibling checkouts. |
|
Guides, reference, and these architecture pages. |
One graph, three target shapes
On MicroPython, micropython.mk or micropython.cmake compiles the module
sources into the firmware. On CPython, setup.py builds the same shared C
kernel into _audiodsp; the Python files in src/cpython/ present the
CircuitPython-compatible public API. This is why import synthio is portable
without importing a package named audiodsp first.
CircuitPython is an oracle and an extension target, not a working tree to
edit. audiodsp-owned modules build into CircuitPython as a user C module
(circuitpython.mk), but stock behavior is not changed there. Read
the correctness standard before any parity- or
CircuitPython-adjacent work.
audiorender deliberately stays outside firmware: it holds a full composition
in memory and requires NumPy. Install
shows its optional extra.
Important boundaries
The
mp3native dependency is a cloned, pinned dependency; it is not vendored source to edit here.audiodsp_util.float32()matters when Python computes a setting that must have board-equivalent single-precision behavior on a desktop. It is not a general-purpose numeric library.The project distinguishes CircuitPython-compatible modules from audiodsp’s own DSP additions such as dynamics, routing, convolution, ladder filtering, and modal synthesis. The latter have target-agreement and numeric-trait checks rather than an upstream oracle.
Testing and contributing
CONTRIBUTING.md
has the build, the tests CI runs and the rules that keep the port honest. For
a first tour of the implementation, follow one simple source through
audiocore’s sample interface, a synthio.Synthesizer, and audiomixer or
audiopump. That path explains the common contract behind the larger effect
catalogue better than reading the module directories alphabetically.
Names
audiodsp was named audioif earlier; that name now belongs to the audio
hardware layer. The modules you import did not change. The helper package is
audiodsp_util, and the distribution on PyPI is omnipython-audiodsp.
How it is checked
The committed synthesis, mixer, MIDI, streaming and effects fixtures match
CircuitPython’s PCM byte for byte, at the release on the circuitpython line
of DEPENDENCIES.lock and the voice ceiling this port ships.
The correctness standard says what each module is
held to. The pull protocol (audiocore.get_buffer and reset_buffer) is what
omnipython’s audiodev package plays from, so any audio sample here plays
through any of its outputs.
Pages in this section
Additions beyond CircuitPython: why each added module exists.
Where audiodsp differs from CircuitPython: each behaviour that differs, and what to do about it.
Sound stability: what is stable across releases, and what isn’t.
The correctness standard: how each module is held to a reference.
The graph runner: how
audiograph.Graphrenders a patch.The drift resampler: how
audiopump.DriftResamplerholds a Ring filled on another clock.Writing a pump port: how a platform plugs in a clock, a thread and a sink.
Wheels and platforms: what the release builds, and what it skips.