Control API
Messages
Every message is a JSON-RPC 2.0 object in a WebSocket text frame. This page covers the conventions, and the handful of methods the protocol itself defines.
Conventions
{ "jsonrpc": "2.0", "id": 1, "method": "scene.switch", "params": { "scene": "Just Chatting" } }- Text frames only, each one JSON, each at most 1 MB.
- Replies carry the request's
id, with eitherresultorerror. - Notifications (requests without an
id) get no reply. Studio's own pushes,hello,stateand the events, are notifications too. - Batches. A JSON array of requests gets one array of replies.
- Order. Each request runs on its own, so a slow action such as going live never holds up a scene switch sent after it. Match replies to requests by
id, never by order. - In flight. A connection may have up to 32 requests running at once. Queue the rest.
- Params. Leave
paramsout for a method that takes none. Unknown parameters are refused, not ignored, so a misspelling is caught at once.
The protocol's methods
Besides one method per action (see Typed methods and events), the protocol defines these. No action id is ever one of these names.
catalog.list
Returns the whole catalog: every action, every event with its data's schema, every topic's schema, every error code, and every effect type's settings.
{ "version": 17, "protocol": "velum/1", "actions": [ … ], "events": [ … ],
"topics": { "scenes": { …JSON Schema… }, … }, "errors": [ … ],
"filter_settings": { "velum.filter.color_correction": { …JSON Schema… }, … } }action.run
Runs one action by id: {"id": "<action id>", "params": { … }}. It runs exactly the same action as calling the action's own method, with the same checks, errors and result. It's useful when the action is chosen at run time, such as from a picker.
→ { "jsonrpc": "2.0", "id": 7, "method": "action.run", "params": { "id": "audio.mute", "params": { "input": "Mic" } } }
← { "jsonrpc": "2.0", "id": 7, "result": { "input": "4d544b59-73d5-4105-9538-1a138a92cf34", "muted": true } }- Results describe what the action did. On and off actions return the new state, and a press that changes nothing still succeeds:
record.startwhile recording returns{"recording": true, "changed": false}. - Display actions (
destination.health,stats.show,stream.viewers) return their current value.
state.get
{"topics": ["scenes", "audio"]} returns {"scenes": {…}, "audio": {…}}. Leave topics out to get every topic. An unknown topic is an error (-32017). Use it to read a topic once without following it.
subscribe and unsubscribe
{"topics": ["scenes", "audio", "stream"]}. The reply lists every topic you now follow, and whether events come typed. Right after the reply, Studio sends each newly followed topic's current value as a state notification, so you never need a separate state.get. After that, each change arrives as soon as it happens.
→ { "jsonrpc": "2.0", "id": 4, "method": "subscribe", "params": { "topics": ["scenes", "chat", "activity"], "typed_events": true } }
← { "jsonrpc": "2.0", "id": 4, "result": { "topics": ["activity", "chat", "scenes"], "typed_events": true } }Add "typed_events": true to get each event as its own notification. It belongs to the connection and stays as set; see each event is a notification.
ping
Returns {"pong": true, "time_ms": …}. A ping every few seconds is a cheap way to notice a Studio that has stopped answering.
pair.claim
Available only to a device that is pairing. See Devices on your network.
What Studio pushes
| Notification | Carries | When |
|---|---|---|
hello |
Studio's identity, catalog version, topics and features | Once, right after connecting |
state |
{topic, value}: a topic's whole new value. Replace what you had. |
After subscribe, then on every change |
event |
{topic, name, data}: something happened |
While you follow the event's topic, unless you asked for typed events |
<event id> |
The event's data as params |
The same, when you asked for typed events |
Events (untyped) look like this:
← { "jsonrpc": "2.0", "method": "event", "params": { "topic": "scenes", "name": "scene.changed", "data": { "scene": "d73c…", "name": "Just Chatting" } } }meters sends audio levels ten times a second, so subscribe to it only while you show them. The full list of events is in the reference.

