Developer
Log in

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:ro and --filesystem=~/.var/app/com.legendremedia.velumstudio/config/velum-studio:ro; connecting to 127.0.0.1 needs only --share=network.
JSONcontrol.json
{
  "protocol": "velum/1",
  "instances": [
    { "port": 28710, "token": "3714ba…", "pid": 4242, "instanceName": "Velum Studio", "version": "0.1.1-beta.57" }
  ]
}
  • version is Studio's version, as About shows it. Don't use it to tell what Studio can do: the hello's catalog_version and features say 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 pid isn'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 protocol in the hello instead.
  • A handshake that offers only other subprotocols is refused with HTTP 400.
HTTP
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 deck

The hello

Right after connecting, Studio sends a hello notification:

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

Node.js
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);
});
Python
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.

TypeScript
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.

to open · ↑ ↓ to move · Esc to close