Control API
Typed methods and events
Every action is its own method and every event can be its own notification, each with a JSON Schema in the catalog. A client never passes an action's name as a parameter, and never reads a name out of a message to learn what happened.
Both are additions to velum/1, announced in the hello's features as typed_methods and typed_events. action.run and the event notification keep working exactly as before, so clients written for them don't change.
Each action is a method
Call an action by its id, with its parameters as the params:
→ { "jsonrpc": "2.0", "id": 3, "method": "scene.switch", "params": { "scene": "Just Chatting" } }
← { "jsonrpc": "2.0", "id": 3, "result": { "scene": "d73c5e2a-…", "name": "Just Chatting" } }- It runs exactly the same action as
action.runwith that id: the same checks, the same errors, the same result. - Leave
paramsout for an action that takes none:{"jsonrpc": "2.0", "id": 4, "method": "record.toggle"}. - Each action's
result_schemain the catalog is the shape of its result. Foraudio.volume:
"result_schema": {
"type": "object",
"properties": {
"input": { "type": "string", "format": "uuid", "description": "The source's id." },
"volume_db": { "type": ["number", "null"], "description": "The volume in dB; null is silent." },
"volume_percent": { "type": "number", "description": "The fader position, 0 to 100." }
},
"required": ["input", "volume_db", "volume_percent"],
"additionalProperties": false
}No action id is ever the name of one of the protocol's own methods (catalog.list, action.run, state.get, subscribe, unsubscribe, ping, pair.claim).
Each event is a notification
Ask for typed events when you subscribe:
→ { "jsonrpc": "2.0", "id": 4, "method": "subscribe", "params": { "topics": ["scenes", "chat", "activity"], "typed_events": true } }
← { "jsonrpc": "2.0", "id": 4, "result": { "topics": ["activity", "chat", "scenes"], "typed_events": true } }
← { "jsonrpc": "2.0", "method": "scene.changed", "params": { "scene": "d73c5e2a-…", "name": "Just Chatting" } }
← { "jsonrpc": "2.0", "method": "activity.raid", "params": { "eid": 812, "platform": "twitch", "kind": "raid", "text": "PixelFox is raiding with 30 viewers", "amount": { "value": 30, "unit": "viewers", "display": "30 viewers", "tier": null, "months": null }, … } }- The method is the event's id and the params are its data. Nothing else changes: an event still belongs to a topic, and you get it while you follow that topic.
typed_eventsbelongs to the connection and stays as set. A latersubscribethat leaves it out keeps it, and"typed_events": falsegoes back to theeventnotification. A connection gets each event one way, never both.- State keeps coming as
statenotifications, with the topic's name intopic. Each topic's schema is in the catalog undertopics. - Untyped, the activity events all arrive as one
eventnamedactivity. Typed, each kind is its own:activity.follow,activity.sub,activity.raidand the rest.
Every event, with its topic and its untyped name:
| Event | Topic | What happened | Untyped name |
|---|---|---|---|
scene.changed | scenes | A scene went on air. | scene.changed |
chat.message | chat | A chat message arrived on any platform, including messages sent from Studio, /me actions, channel notices, bot replies and announcements (kind says which). | chat.message |
chat.deleted | chat | A moderator (or a ban or timeout) removed chat messages. | chat.deleted |
chat.edited | chat | A chat message was edited. | chat.edited |
chat.cleared | chat | A platform's chat was cleared for everyone. | chat.cleared |
activity.follow | activity | Someone followed. | activity |
activity.sub | activity | Someone subscribed. | activity |
activity.resub | activity | Someone renewed their subscription and said so. | activity |
activity.gift_sub | activity | Someone gifted subscriptions (amount.value is how many, with unit subs). | activity |
activity.support | activity | Support with an amount: Velora Volts, Twitch bits, Kick KICKs, YouTube Super Chats. amount says how much and in what unit. | activity |
activity.redemption | activity | A channel-points (or Kick rewards) redemption. title is the reward's. | activity |
activity.raid | activity | Another channel raided this one. amount.value is how many viewers came, when the platform says. | activity |
activity.card | activity | A poll, prediction, giveaway, goal or clip, shown as a card. It may change in place later (activity.updated). | activity |
activity.updated | activity | An activity row changed in place, such as a poll's votes; same eid as before. | activity.updated |
record.paused | record | The recording was paused: nothing more goes in until it resumes. | record.paused |
record.resumed | record | The recording carries on in the same file, with no gap in its timeline. | record.resumed |
replay.started | replay | The replay buffer started keeping the last seconds of what's on air. | replay.started |
replay.stopped | replay | The replay buffer stopped; what it held was let go. | replay.stopped |
replay.saved | replay | A replay was saved to a file. | replay.saved |
media.changed | media | A media source started, paused, stopped, ended, went on or off air, or moved to another playlist item. | media.changed |
obs.custom_event | activity | An identified v5 client broadcast a custom event. | obs.custom_event |
web.changed | web | A web source's page failed to load (it's see-through on air and tried again by itself), failed for another reason, or loaded. | web.changed |
captions.sent | stream | Closed caption text went into the stream or recording (captions.send, obs-websocket's SendStreamCaption, or a plugin). | captions.sent |
Chat rows
chat.message and every activity event carry a chat row (the schema's title is ChatRow), so one renderer shows a message, a sub and a raid alike:
platformisvelora,twitch,kick,youtube,owncastorrumble.tsis Unix milliseconds.authoris{id, login, display, color, avatar, pronouns, roles, badges}, or null for a row nobody wrote (a poll).partsis the message in pieces, told apart byt:{t: "text", text},{t: "emote", code, url, animated, …},{t: "mention", login}or{t: "link", url}.amountis{value, unit, display, tier, months}: a number and its unit (bits,volts,kicks,subs,viewers, or a currency code such asUSD), never a string to read as money.stateis{t: "live"}or{t: "deleted", by}.metais anything else the platform sent that Studio doesn't describe yet. Don't rely on its shape.
Every field is in the reference under Shapes › ChatRow.
Reading the schemas
The schemas are JSON Schema (draft 2020-12), written so you can generate types from them:
- Objects list every field Studio sends, and
requirednames the ones that are always there. Studio may add fields later, but never removes or retypes one, so accept fields you don't know. titlenames a shape that appears in several places (ChatRow,DestinationHealth,StreamStatus). Use it as the type's name; the SDKs do.enumlists a field's words. A newer Studio may add words, so keep a way to hold one you don't know.oneOfof objects told apart by the constant intis a tagged union: a chat part, a chat row's state, a chat connection.- Maps keyed by an id are objects with only
additionalProperties. "type": [..., "null"]means the field can be null.
Error names
catalog.list lists every error code under errors, with a stable name to use for an enum or an exception type. See Errors and limits.
"errors": [
{ "code": -32700, "name": "parse_error", "description": "The message isn't JSON." },
{ "code": -32011, "name": "not_found", "description": "The scene, layer, source, effect, automation, collection or destination named doesn't exist." },
…
]Generating a client
The SDKs are generated from the catalog: one function per action, one type per event, one record per topic, one exception per error. To write a client in another language, read catalog.list from a running Studio and generate from it the same way. A notification whose method you don't know is an event newer than your client: ignore it, or handle it by its params.

