Developer
Log in

SDKs

SDKs

Client libraries for the control API, generated from Studio's catalog: every action is a typed function, every event a typed value, every state topic a typed record, every error its own class.

Language Runs on Depends on
C# .NET 8 on Windows, macOS and Linux; trimming- and Native AOT-safe The base class library only
TypeScript and JavaScript Node 20+ and browsers (ES modules) ws in Node; nothing in a browser
Python Python 3.10+, asyncio websockets

Each one:

  • types every action (parameters and result), every event, every state topic and every error code;
  • finds Studio through its discovery file on Windows, macOS and Linux, and skips Studios that aren't running;
  • reconnects when Studio restarts, reading the discovery file again and following the same topics;
  • pairs with Studio on another computer over TLS pinned to Studio's certificate.

Install

LanguagePackageVersion
C#Velum.Studio.Client1.21.0
TypeScript and JavaScriptvelum-studio-client1.17.0
Pythonvelum-studio-client1.21.0

All three were generated from catalog version 21 (fingerprint 25ecd76a642cc5f5) by generator 1.0.0.

Package registries: coming soon

The SDKs will be published to NuGet, npm and PyPI under the package names above. Until then, they install from source, as below.

C#
# Reference the project…
dotnet add reference path/to/sdk/csharp/src/Velum.Studio.Client/Velum.Studio.Client.csproj
# …or pack it and reference the package
dotnet pack sdk/csharp/src/Velum.Studio.Client -c Release -o ./packages
dotnet add package Velum.Studio.Client --source ./packages
TypeScript
npm install path/to/sdk/typescript     # or: npm pack in sdk/typescript, then npm install the .tgz
Python
pip install path/to/sdk/python

How they're made

Text
Studio's catalog (catalog.list)  →  catalog snapshot  →  generator  →  one SDK per language
  1. The catalog. catalog.list describes every action (parameters and result as JSON Schema), every event, every state topic and every error code. The SDKs are generated from a snapshot of exactly what a running Studio returns.
  2. The generator reads the snapshot once into a language-neutral model (records, enums, tagged unions, actions, events, topics, errors, with stable names derived from the ids), then a back end per language writes that language's files.
  3. Each SDK keeps its hand-written part (the connection, discovery, reconnecting, pairing) apart from its generated part, which is never edited by hand.

Names come straight from the ids, the same way in every language, so you can predict them:

Catalog C# TypeScript Python
Action scene.switch SceneSwitchAsync(SceneSwitchParams) sceneSwitch(params) scene_switch(scene=…)
Event activity.raid ActivityRaid event, ActivityRaidEvent "activity.raid" handler EventType.ACTIVITY_RAID, ActivityRaidEvent
Topic stream_info TopicType.StreamInfo "stream_info" TopicType.STREAM_INFO
Error not_found VelumNotFoundException VelumNotFoundError VelumNotFoundError

The reference shows each action's signature in all three.

Choosing actions at run time

Every SDK also carries the catalog's metadata, for tools where people pick an action: a button editor, a macro builder. Each lists every action with its name, description, group and parameters (ActionTypes.All in C#, ACTIONS in TypeScript and Python), runs a chosen action with a typed result, and runs an action newer than the SDK by id with JSON parameters.

Newer Studio, older SDK

Everything the SDK knows keeps working. Studio's hello says its catalog version; newer actions run by id, and newer events arrive as untyped notifications (UnknownNotification in C#, onUnknown in TypeScript, on_unknown in Python). A word Studio adds to an enum later reads as unknown rather than failing. See Versioning.

to open · ↑ ↓ to move · Esc to close