The control API: commands
DeveloperAn action
{"type": "action", "verb": "cut", "inputID": "…", "parameters": {}, "withoutAsking": false, "requestID": "42"}
verb names the action. inputID is the input it acts on, for the actions that take one. parameters carries
anything else it needs.
Acting on an input (inputID required):
| Action | Parameters |
|---|---|
cut, setPreview |
— |
fade |
milliseconds (optional; the Show’s own fade when absent) |
overlayIn, overlayOut, toggleOverlay |
— |
play, pause, restart, nextItem, previousItem |
— |
goToItem |
item, counted from one |
mute, unmute, toggleMute |
— |
setGain |
decibels |
toggleFollowProgram, reloadInput, reshuffle, toggleSolo |
— |
toggleInputTransformAnimation |
— |
enableVideoEffect, disableVideoEffect, toggleVideoEffect |
effect: blackAndWhite, noiseReduction, blur, sharpen or vignette, with the input as inputID, or Program’s own with programPicture.id from the state. On and Off do nothing to an effect already so |
showCompositeLayer, hideCompositeLayer, toggleCompositeLayer |
layerID, one of the Composite’s layers, with the Composite as inputID. Show and Hide do nothing to a layer already shown or hidden |
recallFramingPreset |
presetID, or presetNumber counted from one, one of the framingPresets; layerID (optional), one of the Composite’s layers, with the Composite as inputID, to frame that layer; milliseconds (optional, 0 to 10000), the glide, a jump at 0 or when absent |
recallCameraPreset |
preset, 1 to 9, with an NDI camera that takes PTZ as inputID: the camera goes to the shot it keeps under that number; speed (optional), 0.1 to 1, its fastest without one |
setCameraZoom |
position, 0 widest to 1 furthest in, with an NDI camera as inputID; milliseconds (optional), 0 to 60000, a glide. A camera InterDirector has not told a zoom position, or one that has zoomed some other way since, goes straight there |
moveCameraToPosition |
pan and tilt, each -1 to 1, with an NDI camera as inputID |
cameraHome |
An NDI camera as inputID: to the centre |
nudgeCamera |
move: left, right, up, down, upLeft, upRight, downLeft, downRight, zoomIn or zoomOut; milliseconds, 50 to 10000; speed (optional), 0.1 to 1, with an NDI camera as inputID. It moves for that long, then stops |
setPhoneZoom |
zoom, the display zoom, 0.5 to 100, with an input InterDirector Cam sends to over SRT or RTMP as inputID; milliseconds (optional), 0 to 60000, a glide, or the phone’s own speed without one |
stepPhoneZoom |
percent, 1 to 100, positive in and negative out, with the phone’s input as inputID |
selectPhoneLens |
zoom, a back lens by its display zoom, with the phone’s input as inputID |
Acting on Program, an output, replay or a data source (no input):
| Action | Parameters |
|---|---|
cutPreview, dipPreview |
— |
fadePreview |
milliseconds (optional) |
fade2Preview |
— (the Show’s own second fade) |
toggleStreaming, toggleRecording, toggleInputRecording, toggleNDIOutput, addCutMark |
— |
stopTheShow |
— (InterDirector asks twice on the Mac before anything stops; withoutAsking is ignored) |
toggleFadeToBlack, toggleTransformAnimations |
— |
toggleAutoDirector, toggleQuickOverlay, toggleExternalOutput |
— |
setMixGain |
mix (master, or a bus, busA to busH), decibels |
muteMix, unmuteMix, toggleMixMute |
mix (master, or a bus, busA to busH). A muted bus is silent, its return to Master too; a muted Master silences the stream, the recording and every other output |
clearSolo |
— |
toggleStreamDestination |
destinationID |
playReplayBucket |
bucketID (optional; the selected bucket when absent) |
playAllReplayBuckets |
— |
playReplayClip, previousReplayClip, nextReplayClip, stopReplay |
— |
selectReplayBucket |
bucketID |
nextReplayBucket, previousReplayBucket |
— |
clearReplayBucket |
bucketID (optional) |
captureReplayClip |
seconds (optional; the Show’s own length when absent) |
deleteLastReplayClip, deleteSelectedReplayClip |
— |
nextDataRow, previousDataRow, readDataSource |
dataSourceID |
goToDataRow |
dataSourceID, row (counted from one) |
selectDataRow |
dataSourceID, key |
Setting an overlay’s fields
{"type": "action", "verb": "setOverlayFields", "inputID": "…",
"parameters": {"fields": {"home": 2, "away": 1, "title": "Second half"}}, "requestID": "44"}
Sets the fields of the Overlay input named as inputID, by the ids its overlayFields in the state give them: one
or several at once, shown together, so the graphic never shows half an update. They are saved in the Show, just as if
they were typed in the overlay’s settings.
| Kind | Value |
|---|---|
text |
a string |
choice |
a string, one of its options |
number |
a number, within its minimum and maximum |
color |
a string of six or eight hex digits, #00FF00 or #00FF0080 |
boolean |
true or false |
An image field can’t be set this way, and neither can a field whose value comes from a data source (bound in the
state): change the data instead. If any field can’t be set, none is, and the refusal names it:
{"type": "refused", "reason": "wrongValue", "field": "home", "requestID": "44"}.
A hotkey
{"type": "press", "mappingID": "…", "withoutAsking": false, "requestID": "43"}
Runs the hotkey exactly as if its key were pressed, every step of it.
Moving a camera while a button is held
{"type": "ptz", "inputID": "…", "move": "left", "speed": 0.5, "requestID": "44"}
Pans, tilts or zooms an NDI camera that takes PTZ, from the moment this arrives until {"type": "ptz", "inputID": "…", "move": "stop"} does: send the move as your button goes down and the stop as it comes up. move is left,
right, up, down, upLeft, upRight, downLeft, downRight, zoomIn, zoomOut, home (back to the centre,
nothing to stop) or stop; speed is 0.1 to 1. If your connection closes with a camera moving, InterDirector stops
it. Over the socket only, not over HTTP.
What asks first
Some actions ask on the Mac before they run: stopping the stream, a recording or input recording, deleting a replay
clip, clearing a bucket that has clips, and switching a destination off while streaming. Sent from the API, they ask
the same question on the Mac, unless the command says "withoutAsking": true.
Answers
Give a command a requestID, any string of yours, and InterDirector answers it:
{"type": "done", "requestID": "42"}once it has been carried out (or handed to the Mac’s question);{"type": "refused", "reason": "stale", "requestID": "42"}if it could not be, followed by the state.
Without a requestID, a command is answered only when it is refused. Either way, what it did shows in the state.
| Refused because | Meaning |
|---|---|
stale |
an input, hotkey or bucket the Show no longer has, or an action that means nothing for that input |
unknown |
not a message this version knows |
signIn |
from another computer: not signed in yet |
session |
from another computer: the session has ended; sign in again |
password |
from another computer: a wrong password; retryAfter says how many seconds to wait |
noSuchField |
setOverlayFields: the overlay has no field with that id; field names it |
wrongValue |
setOverlayFields: not a value that field can hold; field names it |
boundToData |
setOverlayFields: that field’s value comes from a data source; field names it |
notSettable |
setOverlayFields: an image field, which can’t be set from outside; field names it |
Keep a WebSocket alive with {"type": "ping"}, answered {"type": "pong"}, every 10 seconds or so.