Developer
Log in

Control API

The catalog

catalog.list describes every action Studio can run, in enough detail to build a picker, a settings form and a live key without hard-coding anything.

Why a catalog

A control surface shouldn't keep its own list of what Studio can do. It should ask. The catalog gives each action a stable id, plain-English words ready to show, typed parameters (as a list for forms and as JSON Schema for code generators), the shape of its result, where its live state comes from, and the controls it suits. When Studio gains an action, every catalog-driven client gains it too, often without an update.

Studio lists only actions it can do today. This site's reference is generated from the same catalog.

An action

JSON
{
  "id": "audio.mute",
  "name": "Mute",
  "description": "Mutes, unmutes or toggles a source's sound.",
  "group": "Audio",
  "params": [
    { "name": "input", "type": "audio_input", "required": true, "description": "The source with sound.", "choices": "audio" },
    { "name": "mode", "type": "choice", "options": ["mute", "unmute", "toggle"], "required": false, "default": "toggle", "description": "Mute, unmute, or toggle." }
  ],
  "params_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "input": { "type": "string", "minLength": 1, "description": "The source with sound. Give its id or name." },
      "mode": { "type": "string", "enum": ["mute", "unmute", "toggle"], "default": "toggle", "description": "Mute, unmute, or toggle." }
    },
    "required": ["input"],
    "additionalProperties": false
  },
  "state": {
    "topic": "audio", "map": "items", "key_param": "input", "field": "muted", "shape": "bool",
    "description": "On while muted.",
    "schema": { "type": "boolean", "description": "On while muted." }
  },
  "controllers": ["key"],
  "destructive": false
}
Field Meaning
id Stable forever, such as scene.switch. People's keys and buttons store it.
name, description Plain English, ready to show.
group The heading a picker lists it under: Scenes, Audio, Output and so on.
params The parameters as a list, for building a settings form: name, type, required, default, description, plus options (choices), min, max and unit (numbers), max_length (text) and choices (the topic that lists the possible values).
params_schema The same parameters as a JSON Schema object, for code generators and validation.
result_schema The shape of the action's result.
state Where the action's live state comes from, with its own schema. See Live state.
controllers What suits it: key (a press), dial (a turn or a slide), display (it shows a value).
destructive It ends something viewers see. It needs explicit parameters, and clients should guard it, for example with a long press.
scope What a paired device needs to run it: control, chat, broadcast or manage. See Scopes.

Parameter types

A parameter's type says what kind of value it takes, and for anything in Studio, which topic lists the choices. Every type in the current catalog, and how many parameters use it:

typeValueUsed by
choiceOne of the options46
textText33
integerA whole number17
booltrue or false16
numberA number16
sourceA source's id or name. Choices are in sources16
sceneA scene's id or name. Choices are in scenes14
audio_inputA source's id or name. Choices are in audio13
layerA layer's id, or with scene, its number or the name of what it places. Choices are in layers9
destinationA destination's id. Choices are in destinations7
jsonAny JSON value5
choice_listAny of the options4
audio_groupAn audio folder's or send's id or name. Choices are in audio_groups3
automationAn automation's id or name. Choices are in automations2
filterAn effect's id, or its name with owner. Choices are in filters2
graphics_card. Choices are in gpus2
media_sourceA media source's id or name. Choices are in media2
network_card. Choices are in network2
text_listA list of text2
collectionA scene collection's id or name. Choices are in collections1
text_sourceA text source's id or name. Choices are in sources1
  • A layer can be named by its id, or, together with a scene parameter, by its per-scene number (scene_item_id) or the name of the source or scene it places.
  • An effect can be named by its id, or by its name together with an owner parameter.
  • Names are matched exactly first, then ignoring case. Ids are always safer, because a name can change.
  • Unknown parameters are refused, not ignored, so a misspelling is caught at once.

Live state

state tells a client where an action's value lives, using the action's own parameters, so a key can light up without any per-action code:

Rule The value is Example
map + key_param + field topic[map][params[key_param]][field] audio.mute: audio.items[input].muted
map + key_param topic[map][params[key_param]] chat.mode: chat.modes[platform]
… + index_param that, then [String(params[index_param])] audio.track with {"input": "Mic", "track": 2}: audio.items[input].tracks["2"]
field + equals_param topic[field] == params[equals_param] scene.switch lights while scenes.program is its scene
field alone topic[field] record.toggle: record.recording
neither the whole topic stats.show: the stats topic

shape is the value's JSON type: bool, number, string, object, or any (an effect setting, which holds whatever that setting holds).

Lookups by key_param use ids. If you let people pick by name, keep the id from the topic and store that.

TypeScriptA key's live value, from the rule alone
function liveValue(action, params, topics) {
  const st = action.state;
  if (!st) return undefined;
  const topic = topics[st.topic];
  if (!topic) return undefined;
  if (st.map) {
    let v = topic[st.map]?.[params[st.key_param]];
    if (st.field) v = v?.[st.field];
    if (st.index_param) v = v?.[String(params[st.index_param])];
    return v;
  }
  if (st.equals_param) return topic[st.field] === params[st.equals_param];
  return st.field ? topic[st.field] : topic;
}

Destructive actions

Actions marked destructive end something viewers see. Studio refuses stream.stop and chat.clear without "confirm": true, and chat.moderate takes no defaults at all. Guard them on your side too: the Stream Deck plugin needs a long press, and Companion's presets put them on a two-second hold.

Effect settings

filter.set changes one setting of an effect. Each effect type's settings are in the catalog under filter_settings, one JSON Schema per type, keyed by the type (such as velum.filter.chroma_key):

Kind In the schema value
Number "type": "number" with minimum, maximum and sometimes x-unit (px, dB, ms, s, °) A number in range. Fractions such as opacity go from 0 to 1.
On or off "type": "boolean" true or false
Color "type": "string", "x-kind": "color" "#rrggbb" or "#rrggbbaa"
Choice "type": "string" with enum One of the words
File "type": "string", "x-kind": "path" A full path to a file on the computer Studio runs on
  • step moves a number setting by that much, staying within its range: what a dial wants.
  • fade_ms fades a number setting to its new value over that many milliseconds, from what shows now.
  • Values in the filters topic are what the effect runs with: a setting that was never changed shows its default, and only the settings that apply now are shown.
  • A Shader effect's settings are its shader's own, so its schema allows other properties for the settings a shader file brings.
JSON-RPCA dial that tunes a green screen
{ "jsonrpc": "2.0", "id": 9, "method": "filter.set", "params": { "filter": "Green screen", "owner": "Camera", "setting": "similarity", "step": 0.02 } }

Every type and setting is in the effect settings reference.

to open · ↑ ↓ to move · Esc to close