Install
Pick the channel that matches where your code runs: a desktop with CPython, a MicroPython build, or a CircuitPython build. Once it’s installed, your first program renders a block of audio.
CPython 3.11 or later
CPython 3.11+ installs from PyPI:
The distribution on PyPI is `omnipython-audiodsp`.
This gets you audiocore, synthio, audiomixer, audiofilters,
audiodelays, audiofreeverb, audiospeed, audiodynamics, audioroute,
audiomath, audioecho, audioshaper, audioladder, audiooscillator,
audioconvolve, audiobiquad, audioverb, audiomodal, audiosampler, audiometer,
audiofeatures, audiopump, audiovorbis, audiomp3, audiograph, and the audiorender package.
audiomp3 decodes with the Helix C decoder a board’s firmware compiles, so a
file decodes to the same bytes here as on a board. The distribution declares no required
runtime dependencies and does not itself publish an audiodsp import; its
version is the VERSION file, which is also what _audiodsp.__version__
reports.
audiorender is the exception, and it is opt-in: it is numpy throughout,
so numpy comes with the render extra rather than with the wheel, keeping
the core dependency-free for boards and wasm:
python -m pip install "omnipython-audiodsp[render]"
The instrument and effect libraries, audioinstruments and audioeffects,
are not part of this distribution. They live in the
audiocomponents repository
as their own packages, each depending on omnipython-audiodsp; see that
repository for how to install them.
To render on several threads, see Render on several threads.
MicroPython 1.29 or later
MicroPython 1.29 or later takes this repository with one line in the manifest your build already uses. Clone it anywhere, fetch its two pinned native dependencies, and include its manifest.py:
git clone https://github.com/PyDevices/audiodsp ~/build/audiodsp
~/build/audiodsp/scripts/fetch_deps.sh
include("/home/you/build/audiodsp/manifest.py")
On unix the manifest to edit is ports/unix/variants/standard/manifest.py; on
esp32 and rp2 it is usually ports/<port>/boards/manifest.py, unless your
board brings its own. Then build the way you always do. The include brings in
the audiodsp C modules (named with c_module()); it freezes no Python and
brings no ulab, which audiodsp doesn’t use: a build that wants ulab names
it itself. fetch_deps.sh puts the mp3 decoder under .deps/, pinned by
DEPENDENCIES.lock; the mp3 glue looks there first and
falls back to a sibling checkout beside this repo. On a unix build, synthio, audiomp3
and audiopump all import.
If you would rather not edit the MicroPython tree, write a manifest of your
own and pass it as FROZEN_MANIFEST=. That replaces the port’s default, so
include the default too (include("$(PORT_DIR)/variants/standard/manifest.py")
on unix, include("$(PORT_DIR)/boards/manifest.py") on esp32) or you lose
asyncio and the port’s other frozen modules.
To build without mp3, skip the fetch and set AUDIODSP_OPTIONAL_DEPS=1 on
the build step — micropython.mk/micropython.cmake read it, not
fetch_deps.sh, and on CMake ports it is an environment variable, not a
-D cache entry.
Older than 1.29? Manifests there have no c_module(), so do not include
this one; use USER_C_MODULES. On esp32 and rp2 point it at this checkout;
on a Make port point it at the directory that contains the checkout, which
builds every module in that directory.
MicroPython’s
manifest reference
explains include() and c_module(), and
omnipython-builds
keeps ready-made manifests and boards for several PyDevices modules at once.
CircuitPython 11
Every module that is audiodsp’s own builds into CircuitPython 11 as a user C
module from this repository’s micropython.mk:
make BOARD=... USER_C_MODULES=/path/to/audiodsp
Run that in a CircuitPython port. Your sounds play through CircuitPython’s
own audiobusio, audioio and audiopwmio; audiocore, synthio,
audiomixer and the effects modules stay CircuitPython’s. Two modules differ
there: audiopump carries only Ring (see
Play computed audio), and audiometer
and audiofeatures aren’t built, because their sources are a board’s pump and
a USB sound card, and CircuitPython has neither.