Toolchain · first plugin · the commands
Build
A port is one vst.json, one parameter file, an engine, and optionally a
layout. The framework compiles the wrapper, generates the parameter table and draws the skin.
Setup
git clone https://github.com/sd88me/mpc-vst-plugins
export MPC_VST_PLUGINS=$PWD/mpc-vst-plugins
docker pull arm32v7/gcc:11-bullseye # the device toolchain (glibc 2.31)
Docker is not optional: the device is 32-bit ARM and the build must not pull a newer glibc than the device has. Everything else runs on the host.
The five files that matter
| File | What it decides |
|---|---|
vst.json | name, vendor, uid, version, sources, defines, layout, presets |
params.json / module json | the parameter contract — order is the VST index, append-only |
src/… | the engine |
layout.conf | what the screen shows (or custom_skin + your own TUI.json) |
build.sh / test.sh | two lines each around the framework tools |
The contract is the product
Parameters are a public API: presets, projects, Q-Links and the catalog all reference them by index. Append only. A reordered list silently breaks every saved project, and nobody notices until a user opens last week’s song.
The four commands
./build.sh # armhf .so + params.h + skin folder (docker)
./test.sh # x86 host test under ASan/UBSan (host, fast)
tools/bench.sh build/x.so <device-ip> # CPU on the real device
DEVICE=<ip> ./make_skinset.sh --deploy # stage the plugin folder on the device
test.sh is the one to run on every change: it creates two instances, exercises
set/get on every parameter, steps options the way a Q-Link does, renders audio, checks
NULL input, NRPN, thread stress and a chunk round-trip. It runs in seconds. If it fails, do not
deploy — a broken .so can take the app down, and MPC has no “unload plugin” button.
A first plugin, in order
- Stub the engine. Pass audio through unchanged. Build it, run the host test. If this does not pass, nothing later will.
- Parameters. Add the ones the sound needs, not the ones the UI wants. Give enums a label that does not start with a digit (see the traps).
- Skin. First
tools/studio.py serve, thenpreview. A layout is geometry plus a background; the renderer is the check, not your imagination. - Bench. On the device, early. Cost is not linear in “how much DSP you wrote” — a 4× oversampled saturator can be the whole budget.
- Device. Insert it, play it, save the project, reload it. A plugin that sounds right but loses its state on reload is not finished.
Traps that bite during the build
- Option labels beginning with a digit. The wrapper used to read
atoi("1/16")as the option index — the control snapped back while the sound changed. The current wrapper compares the full label first, but a port built against an older wrapper keeps the old behaviour. Avoid such labels; if you need them, add a round-trip test for every option of every enum (we do, 43 checks). - A parameter that is an enum in
params.jsonbut missing from the engine’s text table falls through toatof("On") == 0: the control flips and nothing happens. The offline test catches it; the device would not have. - Momentary parameters need
hold_ms, otherwise the wrapper reports 0 after a single frame and “hold the switch” never was a hold. - Degenerate ranges (
min == max) make MPC unable to notice that a readout changed; the plugin has to callaudioMasterUpdateDisplayitself, from the render block, never from inside a host callback. - No
layoutinvst.jsonmeans the auto-layout runs and an enum with more than six options becomes apopup, which then aborts the build because a hidden<key>__openparameter is missing. Write the layout.
What it costs (measured, Live II)
| Stage | Cost |
|---|---|
| tape-echo core alone | p99 ≈ 18.4 % |
| + 4× oversampled saturator | p99 ≈ 23.9 % (+5.5 pp) |
| + chorus, dropouts, spread | +0.7 pp together |
| whole plugin, 32 params, companion listener | p99 24.4 %, worst block 26.2 % |
| the companion HTTP thread | 0.0 % of a core |
A block is 2902 µs. If p99 crosses ~25 % the device is no longer comfortable; the oversampler is usually the first thing to question, not the modulation.