Developer The control API: commands

The control API: commands

Developer

An 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.

Contact support

Or write to support@interdirector.com. From InterDirector itself, Help → Report an Issue… sends the logs with your message. See the privacy notice for what the chat keeps.