MPC VST · field notes

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

EndpointPurpose
GET /the page — one canvas, no framework, no CDN
GET /stateJSON snapshot, refreshed every ~46 ms by the render block
POST /set?k=&v=write a parameter (needs header X-MHE: 1)
GET /diagthe last eight requests with peer and user agent
GET /healthzok, 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

  1. 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.
  2. Writes travel through a ring into the audio thread. The HTTP thread validates and queues {index, value}; process_block drains it and applies it. The DSP state belongs to the render loop, not to a socket.
  3. 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.
  4. 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.
  5. A header and timeouts. X-MHE: 1 on writes means a stray web page cannot post to the plugin (it would need a preflight the server never grants); SO_SNDTIMEO/SO_RCVTIMEO mean 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

Next: testing →