Everything you need to build an audio plugin for MOD-powered devices — from source code to a working pedal on your unit.
This is the reference documentation for the MOD platform. If you are building plugins for MOD Duo, MOD Duo X, MOD Dwarf or MOD Desktop, start here.
Plugins for MOD are LV2 plugins. LV2 is an open, extensible standard — MOD did not invent it and does not control it, and a plugin you write for MOD is a normal LV2 plugin that runs anywhere LV2 runs.
There are no licensing requirements for making LV2 plugins for MOD. Build one, install it, give it away, sell it elsewhere — none of that involves us.
MOD defines a small number of LV2 extensions that let a plugin describe itself more richly to MOD devices: how it looks, how it is categorised, how its controls behave. They are published openly:
| Extension | Purpose |
|---|---|
mod: |
Plugin metadata — brand, label, ranges, per-device defaults, CV, file types |
modgui: |
The plugin's web interface |
modpedal: |
Pedalboard format — written by MOD's UI, not by plugin developers |
mod:license |
Copy protection and trial mode, for commercial plugins |
All are ISC licensed. Using them is optional; a plugin with no MOD extensions at all still works.
These frameworks export LV2 and are known to work:
- DPF — lightweight, C++, first-class MOD support. The path of least resistance
- JUCE — LV2 export since version 7
- Rust
- Pure Data, via hvcc — no C++ required
- Max gen~, via max-gen-skeleton
You can also write plain C against the LV2 headers directly — no framework required.
FAUST, Max gen~ and Pure Data sources, and any .mk recipe, can also be built with no local
toolchain at all on builder.mod.audio, which installs the result on
a USB-connected unit from the browser — see BUILDING.md § "Building without a
toolchain: the Cloud Builder" for which browser needs which URL.
Getting a plugin built and running
- REQUIREMENTS.md — how MOD expects a plugin to behave. Read before writing DSP
- BUILDING.md — building with
mod-plugin-builder - RECIPES.md — the
.mkpackage format, which is how MOD builds your plugin - VALIDATING.md — checking your bundle before you ship it
- INSTALLING.md — getting the bundle onto your MOD unit
Making it a real plugin
- MODGUI.md — the web interface. How to give your plugin a pedal face
- METADATA.md — brand, label, control ranges, per-device defaults
- CATEGORIES.md — how plugins are classified in the store
- LV2-FEATURES.md — which LV2 features and extensions MOD supports
- TIME.md — tempo and transport
- CAVEATS.md — target-specific gotchas worth knowing before you hit them
Commercial plugins
- LICENSING.md — copy protection and trial mode. Coming later — placeholder for now
A MOD device runs an embedded Linux system with a real-time kernel. Audio is handled by JACK2, with mod-host on top loading and connecting plugins. mod-ui serves the web interface that users actually see, and renders your modgui.
All MOD systems run at 48 kHz.
The same stack runs on every MOD product, which is why one plugin bundle works across the range.
| Target | Hardware | Product |
|---|---|---|
modduo |
AllWinner A20, dual-core Cortex-A7 (ARMv7) | MOD Duo — the original 2016 unit (NAND storage) and MOD Duo 2020 (eMMC storage) are the same CPU and the same build target |
modduox |
RockChip RK3399, big.LITTLE: 2× Cortex-A72 + 4× Cortex-A53 (AArch64) | MOD Duo X |
moddwarf |
RockChip PX30, quad-core Cortex-A35 (AArch64) | MOD Dwarf |
generic-x86_64 |
x86-64 | Desktop — for building and validating |
A target name is exactly the name of its plugins-dep/configs/<target>_defconfig in
mod-plugin-builder; ./build and ./validate will list them if you get one wrong. Note that
the desktop target is generic-x86_64, not x86_64.
modduox's toolchain compiles for the Cortex-A53 cores specifically
(CT_ARCH_CPU=cortex-a53 in mod-plugin-builder/toolchain/modduox.config), not the Duo X's two
Cortex-A72 cores — your code still runs on either, it's just not tuned for the A72's pipeline.
Size a CPU budget on the A53 figures in CAVEATS.md, not an assumption of
A72-class headroom.
A 2019 pre-release Duo X ("Limited Edition") shipped in small numbers with an NXP i.MX8 chip instead of the RK3399 above. It was superseded by the production unit and isn't a target this toolchain distinguishes.
Most targets also have a -new variant — moddwarf-new, modduox-new, modduo-new — which is
the same device on a newer toolchain (GCC 9.4.0, glibc 2.27). This is what MOD's own current
builds use, so prefer it unless you have a reason not to. See CAVEATS.md for the
compiler and libc of each.
The Dwarf is the weakest target, not the strongest. Its Cortex-A35 is in-order and significantly slower per clock than the Duo X's A53. If you size your CPU budget on one device, size it on the Dwarf.
generic-x86_64 is not a shipping device target. It exists so you can build and test on your own
machine before cross-compiling, and it is the only target on which the automated runtime tests can
run. Use it constantly; it will save you hours.
mod-plugin-builder also cross-compiles for the Darkglass Anagram — Darkglass's own hardware, on
the same LV2 / JACK2 / mod-host stack. That's why darkglass-anagram platform names show up
alongside MOD's own inside the toolchain (see BUILDING.md). Darkglass maintain
their own developer documentation for Anagram:
Plugin-Dev-Setup. If you're building
specifically for Anagram, start there — it covers Anagram-specific mechanics this repo doesn't.
| Repository | What it is |
|---|---|
| mod-plugin-builder | The cross-compilation toolchain. This documentation describes how to use it |
| mod-lv2-extensions | The MOD LV2 extension definitions |
| mod-plugin-cookbook | Generate a plugin from a plain-language description |
| mod-host | The LV2 host |
| mod-ui | The web interface that renders your modgui |
| mod-sdk | Older interactive modgui editor. Unmaintained; its template and artwork library is still useful — see MODGUI.md |
| Darkglass Plugin-Dev-Setup | Darkglass's own developer docs for the Anagram, built on the same mod-plugin-builder toolchain this repository documents |
- Forum: forum.mod.audio — the plugin developer community
- Issues: open one on this repository for documentation problems
ISC. Use this documentation, quote it, adapt it, build on it.