Developer
Log in

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

JSON-RPC
{ "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 either result or error.
  • Notifications (requests without an id) get no reply. Studio's own pushes, hello, state and 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 params out 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.

JSON
{ "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.

JSON-RPC
→ { "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.start while 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.

JSON-RPC
→ { "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:

JSON-RPC
← { "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.

to open · ↑ ↓ to move · Esc to close