Developer
Log in

Control API

The control API

Velum Studio runs a small server that other apps can use to control it: control surfaces, phone and tablet apps, bots, and your own scripts. This section is the protocol, end to end.

At a glance

Protocol JSON-RPC 2.0 over WebSocket. The protocol is named velum/1; its WebSocket subprotocol is velum.v1.
On this computer ws://127.0.0.1:<port>/ with a token. Both are in the discovery file. The default port is 28710.
From other devices wss://<address>:<port>/, only after you allow it in Studio and pair the device. Off by default.
Catalog catalog.list describes every action, event, state topic and error, with JSON Schemas. Clients build their pickers from it.
Typed Every action is its own method; every event can arrive as its own notification.
Pushed state Subscribe to topics and Studio sends each change as it happens. Nothing polls.

You can turn the API off, change its port, and see or replace the token in Settings › Remote control.

The shape of a session

  1. Connect to ws://127.0.0.1:<port>/ with the token and the velum.v1 subprotocol. (Connecting)
  2. Read the hello Studio sends first: its version, its catalog version, the topics it has and the features it supports.
  3. Subscribe to the topics you show. Studio answers with each topic's current value, then pushes every change. (State and topics)
  4. Call actions as methods, such as scene.switch or audio.mute, and get typed results. (Typed methods and events)
  5. Stay connected. If Studio restarts, read the discovery file again (the port and token may have changed) and subscribe again. (Events and reconnecting)
On the wire
← { "jsonrpc": "2.0", "method": "hello", "params": { "protocol": "velum/1", "instance_name": "Velum Studio", "version": "0.1.1-beta.57", "catalog_version": 17, "auth": "local", "topics": ["scenes", "audio", "…"], "features": ["typed_methods", "typed_events"] } }
→ { "jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": { "topics": ["scenes"], "typed_events": true } }
← { "jsonrpc": "2.0", "id": 1, "result": { "topics": ["scenes"], "typed_events": true } }
← { "jsonrpc": "2.0", "method": "state", "params": { "topic": "scenes", "value": { "program": "d73c5e2a-…", "program_name": "Just Chatting", "…": "…" } } }
→ { "jsonrpc": "2.0", "id": 2, "method": "scene.switch", "params": { "scene": "Be Right Back" } }
← { "jsonrpc": "2.0", "id": 2, "result": { "scene": "4b1e…", "name": "Be Right Back" } }
← { "jsonrpc": "2.0", "method": "scene.changed", "params": { "scene": "4b1e…", "name": "Be Right Back" } }

Principles

  • One catalog. Everything Studio can do from the API is listed by catalog.list, with typed parameters, a result schema, the live state that goes with it and the controls it suits. Studio lists only what it can do today.
  • Ids never change. An action's id is stored on people's Stream Deck keys and Touch Portal buttons, so once shipped it never changes or goes away. New actions are added. (Versioning)
  • Plain English. Names, descriptions and error messages are written to be shown to people as they are.
  • Safe by default. Actions that end something viewers see need explicit confirmation. No secret ever crosses the API: no stream keys, no platform tokens. Network access is off until someone turns it on. (Errors and limits)
  • API changes are ordinary edits. A scene change made through the API shows in every panel at once. It isn't an undo step, so a control surface never buries the streamer's own edits in Edit › Undo.

In this section

  • Connecting: the discovery file, the token, the subprotocol and the hello.
  • Messages: JSON-RPC as Studio speaks it, and the protocol's own methods.
  • Typed methods and events: calling actions directly, getting events as their own notifications, and reading the schemas.
  • State and topics: what each topic holds, and how a value is pushed.
  • The catalog: actions, parameter types and live state, for building pickers and settings forms.
  • Errors and limits: every code, rate limits and the safety rules.
  • Devices on your network: pairing a phone, tablet or another computer over TLS.
  • Updates: checking for and installing Studio updates from a client.
  • Versioning: catalog versions and how clients stay in step.

to open · ↑ ↓ to move · Esc to close