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
{
"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:
type | Value | Used by |
|---|---|---|
choice | One of the options | 46 |
text | Text | 33 |
integer | A whole number | 17 |
bool | true or false | 16 |
number | A number | 16 |
source | A source's id or name. Choices are in sources | 16 |
scene | A scene's id or name. Choices are in scenes | 14 |
audio_input | A source's id or name. Choices are in audio | 13 |
layer | A layer's id, or with scene, its number or the name of what it places. Choices are in layers | 9 |
destination | A destination's id. Choices are in destinations | 7 |
json | Any JSON value | 5 |
choice_list | Any of the options | 4 |
audio_group | An audio folder's or send's id or name. Choices are in audio_groups | 3 |
automation | An automation's id or name. Choices are in automations | 2 |
filter | An effect's id, or its name with owner. Choices are in filters | 2 |
graphics_card | . Choices are in gpus | 2 |
media_source | A media source's id or name. Choices are in media | 2 |
network_card | . Choices are in network | 2 |
text_list | A list of text | 2 |
collection | A scene collection's id or name. Choices are in collections | 1 |
text_source | A text source's id or name. Choices are in sources | 1 |
- A layer can be named by its id, or, together with a
sceneparameter, 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
ownerparameter. - 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.
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 |
stepmoves a number setting by that much, staying within its range: what a dial wants.fade_msfades a number setting to its new value over that many milliseconds, from what shows now.- Values in the
filterstopic 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.
{ "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.

