Developer
Log in

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.

Shell
npm install path/to/sdk/typescript     # or: npm pack in sdk/typescript, then npm install the .tgz

It has two entry points: velum-studio-client (works everywhere) and velum-studio-client/node (adds discovery and pairing, which need Node).

Quick start (Node)

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

TypeScript
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" }), and mode: "loud" doesn't compile.
  • run("audio.mute", { input: "Mic" }) runs an action chosen at run time, still typed by its id. ActionMap maps every id to its parameters and result, and ACTIONS lists 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:

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

TypeScript
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, and EVENTS says which topic each needs.
  • Chat rows. chat.message and the activity events all carry a ChatRow.
  • Handlers run as Studio's messages arrive, in order. One that throws doesn't stop the client: onHandlerError hears 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:

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

TypeScript
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 the Authorization header over the velum.v1 subprotocol.
  • Several Studios. findRunning() lists them; pick one with instanceName (or port).
  • 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:
TypeScript
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:

JavaScriptsdk/typescript/examples/console.mjs
// 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();
Shell
npm run example
npm run example -- "Velum Studio (2)"     # another instance

to open · ↑ ↓ to move · Esc to close