Start here
Quickstart
Connect to the Velum Studio running on your computer, follow what's on air, and switch a scene. About five minutes, in the language you like.
Before you start
- Velum Studio, running. The control API is on by default. You can see it, change its port and see or replace its token in Settings › Remote control.
- One of the SDKs. C# needs .NET 8, TypeScript needs Node 20 or later (or a browser), Python needs 3.10 or later. See installing the SDKs for where to get them.
You don't need a port or a token. Each running Studio writes both to a discovery file that only your user account can read, and the SDKs read it for you.
1. Connect
using Velum.Studio;
// The Studio running on this computer, found through its discovery file.
await using var studio = await VelumStudioClient.ConnectAsync(new VelumClientOptions { ClientName = "My App" });
Console.WriteLine($"Connected to {studio.Hello.InstanceName} {studio.Hello.Version}");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" });
console.log(`Connected to ${studio.hello.instance_name} ${studio.hello.version}`);import asyncio
from velum_studio import VelumStudioClient
async def main() -> None:
# The Studio running on this computer, found through its discovery file.
async with await VelumStudioClient.connect(client_name="My App") as studio:
print(f"Connected to {studio.hello.instance_name} {studio.hello.version}")
asyncio.run(main())ClientName is how Studio labels the changes your app makes. If more than one Studio is running, pick one by its instance name (for example "Velum Studio (2)"); otherwise you get the first.
2. Follow live state
Subscribe to a topic and Studio sends its whole value right away, then each change as it happens. The SDK keeps the latest value for you, typed.
studio.SceneChanged += (_, e) => Console.WriteLine($"On air: {e.Name}");
await studio.SubscribeAsync(TopicType.Scenes);
var scenes = studio.State.Scenes!;
foreach (var scene in scenes.Items.Values.OrderBy(s => s.Index))
Console.WriteLine($"{(scene.Id == scenes.Program ? "*" : " ")} {scene.Name}");studio.on("scene.changed", (e) => console.log(`On air: ${e.name}`));
await studio.subscribe("scenes");
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}`);
}studio.on(EventType.SCENE_CHANGED, lambda e: print(f"On air: {e.name}"))
await studio.subscribe(TopicType.SCENES)
scenes = studio.state.scenes
for scene in sorted(scenes.items.values(), key=lambda s: s.index):
print("*" if scene.id == scenes.program else " ", scene.name)Nothing polls. A topic is pushed when it changes, and the only regular message is the stats tick, once a second. State and topics explains each one.
3. Run an action
Every action in Studio's catalog is its own typed method, with typed parameters and a typed result.
var result = await studio.SceneSwitchAsync(new SceneSwitchParams { Scene = "Just Chatting" });
Console.WriteLine($"Switched to {result.Name}");
await studio.AudioMuteAsync(new AudioMuteParams { Input = "Mic", Mode = AudioMuteMode.Unmute });const result = await studio.sceneSwitch({ scene: "Just Chatting" });
console.log(`Switched to ${result.name}`);
await studio.audioMute({ input: "Mic", mode: "unmute" });result = await studio.scene_switch(scene="Just Chatting")
print(f"Switched to {result.name}")
await studio.audio_mute(input="Mic", mode=AudioMuteMode.UNMUTE)Scenes and sources can be named by id or by name. Names are matched exactly first, then ignoring case. Ids are safer, because people rename things; the topics give you both.
4. Handle what goes wrong
Every error Studio sends has its own class, with a plain-English message that's ready to show.
try
{
await studio.SceneSwitchAsync(new SceneSwitchParams { Scene = "Intermission" });
}
catch (VelumNotFoundException) { Console.WriteLine("No such scene"); }
catch (VelumException e) { Console.WriteLine($"{e.Code}: {e.Message}"); }import { VelumError, VelumNotFoundError } 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 VelumError) console.log(`${e.code}: ${e.message}`);
else throw e;
}try:
await studio.scene_switch(scene="Intermission")
except VelumNotFoundError:
print("No such scene")
except VelumError as e:
print(f"{e.code}: {e}")Where next
- Events and reconnecting: keep a long-running app in step when Studio restarts.
- The reference: every action, event and topic, generated from Studio's catalog.
- Devices on your network: control Studio from a phone, a tablet or another computer.
- Theming: change how Studio, and every extension in it, looks.

