Developer
Log in

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

C#
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}");
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" });
console.log(`Connected to ${studio.hello.instance_name} ${studio.hello.version}`);
Python
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.

C#
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}");
TypeScript
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}`);
}
Python
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.

C#
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 });
TypeScript
const result = await studio.sceneSwitch({ scene: "Just Chatting" });
console.log(`Switched to ${result.name}`);

await studio.audioMute({ input: "Mic", mode: "unmute" });
Python
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.

C#
try
{
    await studio.SceneSwitchAsync(new SceneSwitchParams { Scene = "Intermission" });
}
catch (VelumNotFoundException) { Console.WriteLine("No such scene"); }
catch (VelumException e) { Console.WriteLine($"{e.Code}: {e.Message}"); }
TypeScript
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;
}
Python
try:
    await studio.scene_switch(scene="Intermission")
except VelumNotFoundError:
    print("No such scene")
except VelumError as e:
    print(f"{e.code}: {e}")

Where next

to open · ↑ ↓ to move · Esc to close