The control API: state

After hello, InterDirector sends the whole state as one message, and again whenever it changes, at most a few times a second. Over HTTP, GET /v2/state answers the same thing. Identities are UUIDs, as uppercase strings; use them to act on an input, a hotkey or a bucket, since a name can change.

{
  "type": "state",
  "protocol": 2,
  "show": "Finals",
  "inputs": [
    {"id": "…", "name": "Cam 1", "kind": "NDI", "picture": true, "sound": true,
     "overlay": false, "transport": false, "reload": false, "gainDecibels": -6.0,
     "color": "#2563EB", "idleColor": "#1D2844", "videoFX": ["blackAndWhite"]}
  ],
  "program": "…",
  "preview": "…",
  "programPicture": {"id": "50524F47-5241-4D00-8000-000000000000", "videoFX": ["vignette"]},
  "isTransitioning": false,
  "overlaysOnAir": ["…"],
  "muted": ["…"],
  "followingProgram": ["…"],
  "soloed": ["…"],
  "mutedMixes": ["busA"],
  "buses": [{"id": "busA", "letter": "A", "name": "Interpreter", "color": "#0F766E"}, {"id": "busB", "letter": "B", "name": "Bus B", "color": "#A16207"}],
  "layers": [{"id": "…", "input": "…", "member": "…", "name": "Comp · Cam 1", "visible": true}],
  "framingPresets": [{"id": "…", "number": 1, "name": "Close-up", "framed": ["…"]}],
  "outputs": {"streaming": true, "recording": false, "inputRecording": false, "ndi": false, "external": false},
  "autoDirector": false,
  "quickOverlay": false,
  "streamDestinations": [{"id": "…", "name": "YouTube", "isEnabled": true}],
  "dataSources": [
    {"id": "…", "name": "Scores", "columns": ["home", "away"], "rowCount": 12, "currentRow": 3,
     "values": {"home": "2", "away": "1"}}
  ],
  "replayPlaying": false,
  "replayBuckets": [{"id": "…", "name": "Goals"}],
  "selectedReplayBucket": "…",
  "fadedToBlack": false,
  "transformAnimations": true,
  "animatedInputs": ["…"],
  "hotkeys": [{"id": "…", "name": "Wide", "isActive": true, "color": "#2563EB", "idleColor": "#1D2844"}],
  "mixes": {"master": 0.0, "busA": -3.0, "busB": -12.0},
  "stream": {
    "elapsedSeconds": 1840, "bitrateKilobits": 4500, "targetKilobits": 6000, "measuredKilobits": 4420,
    "destinations": [{"id": "…", "name": "YouTube", "status": "publishing"}]
  },
  "recording": {"elapsedSeconds": 1200}
}

Inputs

inputs is in the Show’s order. The flags say which actions mean anything for each input:

• picture: it can be on Program and in Preview.
• sound: it can be muted, and gainDecibels is its fader.
• overlay: it can go on and off air as an overlay.
• transport: it plays: media files and images (play, pause, items, reshuffle).
• reload: it can be reloaded: a web page, an overlay, or a folder of images or media.

color and idleColor are the input’s label colour, chosen in its settings, and the same colour dimmed for a button at rest, as a hotkey’s are. Both are absent for an input without one.

videoFX lists the input’s Video FX that are switched on, by the names effect takes, in the order they are drawn. It is empty when none is on, and absent for an input without a picture.

programPicture is Program’s own picture: its id, which the Video FX commands take as inputID to switch Program’s effects, and its videoFX that are on, as an input’s are. Nothing else takes that id.

Switching and audio

• program and preview: the inputs there, absent when there is none. isTransitioning: a fade is running. transition: which button’s, fade (Fade 1), fade2 or dip, so a panel lights only that one; absent when none is running, or when the T-bar is being dragged.
• overlaysOnAir, muted, followingProgram, soloed: lists of inputs.
• mutedMixes: the muted mixes, master and any of busA to busH.
• layers: every Composite’s layers, each with its own id (what layerID takes), its Composite (input), the input it shows (member), its name (“Comp · Cam 1”) and whether it is visible.
• framingPresets: the Show’s framing presets, in order, each with its id (what presetID takes), its number (its place, what presetNumber takes), its name, and framed: the inputs and layers framed exactly as it is now, which is what lights a button that recalls it there.
• buses: the buses the Show uses, in letter order, each with its id (what mix takes), letter, name and color. Master is always there and is not listed.
• mixes: the faders in dB, a key per mix: master, busA and busB always, and any other bus the Show uses. Levels are faders, not meters.

Outputs

• outputs: whether each is running. external is an external display or Blackmagic output.
• streamDestinations: each destination, and whether it is switched on.
• stream, only while streaming: how long it has run; the bitrate the encoder is asked for now (bitrateKilobits, lowered on a slow network and raised again) and what it was set to (targetKilobits); what is actually leaving the Mac (measuredKilobits); and each destination’s status: connecting, publishing, reconnecting (with which attempt, and the reason it was lost) or stopped.
• recording, only while Program is being recorded: how long it has run.

stream and recording are refreshed at most once a second.

Data, replay and hotkeys

• dataSources: each source’s columns, how many rows (rowCount), the row on air counted from one (currentRow), and that row’s values by column, each cut at 200 characters.
• replayPlaying, replayBuckets (in the replay panel’s order) and selectedReplayBucket, when the Show has a replay input.
• autoDirector, quickOverlay, fadedToBlack: whether each is on.
• transformAnimations: whether the zoom and position animations are on, as the Animations button in the operator window is lit; animatedInputs: the sources whose own animation is on.
• hotkeys: the enabled hotkeys. isActive says whether one is lit, as its Stream Deck key would be; it is absent for a hotkey whose action happens rather than is. color and idleColor are its colours lit and unlit.