MPC VST · field notes

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

FileWhat it decides
vst.jsonname, vendor, uid, version, sources, defines, layout, presets
params.json / module jsonthe parameter contract — order is the VST index, append-only
src/…the engine
layout.confwhat the screen shows (or custom_skin + your own TUI.json)
build.sh / test.shtwo 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

  1. Stub the engine. Pass audio through unchanged. Build it, run the host test. If this does not pass, nothing later will.
  2. 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).
  3. Skin. First tools/studio.py serve, then preview. A layout is geometry plus a background; the renderer is the check, not your imagination.
  4. Bench. On the device, early. Cost is not linear in “how much DSP you wrote” — a 4× oversampled saturator can be the whole budget.
  5. 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

What it costs (measured, Live II)

StageCost
tape-echo core alonep99 ≈ 18.4 %
+ 4× oversampled saturatorp99 ≈ 23.9 % (+5.5 pp)
+ chorus, dropouts, spread+0.7 pp together
whole plugin, 32 params, companion listenerp99 24.4 %, worst block 26.2 %
the companion HTTP thread0.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.

Next: the device →