Developer
Log in

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:

JSON-RPC
→ { "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.run with that id: the same checks, the same errors, the same result.
  • Leave params out for an action that takes none: {"jsonrpc": "2.0", "id": 4, "method": "record.toggle"}.
  • Each action's result_schema in the catalog is the shape of its result. For audio.volume:
JSON
"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:

JSON-RPC
→ { "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_events belongs to the connection and stays as set. A later subscribe that leaves it out keeps it, and "typed_events": false goes back to the event notification. A connection gets each event one way, never both.
  • State keeps coming as state notifications, with the topic's name in topic. Each topic's schema is in the catalog under topics.
  • Untyped, the activity events all arrive as one event named activity. Typed, each kind is its own: activity.follow, activity.sub, activity.raid and the rest.

Every event, with its topic and its untyped name:

EventTopicWhat happenedUntyped name
scene.changedscenesA scene went on air.scene.changed
chat.messagechatA 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.deletedchatA moderator (or a ban or timeout) removed chat messages.chat.deleted
chat.editedchatA chat message was edited.chat.edited
chat.clearedchatA platform's chat was cleared for everyone.chat.cleared
activity.followactivitySomeone followed.activity
activity.subactivitySomeone subscribed.activity
activity.resubactivitySomeone renewed their subscription and said so.activity
activity.gift_subactivitySomeone gifted subscriptions (amount.value is how many, with unit subs).activity
activity.supportactivitySupport with an amount: Velora Volts, Twitch bits, Kick KICKs, YouTube Super Chats. amount says how much and in what unit.activity
activity.redemptionactivityA channel-points (or Kick rewards) redemption. title is the reward's.activity
activity.raidactivityAnother channel raided this one. amount.value is how many viewers came, when the platform says.activity
activity.cardactivityA poll, prediction, giveaway, goal or clip, shown as a card. It may change in place later (activity.updated).activity
activity.updatedactivityAn activity row changed in place, such as a poll's votes; same eid as before.activity.updated
record.pausedrecordThe recording was paused: nothing more goes in until it resumes.record.paused
record.resumedrecordThe recording carries on in the same file, with no gap in its timeline.record.resumed
replay.startedreplayThe replay buffer started keeping the last seconds of what's on air.replay.started
replay.stoppedreplayThe replay buffer stopped; what it held was let go.replay.stopped
replay.savedreplayA replay was saved to a file.replay.saved
media.changedmediaA media source started, paused, stopped, ended, went on or off air, or moved to another playlist item.media.changed
obs.custom_eventactivityAn identified v5 client broadcast a custom event.obs.custom_event
web.changedwebA 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.sentstreamClosed 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:

  • platform is velora, twitch, kick, youtube, owncast or rumble. ts is Unix milliseconds.
  • author is {id, login, display, color, avatar, pronouns, roles, badges}, or null for a row nobody wrote (a poll).
  • parts is the message in pieces, told apart by t: {t: "text", text}, {t: "emote", code, url, animated, …}, {t: "mention", login} or {t: "link", url}.
  • amount is {value, unit, display, tier, months}: a number and its unit (bits, volts, kicks, subs, viewers, or a currency code such as USD), never a string to read as money.
  • state is {t: "live"} or {t: "deleted", by}.
  • meta is 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 required names the ones that are always there. Studio may add fields later, but never removes or retypes one, so accept fields you don't know.
  • title names a shape that appears in several places (ChatRow, DestinationHealth, StreamStatus). Use it as the type's name; the SDKs do.
  • enum lists a field's words. A newer Studio may add words, so keep a way to hold one you don't know.
  • oneOf of objects told apart by the constant in t is 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.

JSON
"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.

to open · ↑ ↓ to move · Esc to close