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

src/audiocore/, src/synthio/, src/audiomixer/

Core CircuitPython-compatible source, synthesis, and mixing modules.

src/audio*/

Effects, DSP, routing, and audio utility modules compiled into native targets.

src/audiopump/

Portable pump loop, rings, events, taps, and lifecycle guards.

src/shared/

DSP and sample-protocol C shared by the MicroPython and CPython targets.

src/cp_compat/

Small CircuitPython compatibility shims needed by the MicroPython port.

src/cpython/

_audiodsp extension plus top-level Python wrappers for CPython.

lib/audiodsp_util/

Cross-runtime float32() helpers for settings derived in Python.

lib/audiorender/

Desktop-only, NumPy-based offline composition renderer.

micropython.mk, micropython.cmake

User-module build glue for Make and CMake MicroPython ports.

tests/

CPython fixtures, in-repository parity gates, and parity tools that need sibling checkouts.

docs/

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 mp3 native 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