Control API
Devices on your network
A phone, a tablet or another computer can control Studio over the local network, once the streamer allows it and pairs the device. The connection is TLS, pinned to Studio's own certificate.
Turning it on
- In Studio, turn on Settings › Remote control › Allow devices on my network. Studio then also listens on port 28810 (or the next free one up to 28819) on the network. Only encrypted connections are accepted there.
- Choose Pair a device…. Studio shows a QR code and a one-time code. The code works once, for five minutes, and five wrong tries cancel it.
- On the device, scan the code (or paste its link).
The QR code
The QR code holds a link:
velum-remote://pair?v=1&host=192.168.1.20&port=28810&code=K7Q2M9XD&fp=2421562fd46b1f61…&name=Velum%20Studio| Field | Meaning |
|---|---|
v |
The link's version, 1. |
host, port |
Where Studio listens. |
code |
The one-time pairing code (Studio shows it as K7Q2-M9XD). |
fp |
The SHA-256 fingerprint of Studio's certificate, as 64 hex digits. |
name |
The instance name. |
Pairing
1. Connect with TLS to wss://<host>:<port>/pair, with no token. Studio's certificate is self-signed. Trust it only if its SHA-256 fingerprint equals fp, and ignore its name and issuer. This pin is what keeps a device from talking to an impostor, so check it before you send anything.
2. Claim the code. The connection carries on as the device once it succeeds.
→ { "jsonrpc": "2.0", "id": 1, "method": "pair.claim", "params": { "code": "K7Q2-M9XD", "name": "Living room iPad" } }
← { "jsonrpc": "2.0", "id": 1, "result": { "token": "…", "device_id": "9f2c…", "name": "Living room iPad", "instance_name": "Velum Studio", "protocol": "velum/1" } }3. Keep the token, the fingerprint and the address, privately. From then on, connect to wss://<host>:<port>/ with Authorization: Bearer <token>, pinning the same fingerprint.
A wrong or expired code is -32001 (unauthorized). Before it pairs, a device's hello says "auth": "pairing"; afterwards, "auth": "device".
Device tokens
- Each device has its own token. Studio keeps only its hash.
- Settings › Remote control lists paired devices. Remove disconnects a device at once and refuses its token from then on.
- The tokens don't cross over. The local token from the discovery file doesn't work over the network, and a device token doesn't work locally.
Scopes
What a paired device may run. The person chooses it when the device pairs (It may… next to Pair a device… in Studio) and can change it at any time in the device's row; a change applies to the device's next request. pair.claim's result and the device's hello both carry its scopes.
| Scope | What it covers |
|---|---|
control |
Running the show: scenes, studio mode and Take, transitions, layers on and off, framings, effects on and off, the mixer, media, Mirrors, screenshots, saving a replay, running automations, stats |
chat |
Chat: send, delete, ban, time out, chat modes, clear |
broadcast |
What starts and stops for everyone: go live, end the stream, recording, the replay buffer, the virtual camera, the destination, the title and category |
manage |
Changes to the setup: effect settings, text, automations on and off, Dynamic Sources variables, scene collections, a scene's own transition, freezing, updates, raw scene-model commands |
- Each action names its scope in the catalog (
scope), and the reference shows it on every action. Grey out what the device's scopes don't cover. - The presets in Studio are do everything (every scope, and every device paired before scopes existed), control the show (
control), moderate chat (chat) and only watch (none). - Reading is never scoped. Every paired device gets the catalog, the state topics and the events.
- An action outside the device's scopes fails with
-32018(forbidden);data.scopenames the scope it needs anddata.scopeswhat the device has. - Apps on this computer, with the local token, have every scope.
With an SDK
Every SDK pairs from the link and pins the fingerprint before anything is sent. Save what it returns, and connect with it from then on.
var device = await VelumStudioClient.PairAsync(PairingLink.Parse(qrText), "Studio Deck");
File.WriteAllText(path, device.ToJson()); // keep it private: the token is this device's own
await using var studio = await VelumStudioClient.ConnectAsync(
new VelumClientOptions { Device = PairedDevice.FromJson(File.ReadAllText(path)) });import { connectDevice, pair, parsePairingLink } from "velum-studio-client/node";
const device = await pair(parsePairingLink(qrText)!, "Studio Deck");
const studio = await connectDevice(device);device = await VelumStudioClient.pair(PairingLink.parse(qr_text), "Studio Deck")
Path("device.json").write_text(device.to_json())
studio = await VelumStudioClient.connect(device=PairedDevice.from_json(Path("device.json").read_text()))
