The screen that leaves the device
Companion screen
MPC presents a plugin screen as pictures plus polled values. A plugin cannot draw, and every moving widget costs a redraw — enough of them and the audio crackles. So the plugin serves its own page instead, and any phone on the same WiFi becomes the screen.
Credit where it belongs
The idea is VADER’s (sunskiefer / L’Cronx, MIT): since v0.6.0 (2026-10-24) VADER serves its plugin screen as a web page, for exactly this reason, and documents it. What we borrowed is the approach — one canvas, motion integrated between updates, fullscreen, add-to-home-screen — not code.
What it looks like from outside
| Endpoint | Purpose |
|---|---|
GET / | the page — one canvas, no framework, no CDN |
GET /state | JSON snapshot, refreshed every ~46 ms by the render block |
POST /set?k=&v= | write a parameter (needs header X-MHE: 1) |
GET /diag | the last eight requests with peer and user agent |
GET /healthz | ok, for scripts |
Port 8099, overridable; MHEC_HTTP=0 turns the listener off entirely,
MHEC_HTTP_RW=0 makes it read-only. Four instance slots, ?i=0…3.
Five rules that keep it from hurting the device
- The audio thread only stores. The snapshot is written where the meter is already computed, behind a seqlock, with no allocation, no lock and no syscall beyond reading the clock. The server thread only loads. No pointer to the instance ever leaves the publish call, so destroying the instance cannot race the server into freed memory.
- Writes travel through a ring into the audio thread. The HTTP thread validates
and queues
{index, value};process_blockdrains it and applies it. The DSP state belongs to the render loop, not to a socket. - One ring per instance. A shared ring was our first version and it silently ate the other instance’s commands — the first audio thread to drain advanced the tail past them.
- The listener must not outlive the last instance. Count instances, and in the
last
detach()stop and join the thread. This is the rule that cost us two crashes. - A header and timeouts.
X-MHE: 1on writes means a stray web page cannot post to the plugin (it would need a preflight the server never grants);SO_SNDTIMEO/SO_RCVTIMEOmean a phone that stops reading cannot stall the single accept loop.
The page
Integrate the motion in the page: phases, reel angles, needle ballistics. Then a 7 Hz poll looks continuous, and you do not need a socket. (A socket is worth it when something must follow the audio clock sub-poll — a playhead in a sequencer. A knob panel is not that.)
function poll(){ fetch('/state',{cache:'no-store'}).then(r=>r.json()).then(j=>st=j).catch(()=>{}); }
setInterval(poll,140); poll();
function draw(now){
var dt = Math.min(0.1,(now-last)/1000); last = now;
hits.length = 0; // every frame, or it leaks
/* integrate: phase += dt*rate, needle spring, reel angle */
/* draw, and push each control's hit region */
requestAnimationFrame(draw);
}
function post(k,v){ fetch('/set?k='+k+'&v='+v,{method:'POST',headers:{'X-MHE':'1'}}); }
Details that matter on a phone: smallest-hit-wins and inset adjacent boxes by a pixel; drop the hit
regions of a page that is only sliding in; update optimistically, let /state confirm one
block later; and float the value above the finger, because the finger is exactly where the number was.
Build it once, reuse it
The reusable pieces live in the reference port and in a scaffold folder:
AKAI_MPC/VST/_framework/companion-screen/ (embed script, page test harness, the three
test drivers, a checklist). The page is a source file — web/index.html —
and a generator embeds it into the .so; a test asserts the embedded copy matches the
source, so an old page cannot ship.
What it is not
- Not authenticated. It is open on the LAN by design. Keep the read-only switch and say so in the README.
- Not a replacement for the skin. The device still needs a usable screen for when the phone is not there.
- Not free of CPU. It measured 0.0 % of a core in our bench — the thread sleeps in
poll()— but it does add a socket to your plugin, which catalog reviewers will ask about. Answer it in the release notes.