Docs — control API
Control API
Everything the on-screen controls can do, an external controller can do — from a MIDI surface, a lighting desk, or your own software. Four ways in, one stable protocol.
Transports
| Transport | Where | Notes |
|---|---|---|
| MIDI | Virtual destination StageVis Control | Hardware controllers connect automatically. Clock, start and
stop sync the tempo, and notes fire triggers named
midi-note-<n>. Mapping CC knobs and Program
Change to parameters and templates has no screen in the app yet; use
OSC or HTTP/WebSocket for that today. |
| OSC | UDP port 57824 |
Address patterns mirror the addressing scheme below. |
| HTTP + WebSocket | Port 57823 |
REST: GET /health, GET /discover,
GET /state, POST /command. Live updates
over WebSocket at /ws. |
| Data channel | Topic stagevis-control |
For controllers that already sit in the camera session. |
Locked by default
The control ports bind to the Mac itself (localhost). Control from another device on the LAN is an explicit opt-in in Settings and requires a bearer token that you hand to the controller (OSC has no login, so use it on trusted networks only). The camera connection is separate: the web camera QR carries a per-session join secret, so a device on the Wi-Fi cannot join as a camera without scanning the current QR, and an admitted camera cannot send control commands or change effects, styles, blackout, freeze or panic. Forget Camera… in the Cameras card ejects and blocks a camera. Use your own router or a production network for public venues.
Addressing
Every tunable parameter has a stable address:
style.<id>.<param>— pixel filters (strobe, mirrors, beat effects…)effect.<id>.<param>— semantic effects (face zoom, camera movement, Auto Smart Mode…)visual.<id>.<param>— generative visualizers
Don't guess IDs: ask the running app. GET /discover
returns the live catalog — every unit and parameter the app accepts,
with ranges and defaults. That reply is the source of truth.
Show safety
The panic command resets the pipeline to a clean
passthrough — the picture, untouched. The BLACK and FREEZE buttons remain
available on-screen no matter what a controller is doing.
Stability
The wire format is versioned and stable: integrations built today keep working across updates. Unknown fields are ignored rather than rejected.
Building a deeper integration? The full wire contract — versioning, atomic batches, error semantics, plus a JSON schema for every command — is available on request: hello@stagevis.app.