The control API: commands

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, at its fastest

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

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

Keep a WebSocket alive with {"type": "ping"}, answered {"type": "pong"}, every 10 seconds or so.