SDKs
TypeScript
Every action is a typed method, every event a typed notification (a discriminated union you can switch on), every piece of live state a typed value. For Node 20+ and browsers.
Install
The package is velum-studio-client: an ES module package with its own type declarations. In Node it uses ws, its only dependency; in a browser, the browser's own WebSocket.
npm: coming soon
Until it's on npm, install it from source.
npm install path/to/sdk/typescript # or: npm pack in sdk/typescript, then npm install the .tgzIt has two entry points: velum-studio-client (works everywhere) and velum-studio-client/node (adds discovery and pairing, which need Node).
Quick start (Node)
import { connectLocal } from "velum-studio-client/node";
// The Studio running on this computer, found through its discovery file.
const studio = await connectLocal({ clientName: "My App" });
studio.on("scene.changed", (e) => console.log(`On air: ${e.name}`));
studio.on("activity.raid", (e) => console.log(`Raid from ${e.author?.display}: ${e.amount?.value} viewers`));
// Topics bring their state and their events; state is filled when this resolves.
await studio.subscribe("scenes", "activity");
const result = await studio.sceneSwitch({ scene: "Just Chatting" });
console.log(`Switched to ${result.name}`);
const scenes = studio.state.scenes!;
for (const scene of Object.values(scenes.items).sort((a, b) => a.index - b.index)) {
console.log(`${scene.id === scenes.program ? "*" : " "} ${scene.name}`);
}In a browser
A browser can't set headers on a WebSocket, so the token goes in the address (?token=…), which Studio accepts. The browser can't read Studio's discovery file either: your app gets the port and the token some other way (the person pastes them, or a 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",
});Keep the token private: anyone with it can control Studio.
Actions
Each action is one method, named after its id, taking that action's parameters and returning its result, both typed:
| Action id | Method | Parameters | Result |
|---|---|---|---|
scene.switch |
sceneSwitch |
SceneSwitchParams |
SceneSwitchResult |
audio.mute |
audioMute |
AudioMuteParams |
AudioMuteResult |
record.toggle |
recordToggle |
(none) | RecordToggleResult |
- A fixed set of words is a string-literal union:
audioMute({ input: "Mic", mode: "unmute" }), andmode: "loud"doesn't compile. run("audio.mute", { input: "Mic" })runs an action chosen at run time, still typed by its id.ActionMapmaps every id to its parameters and result, andACTIONSlists every action with its name, description, group and parameters, for building pickers.runById("some.action", {...})runs an action newer than this SDK.
Every action's exact signature is in the reference.
Events
Each event has its own handler, typed by its id:
studio.on("chat.message", (e) => console.log(`${e.author?.display}: ${e.text}`));
studio.on("activity.support", (e) => console.log(`${e.author?.display} sent ${e.amount?.display}`));onEvent gets every event as { type, data }, a discriminated union, so switch (e.type) narrows e.data:
studio.onEvent((e) => {
switch (e.type) {
case "scene.changed": console.log(`On air: ${e.data.name}`); break;
case "activity.raid": console.log(`Raid: ${e.data.amount?.value} viewers`); break;
case "chat.deleted": console.log(`${e.data.eids.length} messages removed`); break;
}
});- An event comes while you follow its topic (
scenes,chat,activity).subscribeEvents("activity.raid")follows the topics that bring the events you name, andEVENTSsays which topic each needs. - Chat rows.
chat.messageand the activity events all carry aChatRow. - Handlers run as Studio's messages arrive, in order. One that throws doesn't stop the client:
onHandlerErrorhears about it. - New words. A word Studio adds later (a new stream state, say) arrives as a string the union doesn't list yet; handle the cases you know and let the rest through.
State
studio.state holds each subscribed topic's latest value, typed by TopicMap; onState hears each change:
await studio.subscribe("audio", "stream");
studio.onState("stream", (s) => console.log(`Stream: ${s.state} for ${s.seconds} s`));
const mic = Object.values(studio.state.audio!.items).find((a) => a.name === "Mic");fetchState() reads topics once without following them.
Errors
Every error Studio sends rejects as its own class, deriving from VelumError, with Studio's plain-English message and its code:
import { VelumError, VelumNotFoundError, VelumRateLimitedError } from "velum-studio-client";
try {
await studio.sceneSwitch({ scene: "Intermission" });
} catch (e) {
if (e instanceof VelumNotFoundError) console.log("No such scene");
else if (e instanceof VelumRateLimitedError) setTimeout(retry, e.retryAfterMs ?? 3000);
else if (e instanceof VelumError) console.log(`${e.code}: ${e.message}`);
else throw e;
}VelumConnectionError means Studio couldn't be reached, or the connection closed before the answer came. Every code's class is in the error reference.
Connecting (Node)
- This computer.
connectLocal()reads Studio's discovery file, skips Studios that aren't running, and connects with the token in theAuthorizationheader over thevelum.v1subprotocol. - Several Studios.
findRunning()lists them; pick one withinstanceName(orport). - Reconnecting is on by default. When Studio restarts or the connection drops, the client reads the discovery file again, reconnects and follows the same topics again (
onDisconnected,onReconnected). See Events and reconnecting. - Another computer. Pair once with the QR code's link and keep the result privately. The connection is TLS, trusted only when Studio's certificate has the QR code's fingerprint, checked before anything is sent:
import { connectDevice, pair, parsePairingLink } from "velum-studio-client/node";
const device = await pair(parsePairingLink(qrText)!, "Studio Deck");
const studio = await connectDevice(device);Versioning
CATALOG.version is the catalog version this SDK was generated from; studio.hello.catalog_version is the running Studio's. The package version is the generator's major version, then the catalog version (1.17.0 for catalog version 17); CATALOG.fingerprint tells two builds of one catalog version apart. An older SDK keeps working with a newer Studio; the newer events arrive through onUnknown.
A complete example
A console app that lists scenes, switches them from the keyboard, and prints chat and activity. This is the SDK's own example, copied here when the site is built:
// SPDX-License-Identifier: MIT
// A small console app: connect to the Velum Studio running on this
// computer, list its scenes, print scene changes, chat and activity as they
// happen, and switch scenes from the keyboard.
//
// npm run example
// npm run example -- "Velum Studio (2)" (another instance)
import { createInterface } from "node:readline/promises";
import { VelumError } from "velum-studio-client";
import { connectLocal } from "velum-studio-client/node";
const studio = await connectLocal({ clientName: "Sample console", instanceName: process.argv[2] });
console.log(`Connected to ${studio.hello.instance_name} ${studio.hello.version}.`);
studio.on("scene.changed", (e) => console.log(`On air: ${e.name}`));
studio.on("chat.message", (e) => console.log(`[${e.platform}] ${e.author?.display}: ${e.text}`));
studio.onEvent((e) => {
if (e.type.startsWith("activity.")) console.log(`${e.type}: ${e.data.text}`);
});
studio.onDisconnected((d) => console.log(`Disconnected (${d.reason})${d.reconnecting ? "; reconnecting…" : ""}`));
studio.onReconnected((h) => console.log(`Reconnected to ${h.instance_name}.`));
await studio.subscribe("scenes", "chat", "activity");
const rl = createInterface({ input: process.stdin, output: process.stdout });
for (;;) {
const scenes = Object.values(studio.state.scenes.items).sort((a, b) => a.index - b.index);
scenes.forEach((s, i) => console.log(` ${s.id === studio.state.scenes.program ? "*" : " "} ${i + 1}. ${s.name}`));
const line = (await rl.question("Number to put on air, q to quit: ")).trim();
if (line === "q") break;
const scene = scenes[Number(line) - 1];
if (!scene) continue;
try {
const r = await studio.sceneSwitch({ scene: scene.id });
console.log(`Switched to ${r.name}.`);
} catch (e) {
if (e instanceof VelumError) console.log(`Studio said: ${e.message}`);
else throw e;
}
}
rl.close();
await studio.close();npm run example
npm run example -- "Velum Studio (2)" # another instance
