Control API
State and topics
Everything a control surface shows comes from a topic. Subscribe and Studio sends the topic's whole value at once, then pushes it again each time something in it changes.
How state arrives
→ { "jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": { "topics": ["audio"] } }
← { "jsonrpc": "2.0", "id": 1, "result": { "topics": ["audio"], "typed_events": false } }
← { "jsonrpc": "2.0", "method": "state", "params": { "topic": "audio", "value": { "items": { "4d54…": { "id": "4d54…", "name": "Mic", "muted": true, "volume_db": 0.0, "volume_percent": 100.0, "monitor": "off", "tracks": { "1": true, "2": false, "3": false, "4": false, "5": false, "6": false }, "visibility": "public", "group": null, "stem": false, "viewer_volume": 1.0, "viewer_muted": false, "slider_order": 0 } } } } }- Each
statenotification carries the topic's whole value. Replace what you had; there are no patches to apply. - Every topic is one JSON object. Things in Studio are listed in an
itemsmap keyed by their id, which stays the same for as long as the thing exists. - Nothing polls. A topic is pushed when it changes. The only regular messages are
stats, once a second, andmeters, ten times a second while you follow it. - Read once with
state.getwhen you don't need to follow a topic.
Each topic's full JSON Schema is in the catalog under topics, and in the reference.
The topics
| Topic | What it holds | When it's pushed |
|---|---|---|
scenes |
program (the scene on air), program_name, preview (studio mode's preview scene, or null), order, and items with each scene's own transition |
On every change |
layers |
Every layer of every scene: scene, index, kind, target, name, visible, locked, freeze on air, opacity (0 to 100), clipped (clip to the layer below), framings |
On every change |
filters |
Every effect: type, owner, index, enabled, and its settings now |
On every change |
audio |
Every source with sound: muted, volume_db, volume_percent, monitor, its six tracks, and what Velora viewers get from it over VELoQ: visibility, group (its folder or send), stem, viewer_volume and viewer_muted (where viewers' slider starts) and slider_order |
On every change |
sources |
Every source, with text for text sources and shows for Mirrors |
On every change |
source_settings |
Every source with settings a controller can change (an Aurora, and plugins' sources), each setting in the Inspector's order with its kind, value, range and choices | On every change, and when a plugin loads |
automations |
Each automation's name and whether it's on | On every change |
variables |
Each automation variable by name and its value: what {var:name} shows in a text layer and an automation's If can check |
On every change |
stream |
live, state, the destination, seconds, and viewers per platform |
When it changes |
record |
recording, paused, seconds (paused time isn't counted), dropped, encoder |
When it changes |
replay |
Whether the replay buffer runs, how much it keeps and holds, its memory, the encode it shares, the last replay saved | When it changes |
media |
Every video, sound and playlist source: state, on air, position, item | When one changes |
web |
Every web (browser) source: state (idle, loading, ok or failed), why a page failed (code, message, http_status) and when it's tried again |
When one fails or loads |
app_volume |
Every application-audio source: its app's own Windows volume and mute, or why it can't be read | When it changes (read about once a second) |
vcam |
Whether the virtual camera is on, and its device | When it changes |
destinations |
The selected destination, and each one's kind, platform, live and health | When it changes |
stats |
Frame rate, render counts, the live connection and the recording | Every second |
meters |
Audio levels per source, peak and RMS in dBFS | Ten times a second, while followed |
chat |
Each platform's connection state, where a message goes by default, and chat modes | When it changes |
activity |
The last 50 activity rows | With each activity event |
stream_info |
The title, category and tags | When it changes |
dynamic |
The category and title that Dynamic Sources match against | When either changes |
avatars |
Whether Avatars is on, and each lip-sync pairing: name, on or off, its state, its source and where it sends |
When a pairing changes |
collections |
The open scene collection and every collection Studio keeps | When one opens, or one is made or imported |
transitions |
The default transition, saved transitions, studio mode, the preview, and what's playing now | As it changes; progress every second while one plays |
update |
Studio's own updates: the state, what's on offer, download progress | When it changes; progress every second while downloading |
gpus |
Settings › Graphics cards: every card (name, vendor, kind, its encoder and whether it works), which one Studio draws on and encodes on | When anything in it changes |
network |
Settings › Advanced › Network cards: every card with its addresses and whether a stream could go out on it, the one chosen and its backup | When a card or the choice changes |
theme |
The active theme, resolved: id, name, appearance, revision and every token by name, so a remote can match Studio's look |
When the theme changes |
audio_groups |
The audio folders and sends: name, kind (folder or send), send_visibility and members |
On every change |
veloq |
What a VELoQ Go live to Velora would send now: its audio tracks in order, the viewer mixer as Velora's player draws it, sliders_used of slider_limit (8), the sources not_sent, has_stinger and where stinger sounds go (transitions) |
On every change |
Every field of every topic is in the topics reference.
Ids and names
- Scene, layer, source, effect and automation ids are UUIDs that stay the same while the thing exists. Store ids, not names: a name can change.
- Scenes and sources share one set of names, as in OBS. Names are matched exactly first, then ignoring case.
- Collection ids are the collection folder's name, such as
default. - Destination ids are
velora,platform:<id>, orwhip:<12 hex digits>. A WHIP server's id is derived from its address, so the address itself, which can contain a credential, never appears.
Media playback
state is idle (not opened yet), opening, playing, paused, stopped or ended. position_ms is how far into the item it was at at_ms (Unix milliseconds).
While state is playing and on_air is true, the position moves with the clock, so work it out as position_ms + (now − at_ms), capped at duration_ms. The topic is pushed only when something else happens (a pause, a seek, the next item, a loop back to the start), not as the position moves. item is the playing item's place in the playlist (0 is the first), and items how many there are (1 for a single file).
Off air, a media source waits where it was. With "start over when shown" on (the default), it plays from the top when it comes back.
Volume
Volume has two scales:
volume_dbis the gain in dB, wherenullmeans silent.volume_percentis the mixer fader's position from 0 to 100, on Studio's mixer scale: amplitude = (position / 100)³, so dB = 60 · log10(position / 100). 50 on the fader is about −18 dB.
Destinations
Destination health is {state, kbps, send_kbps, fps, loss, rtt_ms, reconnects, seconds, protocol, frames_published, frames_dropped, dropped}, where state is offline, connecting, live, reconnecting or refused, and protocol is how the stream is going out: whip, veloq, rtmps, rtmp or srt. Studio sends to one destination at a time, and only the live one shows numbers. Which fields each protocol fills is in Destinations and protocols; the velora destination's own protocol is always veloq (Studio sends to Velora over VELoQ), and its layers is how many qualities VELoQ sends (1 to 4; null is the default, 2).
The replay buffer
rides says which encode the buffer shares: recording, stream, or own (one Studio started for it, with the recording settings). A recording started while the buffer runs on its own joins that same encode. The buffer keeps whole GOPs, so a save starts on a keyframe.
Transitions
A transition is a type with its settings and how long it takes. The types are cut, fade, fade_to_color, slide, swipe, luma_wipe, move, effect (one of Studio's effects, such as swirl or page_curl), shader (a custom shader file) and stinger (a video played over both scenes). A scene can have its own transition into it, which plays instead of the default whenever that scene comes on air. playing lists one entry per canvas a transition is playing on, with progress from 0 to 1.
Secrets stay out
No topic ever carries a stream key, a platform token, or a WHIP address. The only token the API ever sends is a paired device's own, once, when it pairs.

