Control API
Connecting
A client on the same computer finds Studio through a discovery file, connects with a token over the velum.v1 subprotocol, and gets a hello describing what this Studio can do.
The discovery file
Each running Studio adds an entry to control.json in Studio's folder:
| System | Where |
|---|---|
| Windows | %APPDATA%\CLEARLYlogic\Velum Studio\control.json |
| macOS | ~/Library/Application Support/com.legendremedia.velumstudio/control.json |
| Linux | $XDG_CONFIG_HOME/velum-studio/control.json (usually ~/.config/velum-studio/control.json) |
| Linux, Flatpak | ~/.var/app/com.legendremedia.velumstudio/config/velum-studio/control.json |
- Windows, older builds. Before 0.1.1-beta.36 the folder was
%APPDATA%\Legendre Media\Velum Studio\. A newer Studio moves the folder the first time it starts, but a Studio that hasn't been updated yet still writes there, so look in both, the current one first. - Flatpak. The sandbox gives Studio its own config folder, so a Flatpak Studio's file isn't in
~/.config. A client that runs outside the sandbox should look in both Linux places. A client that is itself a Flatpak needs read access to them, for example--filesystem=~/.config/velum-studio:roand--filesystem=~/.var/app/com.legendremedia.velumstudio/config/velum-studio:ro; connecting to 127.0.0.1 needs only--share=network.
{
"protocol": "velum/1",
"instances": [
{ "port": 28710, "token": "3714ba…", "pid": 4242, "instanceName": "Velum Studio", "version": "0.1.1-beta.57" }
]
}versionis Studio's version, as About shows it. Don't use it to tell what Studio can do: the hello'scatalog_versionandfeaturessay that.- Several Studios at once. Each has its own entry, port and name. A second Studio is named "Velum Studio (2)", and so on. Let people pick the instance, and default to the first one.
- When Studio quits, it removes its entry. If the file is missing, no Studio is running. If Studio crashed, its entry stays until the next Studio starts, so skip any entry whose
pidisn't running or whose port refuses the connection. - Privacy. The file is readable only by your user account, because it holds the token. Don't copy the token anywhere else, and never log it.
The default port is 28710. If it's taken, Studio uses the next free one up to 28719, and the discovery file says which.
Read it again before every reconnect
The port and the token can change when Studio restarts, or when someone regenerates the token in Settings. Clients that re-read the file before each attempt simply keep working. The SDKs do this for you.
Authenticating
A token is required on every connection, even from this computer. Send it in either of these ways:
- A header:
Authorization: Bearer <token>. Use this whenever you can. - The query string:
ws://127.0.0.1:28710/?token=<token>, for clients that can't set headers, such as browsers.
Without a valid token, the WebSocket handshake fails with HTTP 401. Regenerating the token in Settings disconnects every client that used the old one; they need to read the discovery file again.
Name your client with the X-Velum-Client: <name> header, or ?client=<name>. Studio records the changes your client makes under that name.
The subprotocol
Ask for the velum.v1 subprotocol (Sec-WebSocket-Protocol: velum.v1) and Studio confirms it. A WebSocket subprotocol can't contain a /, which is why it isn't velum/1.
- Offering no subprotocol is also accepted; check
protocolin the hello instead. - A handshake that offers only other subprotocols is refused with HTTP 400.
GET / HTTP/1.1
Host: 127.0.0.1:28710
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: velum.v1
Authorization: Bearer 3714ba…
X-Velum-Client: My deckThe hello
Right after connecting, Studio sends a hello notification:
{ "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", "layers", "filters", "audio", "sources", "automations", "stream", "record", "vcam",
"destinations", "stats", "meters", "chat", "activity", "stream_info", "dynamic", "variables",
"avatars", "collections", "replay", "media", "web", "transitions", "update", "theme",
"audio_groups", "veloq", "app_volume", "gpus", "network", "source_settings"],
"scopes": ["control", "chat", "broadcast", "manage"],
"features": ["typed_methods", "typed_events", "scopes", "chat_view", "remote_channel"] } }| Field | Meaning |
|---|---|
protocol |
Always velum/1. |
instance_name, version |
Which Studio this is, and its version. |
catalog_version |
The catalog version of this Studio. Compare it with the one your client was built against. |
auth |
local (a client on this computer), device (a paired device), or pairing (a device that hasn't paired yet). |
topics |
The state topics this Studio has. |
scopes |
What this connection may run: every scope for an app on this computer, the device's own for a paired device. See Scopes. |
features |
What it supports beyond the base protocol: typed_methods (each action is its own method), typed_events (each event can be its own notification), scopes (paired devices have scopes), chat_view (chat as Studio's Chat dock draws it, for Velum Remote) and remote_channel (Velum Remote's encrypted channel). A Studio without features has none of them. |
A connection by hand
The SDKs do all of this. Without one, here it is in Node with the ws package and in Python with websocket-client:
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import WebSocket from "ws";
const home = os.homedir();
const dirs = process.platform === "win32"
? ["CLEARLYlogic", "Legendre Media"].map((f) => path.join(process.env.APPDATA, f, "Velum Studio")) // now, then before beta.36
: process.platform === "darwin" ? [path.join(home, "Library/Application Support/com.legendremedia.velumstudio")]
: [path.join(process.env.XDG_CONFIG_HOME ?? path.join(home, ".config"), "velum-studio"),
path.join(home, ".var/app/com.legendremedia.velumstudio/config/velum-studio")]; // native, then Flatpak
const file = dirs.map((d) => path.join(d, "control.json")).find((f) => fs.existsSync(f));
const [studio] = JSON.parse(fs.readFileSync(file, "utf8")).instances;
const ws = new WebSocket(`ws://127.0.0.1:${studio.port}/`, "velum.v1", {
headers: { Authorization: `Bearer ${studio.token}`, "X-Velum-Client": "My deck" },
});
let next = 1;
const call = (method, params) => ws.send(JSON.stringify({ jsonrpc: "2.0", id: next++, method, params }));
ws.on("open", () => {
call("subscribe", { topics: ["scenes"], typed_events: true });
call("scene.switch", { scene: "Just Chatting" });
});
ws.on("message", (data) => {
const m = JSON.parse(data);
if (m.method === "state" && m.params.topic === "scenes") console.log("On air:", m.params.value.program_name);
if (m.method === "scene.changed") console.log("Switched to", m.params.name);
if (m.error) console.error(m.error.message);
});import json, os, websocket
dir = os.path.expanduser("~/.config/velum-studio") # Linux, not Flatpak; see the table above
studio = json.load(open(os.path.join(dir, "control.json")))["instances"][0]
ws = websocket.create_connection(f"ws://127.0.0.1:{studio['port']}/",
header=[f"Authorization: Bearer {studio['token']}"], subprotocols=["velum.v1"])
print(json.loads(ws.recv())["params"]) # hello
ws.send(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "audio.mute", "params": {"input": "Mic"}}))
print(json.loads(ws.recv()))The Python sample reads one message for its answer for brevity. A real client reads in a loop and matches answers by id, because notifications can arrive in between.
From a browser
A browser can't set headers on a WebSocket, so the token goes in the address, ?token=…, which Studio accepts. A browser can't read the discovery file either: your app needs the port and the token some other way, for example the person pastes them from Settings › Remote control, or a small local helper serves them.
import { VelumStudioClient } from "velum-studio-client";
const studio = await VelumStudioClient.connect({
endpoint: { url: "ws://127.0.0.1:28710/", token },
clientName: "My Overlay",
});Anyone with the token can control Studio, so keep it out of anything you publish.
Other devices
The local token works only on this computer. A phone, tablet or another computer connects over TLS on a separate port, with its own token, after it pairs. See Devices on your network.

