Overview
The whole tour: what is in the rack, how a patch is rendered, and where each part is documented. The README has the short version.
Every instrument in audioinstruments is a patch on audioinstruments._rack, a virtual Eurorack
modular synthesizer in Python. Twenty modules
inspired by classic instruments, with their panels, patch cables between them,
and a rack that renders a block at a time on
audiodsp. It runs on CPython and on
MicroPython builds that carry audiodsp and ulab. On a build with
audiograph, a rack whose modules declare graph fragments compiles to one C
graph and renders as one call a block, which is what plays in real time on
an ESP32-P4. Every instrument built on the rack does this; only the
SoundFont players, which are not racks, do not
(docs/how-it-works/architecture.md).
from audioinstruments._rack import MidiCVModule, Modular100VCO, Modular100VCF, Modular100VCA, Modular100EnvLFO, Rack
rack = Rack(sample_rate=48000, block_size=64)
midi = rack.add_module(MidiCVModule("midi"))
vco = rack.add_module(Modular100VCO("vco"))
vcf = rack.add_module(Modular100VCF("vcf"))
vca = rack.add_module(Modular100VCA("vca"))
env = rack.add_module(Modular100EnvLFO("env"))
rack.connect(midi.pitch_out, vco.vco1_pitch_in)
rack.connect(midi.gate_out, env.env1_gate_in)
rack.connect(vco.vco1_saw_out, vcf.vcf1_audio1)
rack.connect(env.env1_out, vcf.vcf1_mod2)
rack.connect(vcf.vcf1_out, vca.vca1_audio1)
rack.connect(env.env2_out, vca.vca1_mod1)
rack.connect(vca.vca1_out, rack.master_left_in)
vcf.set_param("vcf1_cutoff", 0.45)
vcf.set_param("vcf1_res", 0.65)
midi.note_on(60, 100)
for _ in range(100):
rack.step() # rack.output_buffer_left holds 64 floats; ±0.5 is ±5 V
Playing chords, and the instruments
VoicePool copies a voice patch once per note and sums the copies into a
section that exists once, and audioinstruments._rack.adapter wraps the pool
as an audio component (Polyphony). Every instrument
in the reference is such a pool with its
presets. A SoundFont bank you supply plays through audiosampler instead, with
no rack (Play a SoundFont), and
audioinstruments.panel wraps any of them for a control panel
(Panel).
Loading only what you use
import audioinstruments._rack loads the rack and its core and nothing else. A synth is
imported the first time you name it, whether as from audioinstruments._rack import PinMatrix3,
from audioinstruments._rack.modules.pin_matrix3 import PinMatrix3 or audioinstruments._rack.modules.PinMatrix3, and
load_rack() imports only the modules a patch contains. On a board that keeps
the others out of RAM. dir(audioinstruments._rack) lists every name on CPython; on
MicroPython it lists the ones loaded so far, and audioinstruments._rack.__all__ always has
them all. audioinstruments._rack.modules.MODULE_TYPES is the one thing that loads every synth.
What is in the rack
Each module’s name echoes the instrument that inspired it, and the module gives you that instrument’s panel.
Module |
Inspired by |
|---|---|
|
ARP 2600 (and Behringer’s 2600): semi-modular, normalled |
|
Behringer Neutron: paraphonic, wave-blending VCOs, BBD delay |
|
Oberheim SEM: two VCOs, the LP-notch-HP morphing filter |
|
Korg MS-20: the high-pass and low-pass Sallen-Key pair |
|
Buchla Music Easel: complex oscillator, low-pass gates |
|
EMS VCS3: the 16 x 16 pin matrix |
|
Sequential Pro-One: sync and poly-mod |
|
EDP Wasp: the CMOS filter |
|
Moog Mother-32, with its sequencer |
|
Moog DFAM: sequenced percussion |
|
Moog Subharmonicon: subharmonics and polyrhythms |
|
Roland TB-303, with its sequencer |
|
Make Noise 0-Coast |
|
Make Noise Maths: function generators and logic |
|
Mutable Instruments Plaits: a macro oscillator |
|
Mutable Instruments Rings: modal and string resonators |
|
Mutable Instruments Clouds: granular texture |
|
Music Thing Modular Turing Machine: a looping random sequencer |
|
Roland Juno-106: one voice, the shared LFO, the HPF and chorus |
|
Roland System-100M modules 112, 121, 130, 140 and 150 |
|
Moog System 55 modules 921, 904A, 904B, 911 and 902 |
And MidiCVModule, a MIDI-to-CV module with pitch, gate, velocity, wheels,
transport, pressure, expression and foot pedals, 24 knobs and 24 pads as jacks. PolyMidiCV adds a pitch,
gate, velocity and pressure jack for every voice of a polyphonic patch, and
VoiceMix sums the voices.
You get the same oscillators, knobs, switches and ranges. A module does not
aim at its original’s sound, and nothing in the repository compares against
one. The panels are described in each module’s docstring; module.params lists the
controls, module.inputs and module.outputs the jacks.
How it works
Every jack carries a block of floats on one scale, so audio, CV, gates and clocks patch anywhere: 1.0 is +10 V, Eurorack-level audio and bipolar CV are ±0.5, gates are 0 or 1, pitch is 1 V per octave at 0.1 per octave. An input with nothing plugged in reads its panel normal. The rack orders modules by their cables; a cable that closes a feedback loop carries its source’s previous block. docs/how-it-works/patching.md has the details and what the one-block delay does to self-FM and filter feedback.
Linear filters, delays, reverbs, overdrive, the modal and string resonators, MacroOscillator’s chord models, the VCO and the four ladder filters run on audiodsp’s C nodes through a small bridge; the VCO and the ladders need audiodsp 0.6.8 and fall back to Python cores on an older one. The wave blender, the acid filter and a few other cores stay in Python because they need control inside the block or a model audiodsp does not have; the CV generators are vector code. docs/how-it-works/audiodsp.md says what is where and what the rack would still like from audiodsp. Nothing allocates in a block path, in the sense docs/how-it-works/allocation.md spells out for each interpreter, and the tests enforce it. docs/how-it-works/performance.md has measured block times, and docs/how-it-works/architecture.md the layout of the code.
Running the demos
With audiodsp installed (Install):
PYTHONPATH=lib .venv/bin/python examples/play_audio.py --no-live --wav
That renders twenty short movements, one per instrument, into
wav_exports/; give a movement number to render one. examples/poly_render.py
plays chords on a four-voice instrument and checks the steals for clicks;
examples/poly_bench.py times a polyphonic instrument. The same script runs
under a MicroPython build with audiodsp and ulab compiled in:
MICROPYPATH=lib micropython examples/play_audio.py --no-live --wav
Without --no-live the script tries board_config.pcm_out from the
omnipython package for live output and falls back to WAV files when that is
not available. examples/headless_synth.py is a smaller starting point, and
examples/patch2600_demo.py plays the Patch2600’s twelve patches. examples/hmi_instrument.py plays an
instrument’s demo phrase with the rack open to front panels over hmilink
(preview): a phone opens http://<this machine>:9000/, and
examples/rackview/lvgl_panel.py is the same panel as an LVGL screen. Both draw
a rack’s modules and cables, and turn knobs and patch cables on the rack.
examples/hmi_board.py does the same on a board.
Tests
The tests check that signals are present, finite and in range, that controls do what they say, that the bridge to audiodsp runs in lockstep, and that no module allocates an array while processing a block. There are no audio targets: an instrument’s trait file holds what its own sound measured when it was accepted, so a change that moves it shows up. CONTRIBUTING.md says how to run them and has the repo’s rules, and ROADMAP.md what is planned.