Commands

Commands are how you run an output: in, out, update, invoke and timer. Send them in a batch to Run commands or over the control WebSocket.

Each command is an object whose command says what it does. A batch runs in order, under one revision, and all or nothing: if one command can't run, none do.

JSON

{
  "commands": [
    { "command": "update", "component": "lower-third", "data": { "name": "Jane Doe" } },
    { "command": "in", "component": "lower-third" }
  ]
}

Components, layers, events, timers and instances are named by id. Data is named by each field's key. A value of null clears a key, so the field goes back to what it inherits or its default.

in

Puts a component on air, playing its In.

componentstringRequired

The component's id.

dataobject

Values to merge into the component's data first. The component keeps them after it goes off air.

instancestring

An instance of the component to show. Its data replaces the component's data. Send data or instance, not both.

JSON

{ "command": "in", "component": "lower-third", "instance": "4c1d…" }

If the component is already showing, in doesn't play In again. It just takes the new data, exactly as update would, and a change to one of its trigger fields plays Change.

out

Takes things off air, playing their Out. By default it acts on one component; scope widens it to a layer or everything.

scope"component" | "layer" | "root"

Defaults to "component".

componentstring

With the component scope: the component's id.

layerstring

With scope: "layer": the layer's id. Every component on it goes off air.

JSON

{ "command": "out", "component": "lower-third" }
{ "command": "out", "scope": "layer", "layer": "sponsors" }
{ "command": "out", "scope": "root" }

scope: "root" clears the output: everything goes off air. What comes off air keeps its data.

update

Merges values into data without changing what's on air. On a component that's showing, a change to one of its trigger fields plays its Change.

scope"component" | "layer" | "root"

Defaults to "component". "layer" updates a layer's data and "root" the composition's global data, which fields inherit from.

componentstring

With the component scope: the component's id.

layerstring

With scope: "layer": the layer's id.

dataobjectRequired

Values by field key: strings, numbers, booleans, or null to clear.

JSON

{ "command": "update", "scope": "root", "data": { "homeScore": 3, "awayScore": 1 } }

invoke

Plays one of a component's events, such as a custom Goal event.

componentstringRequired

The component's id.

eventstringRequired

The event's id.

JSON

{ "command": "invoke", "component": "score-bug", "event": "goal" }

timer

Starts, pauses, resets or sets a countdown or count-up field. Clocks and countdowns to a time follow the wall clock, so they can't be started or stopped.

timerstringRequired

The timer field's id.

action"start" | "pause" | "reset" | "set"Required

reset goes back to the timer's starting time. set moves it to the time you give.

msnumber

For set: the time in milliseconds.

timestring

For set: the time as text instead, such as "5:00".

JSON

{ "command": "timer", "timer": "clock", "action": "set", "time": "45:00" }
{ "command": "timer", "timer": "clock", "action": "start" }

The output runs every timer on its own clock, so every renderer shows the same time. A countdown can fire an event on a component when it reaches zero; set that up on the timer field in the editor.