OSC protocol
Everything the engine does, it does over OSC — drive it and watch it from a script, a controller, or whatever you feel like wiring up.
Everything the engine does, it does over OSC. Studio is just the best-known client; the contract is open to anything that can sling OSC packets — a script, a hardware controller, a phone, whatever you feel like wiring up. This page covers the shape of that contract.
Getting in
The engine listens on its control port — 9000 by default (--osc-rx-port, or OMNIPHONY_OSC_PORT). OSC is off unless you turn it on (render.osc: true, or --osc); an engine inside mpv-omniphony turns it on by itself when there’s no config file yet.
- UDP, from anywhere on the network: what a phone, a controller or a script will use.
- TCP on loopback, same port number, OSC 1.0 framing (each packet preceded by its size as a big-endian int32, up to 1 MiB): for a client on the same machine that wants big payloads in one piece. That’s what Studio uses locally.
The control / state contract
Messages fall into two directions:
- Control —
/omniphony/control/…, sent client → engine to change state or trigger an action. - State —
/omniphony/state/…, emitted engine → registered clients when something changes (and as a snapshot on connect).
To receive state, a client registers: send /omniphony/register [listen_port]. The engine answers with the full state snapshot (several datagrams over UDP), the log backlog and the metering state, ending with /omniphony/state/snapshot_complete, then streams changes. Over UDP, keep it alive with /omniphony/heartbeat [listen_port] every few seconds — the engine replies /omniphony/heartbeat/ack, or /omniphony/heartbeat/unknown when it has forgotten you (re-register), and drops a client after 15 s of silence. Over TCP the connection is the session: no heartbeat needed. (Studio does exactly this — see Using Studio.)
State bundles and heartbeat acks carry a generation counter; a client that missed something sends /omniphony/control/state/refresh. /omniphony/sync is answered by /omniphony/sync/ack once everything sent before it has been handled.
Argument conventions
- Booleans are accepted as OSC
int(0/ non-zero),float, orbool; the engine coerces. Most toggles take a single int0/1. - Enums are lowercase strings.
- Refusals are answered. An unknown address, bad arguments, or a value the engine can’t apply comes back to the sender alone as
/omniphony/state/control_error [address, code, message](unknown_address,invalid_arguments,not_applied,undecodable,not_allowed). Stopping the engine or taking its port (quit,yield_port) is accepted from this machine only. - Realtime gain controls (
/control/realtime/*) carry a trailing monotonic sequence int so the engine can drop stale, out-of-order updates. - Larger structured payloads (layout, speakers, audio, input config) are sent as a single JSON string argument.
Options: one address for most settings
Most render settings are declared once in an options registry, with their type, range and default, published on /omniphony/state/options_schema. Set any of them with the generic /omniphony/control/option [key, value] (several at once with /control/options); the older per-setting addresses still work as aliases.
A few representative addresses
| Address | Args | Meaning |
|---|---|---|
/control/render_backend |
s |
Select the active backend by id. |
/control/backend/param |
[key, value] or [backend_id, key, value] |
Set a backend parameter (schema-driven). |
/control/realtime/master_gain |
f, seq int |
Master gain (linear). |
/control/output_mode |
s |
speaker / binaural output stage. |
/control/option |
[key, value] |
Any declared option. |
/control/placement/mode |
family, mode | Where a source family’s fixed channels go (sphere / room / manual). |
/control/save_config |
— | Write the render settings to config.yaml — the only way they get there. |
(All under /omniphony/.) The full state snapshot is published as /omniphony/state/renderer (JSON), with individual deltas for render config, metering, latency, head pose, and more.
Versioning
The engine advertises a contract revision (contractRevision in /omniphony/state/capabilities; 7 as of 0.7.0), so a client can tell what the engine on the other end understands. Studio shows a banner when the engine is older or newer than itself.
The machine-readable single source of truth for every address is the
omniphony-osc-contractcrate (osc-contract/in the repository, no dependencies;ALL_CONTROL,ALL_STATE,ALL_SESSION). Depend on it, or generate against it, rather than hardcoding strings, so your client never drifts from the engine. The repository’sdocs/osc-control-contract.mdis the full human-readable table.
Snapshot datagrams can reach 65 000 bytes: if you listen over UDP, give your socket a decent receive buffer.
Where backends fit
The two backend addresses in the table above (/control/render_backend, /control/backend/param) aren’t special-cased strings — the engine publishes each registered backend’s id, label, and parameter schema in the state snapshot, and every client (Studio included) generates its controls from that. So when you write your own backend, it shows up over this same contract for free, with no protocol changes.