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
- Connect to
ws://127.0.0.1:<port>/with the token and thevelum.v1subprotocol. (Connecting) - Read the hello Studio sends first: its version, its catalog version, the topics it has and the features it supports.
- Subscribe to the topics you show. Studio answers with each topic's current value, then pushes every change. (State and topics)
- Call actions as methods, such as
scene.switchoraudio.mute, and get typed results. (Typed methods and events) - 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.

