Skip to main content

Demon Switcher control API

Reference for software that drives Demon Switcher (automation, PCR control, Companion-style panels; a Bitfocus Companion module is in companion/). Everything here works the same over every transport; the operator's UI uses the same command bus, so API changes show in the UI at once and vice versa.

Written against Demon Switcher 0.1 (production format 5). Examples are real responses captured from a running instance.


1. Connecting​

TransportDefaultBest for
TCP textport 7892Automation: one command per line, one reply per line, plus pushed tally/state after SUBSCRIBE. Closest to vMix's TCP API.
HTTP RESTport 7890One-off commands, polling state, adding inputs.
WebSocketws://host:7890/api/wsBrowser/JS clients: pushed state + tally, send commands on the same socket.
OSC (UDP)port 7891Lighting/sound desks, TouchOSC. Fire-and-forget (no replies).
  • Access (0.38): from another machine you need an API key (or, for the web console, a login). Keys are made on the switcher (Switcher Settings → Access → API keys), one per device, each with a role. The switcher's own computer is trusted (no key) unless that's turned off.
    • HTTP: Authorization: Bearer <key> (or ?key=<key> for devices that can only open a URL — less private: URLs end up in logs).
    • WebSocket: the same header, or the web console's login cookie.
    • TCP: send AUTH <key> first (reply OK <role>); before that every line gets ERROR … send AUTH <key> first.
    • OSC: send /ds/auth <key> first; OSC from that address is then accepted for an hour after its last message.
    • Roles: Viewer — STATE, TALLY, INPUTS, OUTPUTS, SUBSCRIBE, pictures. Operator — running the show: switching, transitions, supers, audio levels and processing, clip transport, replay, PTZ moves and presets, take buttons, scripts, triggers, ON AIR, REC ALL, starting / stopping existing outputs, delay dumps. Admin — everything, setup included: adding / removing / renaming inputs and outputs, routing, productions (NEW / OPEN / SAVE), multiviews, buses, composites' layout, vertical links, PTZ camera connections, loading files into players, the delay on / off. A command beyond the role answers not allowed: that needs Operator (key … is Viewer).
    • Refused: HTTP 401 ({"error", "login": true, "setup"}), 429 after repeated failures from one address (10 in five minutes: five minutes off). Until the switcher has its first admin user, only its own computer gets in ("setup": true).
    • WHIP guests (WebRTC guest inputs) send Authorization: Bearer <guest key> — a one-time key from Access → Guest keys (OBS: Bearer token) — or an Operator / Admin API key.
  • By default the servers listen on all interfaces; the operator can restrict this. Switcher command-line flags: --api-bind <addr> (e.g. 127.0.0.1), --http-port N, --tcp-port N, --osc-port N (0 disables one), --no-api. Keys and passwords travel unencrypted (no HTTPS yet): use a closed show network, not public Wi-Fi.
  • Commands take effect on the next video frame (20 ms at 50p).
  • Recommended for a PCR automation client: one persistent TCP connection, send SUBSCRIBE once, then send commands on it. Treat any line that starts with TALLY or STATE as a push; every other line is the reply to your oldest unanswered command (replies come back in order).

2. Addressing inputs — read this first​

Inputs are addressed by their stable ID or by their name — never by number.

  • Every input has a 12-character ID (e.g. 3qwxSSU48QB9), shown as id in INPUTS / STATE and in the operator UI (input ⚙ → Control ID). It is saved with the production, so it survives restarts, reordering and re-categorising. Store IDs in your rundown, not numbers.
  • A name works too (case-insensitive): PREVIEW "Camera 1". Quote names with spaces. Names can be changed by the operator; IDs can't.
  • Numbers are rejected: PREVIEW 2 → ERROR inputs are addressed by their ID or name, not by number ("2"); see INPUTS for the IDs. (Input numbers in the UI change whenever the operator reorders inputs.) The number field in INPUTS is display order only.
  • Two built-in sources need no ID: BLACK (or BLK) and BARS.
  • Everywhere the API sends an input reference (tally, switcher state, outputs) it uses the ID.

Typical start-up: connect → INPUTS → build a name→ID map → use IDs from then on.

3. Text commands​

Used over TCP, POST /api/text (one or more lines in the body; the reply is the last line's), WebSocket (a text frame that isn't JSON), and OSC (/ds/preview "Camera 1" = PREVIEW "Camera 1"; path segments become words, arguments are appended; /ds is optional).

Rules: verbs are case-insensitive; "double quotes" group words; blank lines and lines starting // are ignored. <in> = input ID or name; <src> = an input, BLACK or BARS.

Replies: OK · ERROR <message> · or one line of JSON for queries/ADD. (HTTP: {"ok":true}, {"error":"…"} with status 400, or the JSON.)

Switching​

CommandDoes
PREVIEW <src> (PVW)Put a source on preview.
PROGRAM <src> (PGM)Hot-cut a source straight to program (preview unchanged).
CUTSwap program and preview instantly.
AUTO (TAKE)Run the current transition (see TRANSITION).
FADEMix preview → program over the FADE button's duration (doesn't change the current transition).
MORPH (or MERGE)Morph preview → program over the MORPH button's duration (see below).
FTBToggle fade to black.
TBAR <0..1>Manual T-bar position; reaching 1 completes the transition.
BUTTON <1–6>Press one of the operator's six custom take buttons (stingers, preset commands — whatever the operator set up).

Morph: anything that appears in both pictures moves/resizes into its new place (a box inside a composite "2-box" grows to full frame, or shrinks back); everything else cross-fades.

Transitions (what AUTO / the T-bar run)​

Command
TRANSITION mix [frames]Also dip, wipe (horizontal), vwipe, dwipe (diagonal), iris, box, merge.
TRANSITION stinger <clip-in> [frames] [cut]A stinger clip input; cut = the frame where program switches under the clip (default: half way).
DURATION <frames>Change the current transition's length.

Durations are in frames of the production's frame rate, not milliseconds. Read format from STATE (e.g. "1080p50" → 50 frames/s; 1080p59.94, 1080p25, …). 1 s at 50p = 50.

Supers (overlays over program, kept through cuts and transitions)​

SUPER <1–10> … — as many as the edition has (S 1, M 4, L 5, XL 10).

Action
SOURCE <src>What the super shows.
ON / OFF / TOGGLEFade on / off over the super's fade time.
CUTToggle instantly.
PIP full|tl|tr|bl|brFull frame or a corner picture-in-picture.
OPACITY <0..1> · FADE <frames>
CHROMA green|blue|#RRGGBB|off [sim] [smooth] [spill]Chroma key on this super.
ENABLE / DISABLEUse this super in the production or not (Production Settings → DSK / Supers). A disabled super has no row on the switcher and can't go on air (ON / TOGGLE / CUT answer an error); disabling one takes it off air.

SUPERS on|off|toggle — all of them together (on: those enabled, with a source).

Audio​

Command
GAIN <in> <dB>e.g. GAIN "Camera 1" -6. 0 = unity.
MUTE <in> [on|off|toggle]No argument = toggle.
AFV <in> on|offAudio follows video.
PAN <in> <-1..1>
MASTER <dB>Master output gain.

Processing (each input, and MASTER): low / high cut, four EQ bands, gate, compressor, limiter — in that order; inputs before their fader, master after it (so its limiter protects every output). Each command changes only what it names.

Command
HPF <in|MASTER> <Hz>|off · LPF <in|MASTER> <Hz>|offLow cut / high cut (12 dB/octave).
EQ <in|MASTER> <band 1–4> <Hz> <dB> [Q] [peak|lowshelf|highshelf] · EQ … <band> offA parametric band (default bands: low shelf 120 Hz, peak 500 Hz, peak 2.5 kHz, high shelf 8 kHz).
GATE <in|MASTER> on|off [threshold dB] [range dB]Below the threshold, down by the range.
COMPRESSOR <in|MASTER> on|off [threshold] [ratio] [attack ms] [release ms] [make-up dB](COMP means composite.)
LIMIT <in|MASTER> on|off [ceiling dB]1.5 ms look-ahead: nothing gets past the ceiling.
FX <in|MASTER> resetAll processing off, back to defaults.

Each input's settings (audio.dsp) are in INPUTS / STATE; master's in STATE.audio.master_dsp; gain reduction (gr_db, master_gr_db) in GET /api/audio.

Inputs​

CommandReply
ADD <spec>{"id":"<new ID>"} — see specs below.
REMOVE <in>
RENAME <in> <new name>
MOVE <in> <position>1 = first.
PLAYMODE <in> take|backgroundClips: wait cued and play when taken to program, or play all the time.
LOOP <in> on|offClips.
CONTROL <in> <cmd>Clips: play, pause, restart. HTML graphics templates: play, stop, next, update {"f0":"Jane Doe","f1":"Reporter"} (CasparCG-style template data). OGraf graphics: play (playAction, the next step), stop, update {…} (updateAction, the manifest's fields), custom <id> [{…}] (a custom action).
KEY <in> green|blue|#RRGGBB|off [sim] [smooth] [spill]Chroma key on the input itself (applies everywhere it's shown).

Input specs for ADD:

SpecSource
/path/clip.mp4, file:///…Video/still file (clips start cued: PLAYMODE take).
stinger:/path/clip.movA stinger clip (alpha kept).
ndi:MACHINE (Source Name)NDI / NDI|HX source.
omt:HOST (Name)Open Media Transport source.
srt://host:port, rtmp://…, rtsp://…, udp://…, https://…/x.m3u8Network streams (reconnect automatically).
st2110:<sdp>[;<sdp>…][?iface=<if>][&latency=<ms>]SMPTE ST 2110-20 video / -30 audio, as the SDPs describe (each a file path, or b64: + the SDP's text, URL-safe base64, so a production carries it). iface: the interface to join multicast on; latency: how long after capture frames are shown (default 40).
https://youtube.com/watch?v=…Online video (needs yt-dlp on the switcher machine).
whep:https://…WebRTC: play a WHEP stream.
whip:<port>, whip:<address>:<port>WebRTC: a WHIP server guests send to (http://<this machine>:<port>/whip/endpoint).
html:/path/template.html, html:https://…HTML graphics (CEF).
ograf:/path/graphic (its folder), /path/x.ograf.jsonAn EBU OGraf graphic (in the HTML engine).
device:<name>, v4l2:/dev/videoN, decklink:NCapture devices.
compositeAn empty composite input (layers are set by the operator).
syn:bars, syn:nv12:50, syn:lowerthirdTest signals.

Composites (boxes)​

A composite is an input made of layers (bottom first): e.g. a "2 Box" = background + Player A box + Player B box. The operator designs the boxes in the composite's editor; automation usually just swaps sources.

Command
COMPOSITE <in> LAYER <n> SOURCE <src>What layer n (1 = bottom) shows.
COMPOSITE <in> LAYER <n> PIP full|left|right|tl|tr|bl|brPlacement preset (left/right = the middle half of the source in that half of the frame).
COMPOSITE <in> LAYER <n> POSITION <x> <y> [scale]Centre (0..1 of the frame) and size (1 = full frame).
COMPOSITE <in> LAYER <n> CROP <l> <t> <r> <b>Fractions of the source.
COMPOSITE <in> LAYER <n> OPACITY <0..1> · … LAYER <n> REMOVE
COMPOSITE <in> LAYER ADD <src> · COMPOSITE <in> CLEARAdd a top layer · remove all layers.

A composite can't contain another composite. Its layers are in STATE (inputs[].layers, below). Tally includes the inputs in a composite that's on air, and the MORPH transition animates boxes between composites.

Virtual sets (Demon Labs, 0.43)​

A virtual set is a composite (background, keyed presenters, foreground) with shots that a virtual camera moves between (Switcher Settings → Demon Labs → VIRTUAL SETS; made with + ADD INPUT → Virtual set).

Command
SHOT <set> <n|name>The camera to shot n (1 = the first) or the one named so (any case), over the set's move time. Operator.
CAMERA <set> <x> <y> <zoom> [frames]The camera to look at (x, y) — fractions of the set — magnified zoom (1–4) times, over frames (default: the set's move time; 0: cut). Kept inside the set. Operator.

Its shots are in STATE (inputs[].vset). A custom button or trigger can run SHOT lines too.

Clip players (video files and lists)​

Any file input is a player with a list (a plain file is a list of one). The player plays the current item from its IN point to its OUT point and stops there by itself, on the frame — the client doesn't need to watch the position to stop it.

Command
LIST <in> LOAD <path> [<path> …]Replace the list (absolute paths on the switcher machine; quote paths with spaces) and load item 1.
LIST <in> ADD <path> · LIST <in> REMOVE <n>Append · remove an item that isn't loaded.
LIST <in> SELECT <n> [IN <t>] [OUT <t>]Load item n (1 = first) with those in/out points.
LIST <in> MARK [IN <t>] [OUT <t>]Change the loaded item's points (omitted = none).
SEEK <in> <t>Jump to a time in the loaded file.
CONTROL <in> play / pause / restartrestart = back to the IN point.
PLAYMODE <in> take|background · LOOP <in> on|offSee below.

Times (<t>): seconds 12.5, mm:ss or hh:mm:ss[.fff], timecode hh:mm:ss:ff, or frames 250f — frames at the production frame rate (STATE.format). Times are positions in the file (an IN of 10 and OUT of 25 plays the file's 0:10–0:25).

Behaviour:

  • PLAYMODE take (the default for clips): the player waits cued — held on its IN frame — and plays when taken to program (cut, transition, or a super). When it leaves program it rewinds to IN and waits again. background: plays all the time.
  • At the OUT point (or the end) it holds the last frame and reports ENDED; with LOOP on it loops between IN and OUT instead.
  • Changing item, points or position on a cued player keeps it cued on the new frame (the reply comes once that frame is on screen, so a following take shows the right picture). On a player that's on air and playing, it jumps and carries on.
  • The usual flow per story: LIST p SELECT 3 IN 00:00:04:12 OUT 00:00:31:00 while p is off air → take p to program → the clip plays and stops at its OUT point; CLIP pushes report ENDED → cut away (p re-cues itself).

Multiviews​

Command
MULTIVIEW ADD [name]A new multiview (2+8, AUTO cells).
MULTIVIEW <n> LAYOUT 2+8|1+5|2x2|3x3|4x4Change layout (assignments kept where cells remain).
MULTIVIEW <n> CELL <c> PGM|PVW|AUTO|EMPTY|<in>What cell c (1-based, left to right, top to bottom) shows. AUTO = the next input not shown in another cell.
MULTIVIEW <n> METERS on|offAudio meters on the tiles (on by default): each input's own level, the master mix on PROGRAM.
MULTIVIEW <n> NAME <name> · MULTIVIEW <n> REMOVERemoving one renumbers later multiviews (outputs follow).

Multiviews are in STATE.multiviews: [{"name":"Studio wall","layout":"Grid3","cells":["Program",{"Input":"<ID>"},"Preview","Auto",…,"Empty"]}] (layouts: TwoPlusEight, OnePlusFive, Grid2, Grid3, Grid4). Route them with OUTPUT ROUTE <id> MV2 / OUTPUT multiview2 <spec> (MV = MV1).

Audio buses (mixes for outputs)​

Besides master there are aux buses (up to 16). Every bus carries its inputs at their fader level, exactly as master hears them (fader, mute, audio-follow-video) — there are no separate send levels. A bus is either selected inputs (just the inputs put on it) or a mix-minus (every input on master except those left out, plus any added — e.g. a remote guest's return without their own voice, with talkback). <bus> = its number (1 = first aux bus) or name.

Command
BUS ADD [name]A selected-inputs bus.
BUS ADD MIXMINUS <in> [<in> …]A mix-minus leaving those inputs out (named "Mix-minus ").
BUS <bus> GAIN <dB> · BUS <bus> MUTE [on|off|toggle] · BUS <bus> NAME <name>
BUS <bus> EXCLUDE <in> …Change which inputs a mix-minus leaves out.
BUS <bus> REMOVELater buses move down; outputs follow; outputs on it go silent.
SEND <in> <bus> on|offThe input on / off that bus (mix-minus: in / out of that return; an input not on master can be put in — e.g. talkback). A number is accepted too: > 0 = on.
SEND <in> MASTER on|offWhether the input feeds master (off: heard only on buses).
OUTPUT AUDIO <id> MASTER|<bus>An output's audio (from its next start).

STATE.audio.buses: [{"name":"Guest return","kind":{"mix_minus":["<ID left out>"],"plus":["<ID added>"]},"gain_db":0,"mute":false}, {"name":"Aux 1","kind":"sends",…}] ("sends" = selected inputs: the inputs whose audio.sends[n] > 0); each input's audio.master says whether it feeds master; GET /api/audio → aux: [{"name", "meter"}]. An output's config.audio is "Master" or {"Aux": n} (0-based).

Outputs, productions​

Command
OUTPUTSList (JSON, below). Output IDs are small integers.
OUTPUT START <id> / OUTPUT STOP <id> / OUTPUT REMOVE <id>Start/stop the operator's configured outputs (recordings, streams, NDI, screens).
OUTPUT ROUTE <id> PGM|PVW|MV|<in>Re-route an output live (a running stream/recording carries on).
OUTPUT AUTO <id> on|offStart it automatically whenever the production opens (saved with it).
OUTPUT [program|preview|multiview|iso <in>] <spec>Add and start a new output: ndi:NAME, omt:NAME, srt://…, rtmp://…/KEY, /path/file.mkv, decklink:N, screen[:MONITOR]. Recordings: .mkv / .mp4 = H.264, .mov = ProRes 422, .mxf = DNxHR HQ; whep:[address:]<port> = a WHEP server (viewers play http://<this machine>:<port>/whep/endpoint; give it a mix-minus bus with OUTPUT AUDIO); whip:https://…[#token] = push to a WHIP server; st2110:<video addr:port>[,<audio addr:port>][?iface=<interface>] = SMPTE ST 2110-20 (10-bit 4:2:2) + -30 (L24 stereo, 1 ms) to multicast groups or unicast — its SDP from GET /api/outputs/<id>/sdp (`?essence=video
NEW · OPEN <path.pcrproj> · SAVE [path]Productions.
RECORD start|stop|toggleREC ALL: programme and every input (or the chosen set) each to its own file, all from the same frame. STATE.recording: its folder, files and seconds (null when not recording).
ONAIR on|off|toggleThe ON AIR light in the Production box (when Switcher Settings sets it to MANUAL or API; AUTOMATIC follows the outputs' tally). STATE.on_air says whether it's lit.

Sub-mixes and the profanity delay​

A sub-mix (ADD mix, at most 4) is an input with its own programme, preview and transition — for studio screens or an alternative feed. It's an input like any other (on the main switcher, in multiviews, as an output's source) and has its own audio bus: its programme's inputs at their fader level, following its video. An output takes that sound with OUTPUT AUDIO <id> <sub-mix>.

The profanity delay is a fifth, separate sub-mix ("Profanity Delay"): the programme and master sound, N seconds late, with dumps that cover what was just heard before it airs. Point an output (e.g. NDI) at it, with its audio.

Command
(inputs) #nAnywhere an input is named: whatever is n-th on the buses (1-based) — what a control surface's "PGM 3" means.
MIX <in> PROGRAM|PREVIEW <src> · MIX <in> CUT|AUTO · MIX <in> TBAR <v> · MIX <in> TRANSITION <kind> [frames]Switch a sub-mix — the main switcher's words.
DELAY ON [seconds] · DELAY OFFThe profanity delay (it records the programme; dumps work once it has filled).
DELAY COVER SILENT · DELAY COVER AUDIO <in> · DELAY COVER CLIP <in>What dumps cover with: the delayed picture without sound, with another input's sound (e.g. birdsong), or a clip (covers at most its length). Changing it restarts the delay.
DELAY DUMP <seconds> · DELAY DUMP [ALL]Cover what was live over the last N seconds (or everything in the delay); it airs N seconds before the end of the delay, cut on exact frames. Dumps that overlap join.
DELAY CANCELTake back the last dump still to air (one on air ends now).

Replay​

Up to 8 inputs are recorded continuously (a rolling buffer, set in Switcher Settings → Replay), all on the same frames, so an event — a stretch of switcher time — has every angle. Two channels, Replay A (ADD replay) and Replay B (ADD replay:b, L and up), one of each per switcher, play events at any speed, each with its own transport (position, speed, angle, event). Event numbers are small integers, shown in the REPLAY tab; angles are numbered 1–8 in the order inputs started recording.

Every command takes an optional channel straight after REPLAY: REPLAY B PLAY 3, REPLAY B SPEED 50. Without one it means A. Marks, events, the reel, recording and exports are shared by both channels (a mark or LAST made on B takes B's angle and frame).

Command
REPLAY RECORD <in> [on|off]Record an input (on when left out). off discards its recording. At most 8.
REPLAY IN · REPLAY OUTMark in / out: OUT makes an event. Live, a mark is the newest frame; while a replay is cued or playing, the frame shown (an event from within a replay).
REPLAY LAST [seconds]An event of the last N seconds (default 10), ending now.
REPLAY PLAY [event]Play an event from its in point; without one, carry on (or, when live, play from the mark in).
REPLAY CUE <event>Load an event paused on its in point.
REPLAY PAUSE · REPLAY TOGGLEPause (from live: freeze the frame on screen) · play/pause.
REPLAY SPEED <percent>e.g. 50 = half speed, -100 = reverse. Kept across events. Sound plays at 100% forwards only.
REPLAY ANGLE <n> · REPLAY ANGLE NEXTChange angle — on the same frame, while playing.
REPLAY STEP [frames]Step (negative: back); pauses.
REPLAY LIVEBack to showing the chosen angle live.
REPLAY ANGLESET <event> · REPLAY DELETE <event>Give an event the current angle · delete it.
REPLAY REEL ADD <event> · REPLAY REEL REMOVE <event>The highlight reel: add an event at the end · take it off.
REPLAY REEL UP <event> · REPLAY REEL DOWN <event> · REPLAY REEL CLEARMove an event earlier / later · empty the reel.
REPLAY [B] PLAY REELPlay the reel from the top: its events back to back, each on its own angle, at the channel's speed. Playing an event, cueing or LIVE leaves the reel.
REPLAY EXPORT <event> [ALL] [PRORES|HQ|DNXHR|H264]Export an event to a file on its angle (ALL: one file per recorded angle). ProRes 422 (default) or 422 HQ in .mov, DNxHR HQ in .mxf, with 24-bit PCM; H.264 in .mp4 with AAC.
REPLAY EXPORT REEL [format]The reel, in one file.
REPLAY EXPORT CANCEL <n> · REPLAY EXPORT CLEARStop export n (its partial file is deleted) · forget finished ones.

Exports run in the background, two at a time (the rest wait), below the live work's priority, into <REC ALL folder>/<production>/Replay exports/ (names never overwrite: Event 3 - CAM 1-2.mov). STATE has a replay object: each channel's transport, the events (in / out frames, seconds, angle), the reel (event numbers in order), and exports with their progress (frames of of) and state (queued, running, done, cancelled, failed with error).

Recordings last for the run (deleted on exit). An event older than the buffer can't play any more.

Vertical video​

Command
ADD mix:verticalA vertical (9:16) mix following the main switcher (a sub-mix; M and up).
ADD composite:portraitA 9:16 composite.
VERTICAL <in> PARTNER <in>|NONEThe input shown instead of <in> in vertical mixes (a portrait version), or none.
VERTICAL <in> X <0–1>Without a partner: where its 9:16 slice is centred, across the picture.
COMPOSITE <in> VERTICALBuild a stacked 9:16 version of a composite and link it as its partner (replies with its ID).

STATE: each input's canvas ([1080, 1920] for portrait composites and vertical mixes) and vertical ({"partner": ID, "x": 0.5}).

Scripting​

Scripts are saved with the production (the SCRIPTS tab; M edition and up), in Lua 5.4 (built in, sandboxed: no files, no OS) or Python (the machine's python3, not sandboxed: it runs only where Switcher Settings → Scripts → ALLOW PYTHON SCRIPTS is on, since scripts travel inside production files). Both drive the switcher with this API's own commands and have the same ds API (in Python ds.try_, as try is a keyword; event.kind and event["kind"] both work). Each run has its own thread and can always be stopped; a script that's still running isn't started again.

Command
SCRIPT RUN <name> [words…]Run a script; the words are event.args.
SCRIPT STOP <name> · SCRIPT STOP ALLStop one, or every one.

STATE has scripts: name, running, last error, whether triggers are on.

Inside a script:

ds.cmd('PREVIEW "Camera 2"') -- any command here; returns the reply ("OK", JSON text…)
ds.cmd("CUT") -- an error stops the script…
local ok, reply = ds.try("SUPER 4 ON") -- …unless tried: false and the error instead
ds.wait(1.5) -- seconds
local st = ds.state() -- STATE as a table: st.switcher.program, st.inputs…
local t = ds.tally() -- t.program, t.preview: lists of input IDs
local cam = ds.input("Camera 2") -- an input's STATE entry, by name or ID (nil if none)
ds.set("count", (ds.get("count") or 0) + 1) -- values shared by all scripts, for the switcher's run
ds.now() -- seconds since 1970
print("hello") -- or ds.log(...): to the script log
-- event.kind: "run", "program", "program_out", "preview", "clip_end", "on_air",
-- "super_on", "super_off", "recording", "timer", "at", "opened"
-- event.input (an input's ID), event.on (ON AIR, recording), event.index (a super, 1-based),
-- event.args (SCRIPT RUN's words)

The same in Python:

ds.cmd('PREVIEW "Camera 2"')
ok, reply = ds.try_("SUPER 4 ON")
for i in ds.state()["inputs"]:
print(i["name"], i["status"])
if event.kind == "program":
ds.set("last_live", event.input)

An uncaught Python exception stops the script and is reported as line N: ValueError: …; stopping a Python script ends its process.

Triggers (set per script in the SCRIPTS tab; ON / OFF for all of a script's triggers): an input goes to programme · leaves programme · goes to preview · a clip reaches its end · a super goes on / off air · ON AIR turns on / off · REC ALL starts / stops · every N seconds · each day at a time · the production opens.

Triggers and actions​

"When this happens, do that", without a script (Production Settings → Triggers; every edition). A trigger waits for one of the events above and then runs its actions: commands of this API, in order, each after an optional delay (milliseconds, counted from the action before). A failed action is logged (the SCRIPTS tab's log, as trigger <name>) and the rest still run. A trigger still running its actions isn't started again. Triggers are saved with the production.

Command
TRIGGER FIRE <name>Run a trigger's actions now (also TRIGGER RUN).
TRIGGER ON <name> · TRIGGER OFF <name>Turn a trigger on / off (ENABLE / DISABLE).

STATE has triggers: name, enabled, when (in words), the number of actions, running, how many times it has fired, and the last firing's error.

An action can itself be TRIGGER FIRE other or SCRIPT RUN name (with the scripting entitlement) to chain them.

PTZ cameras​

An input's camera (L and up, or the ptz add-on) over VISCA over IP (Sony's UDP framing, 52381), raw VISCA over TCP (5678: PTZOptics, Lumens, BirdDog…) or UDP (1259), ONVIF (Profile S, with a login), or NDI (an NDI PTZ camera, through the input's own NDI connection). The camera's settings and named presets save with the production; STATE has a ptz list (connection, last error, presets).

<in> can be an input, a shot (it drives the shot's camera), or PREVIEW / PROGRAM: whatever is there now — so a joystick can drive the camera on preview. Speeds are −1…1 (or a percentage).

Command
PTZ <in> CAMERA VISCA|VISCA-TCP|VISCA-UDP|ONVIF|NDI [host] [port] [user] [password] · PTZ <in> CAMERA OFFSet up (or remove) the input's camera. The port defaults to the protocol's.
PTZ <in> MOVE <pan> <tilt>Pan (right +) and tilt (up +) at these speeds until the next move; MOVE 0 0 stops.
PTZ <in> PAN <speed> · PTZ <in> TILT <speed>One axis, keeping the other (for a control surface's stick: PTZ PREVIEW PAN {v} with −1…1; values under 0.1 count as 0).
PTZ <in> ZOOM <speed> · PTZ <in> FOCUS <speed>|AUTOIn + / out −; far + / near −. Speed 0 stops. Focus isn't available over ONVIF.
PTZ <in> STOP · PTZ <in> HOMEStop moving and zooming · the home position.
PTZ <in> PRESET <n> · PTZ <shot> PRESETRecall preset n (a shot: its own).
PTZ <in> STORE <n> [name] · PTZ <in> NAME <n> <name>Store the current position as preset n (ONVIF: a camera preset named DS n) · name it.
ADD shot:<camera>:<n>A shot: the camera's picture as an input of its own. Putting it on preview recalls preset n — unless its camera is on air, which is never moved.

Queries​

STATE · TALLY · INPUTS · OUTPUTS · HELP (one-line summary). SUBSCRIBE (TCP only) — see §5.

STATE's multiviews each carry tiles: what the picture shows where — rect ([x0, y0, x1, y1] as fractions of the picture) and source ("pgm", "pvw", an input's ID, or null), AUTO cells resolved as drawn (the web console's tap-to-preview).

STATE has timing: mode (free-run, or aligned with Switcher Settings → Demon Labs → network-aligned timing), tai_utc (TAI − UTC in seconds) and tai_utc_from_kernel (whether the system clock reported it; otherwise 37 is assumed), and timecode: the time of day now as SMPTE timecode at the production's rate, local time (HH:MM:SS:FF; drop-frame HH:MM:SS;FF at 29.97 / 59.94). With aligned timing also reference — what keeps the clock right: label (PTP LOCKED, NTP, FREE-RUN CLOCK…), source (Ptp / Ntp / None), locked, synced (the kernel's flag), error_us, detail — and discipline: error_ns (system TAI − media time) and slew_ppm (non-zero while the timeline is slewed back after the clock was stepped).

Asynchronous commands​

FADE, MORPH, BUTTON, the OUTPUT … commands and NEW/OPEN/SAVE are handed to the operator application and reply OK once accepted, before they have finished; failures (e.g. a bad stream URL) appear in the UI and in later OUTPUTS state, not in the reply. Everything else is applied (or rejected with ERROR) before the reply.

4. JSON shapes​

TALLY / GET /api/tally​

{"preview":["cH0zAPacOX5P"],"program":["3qwxSSU48QB9"]}

Lists of input IDs. Program includes everything visible on air: mid-transition both sources, supers that are on, and every input inside a composite that's on program (so a camera inside an on-air 2-box tallies red).

INPUTS / GET /api/inputs — one entry​

{
"id": "3qwxSSU48QB9",
"number": 1,
"name": "Camera 1",
"spec": "syn:nv12:50",
"status": "LIVE",
"description": "synthetic · 1920×1080 NV12 @ 50",
"format": "1920×1080 NV12 709/lim",
"program": true,
"preview": false,
"controllable": false,
"clip": null,
"chroma": null,
"sync_delay_ms": 20.0,
"audio": {"gain_db": 0.0, "mute": false, "pan": 0.0, "follow_video": true, "delay_ms": 0.0, "sends": [0.0, 0.0]}
}
  • status: LIVE, WAITING, STALLED, RECONNECTING, PAUSED, ENDED, or ERROR: <message>.

  • clip: null, or for clip players:

    {"state": "PAUSED", "item": 2, "position": 1.0, "remaining": 2.0, "duration": 10.0,
    "in": 1.0, "out": 3.0, "play_on_take": true, "loop": false,
    "items": [{"path": "/media/story1.mp4", "duration": 10.0, "in": 0.5, "out": 2.0},
    {"path": "/media/story2.mp4", "duration": 10.0, "in": 1.0, "out": 3.0}]}

    state: LOADING (no picture from this item yet), PAUSED (cued or paused), PLAYING, ENDED (the frame on screen is the last before the OUT point / end), ERROR. position = time in the file of the frame on screen (seconds, 3 decimals); remaining = to the OUT point (or end); duration = the whole file; item is 1-based. Durations of other items fill in shortly after LOAD.

  • layers: null, or for composites the layers bottom first: [{"source": {"Input": "<ID>"} | "Bars" | "Black", "opacity": 1.0, "transform": {"x": 0.25, "y": 0.5, "scale": 1.0, "crop": [0.25, 0.0, 0.25, 0.0]}}, …].

  • vset: null, or for virtual sets {"shots": ["WIDE", "TWO-SHOT", …], "current": 1, "move_frames": 50} (current: the shot last taken, from 0).

  • stats: over the last second, {"fps": 50.0, "repeated": 0, "dropped": 0} — new frames shown, ticks that repeated the last one, frames skipped (0.45.2; not in SUBSCRIBE pushes, which they'd otherwise send every second).

  • controllable: accepts CONTROL commands (clips, HTML templates).

  • chroma: null or {"color":[r,g,b],"similarity":…,"smoothness":…,"spill":…}.

STATE / GET /api/state​

Top-level keys: format (e.g. "1080p50"), inputs (as above), tally (as above), switcher, audio, outputs, multiviews, production (path or null), edited (unsaved changes).

"switcher": {
"program": {"Input": "3qwxSSU48QB9"},
"preview": {"Input": "cH0zAPacOX5P"},
"transition": {"kind": "Mix", "frames": 25},
"position": 0.0,
"auto_running": false,
"ftb_on": false, "ftb": 0.0, "ftb_frames": 25,
"supers": [
{"source": "Black", "on_air": false, "mix": 0.0, "opacity": 1.0, "fade_frames": 25, "chroma": null,
"transform": {"x": 0.5, "y": 0.5, "scale": 1.0, "crop": [0.0, 0.0, 0.0, 0.0]}}
]
}
  • Sources: {"Input": "<ID>"}, "Black" or "Bars".
  • transition.kind: "Mix", "Merge" (the MORPH transition), {"Dip":{"color":[r,g,b]}}, {"Wipe":{"pattern":"Horizontal"|"Vertical"|"Diagonal"|"Circle"|"Box","softness":…,"reverse":…}}, {"Stinger":{"input":"<ID>","cut":<frame>}}.
  • position 0..1 during a transition (auto_running true while an AUTO runs).
  • supers[n].on_air is the target state; mix is how far faded on (0..1).

OUTPUTS / GET /api/outputs — one entry​

{"id": 1, "name": "Record show", "status": "Running", "auto_start": true, "frames": 228, "dropped": 0,
"config": {"kind": {"Record": {"path": "/home/op/show.mkv"}}, "source": "Program",
"audio": "Master", "size": null, "video_kbps": 25000}}

status: Running, Starting, Ready (configured, stopped), Error(…). config.kind is one of Ndi, Omt, Srt, Rtmp, Record, DeckLink, Screen; config.source is "Program", "Preview", {"Multiview":n} (0-based) or {"Input":"<ID>"}.

GET /api/audio (meters — changes every frame, so not in STATE)​

{"master": {"peak_db": [-18.0, -18.0], "momentary_lufs": -18.0, "short_term_lufs": -18.0},
"aux": [ … ],
"strips": [{"id": "3qwxSSU48QB9", "name": "Camera 1", "follow": 1.0, "has_audio": true,
"meter": {"peak_db": [-33.3, -33.3], "momentary_lufs": null, "short_term_lufs": -28.7}}]}

null = silence. follow is the input's current audio-follow-video gain (0..1).

5. Push updates​

TCP: send SUBSCRIBE (reply OK). From then on the connection also carries, whenever they change (checked 25×/s):

TALLY {"preview":["cH0zAPacOX5P"],"program":["3qwxSSU48QB9"]}
STATE {"audio":{…},"edited":false,"format":"1080p50","inputs":[…],…}

You get both once immediately after subscribing. Clip players also push a small line whenever their position or state changes (each frame while playing):

CLIP {"id":"wZ6VrmfLWbUg","item":2,"state":"PLAYING","position":2.04,"remaining":0.96,"duration":10.0}

(STATE isn't re-sent for position changes alone — use CLIP for countdowns and end-of-clip. Nor for other things that change all the time: replay's frame, export progress, outputs' frame and drop counts, REC ALL's running seconds, the time of day in timing.timecode and the clock reference's measured offsets; they ride along when anything else changes. Poll STATE for them.) Replies to your commands are interleaved, in order. Captured session:

> TALLY
< {"preview":["3qwxSSU48QB9"],"program":["cH0zAPacOX5P"]}
> CUT
< OK
> SUBSCRIBE
< OK
< TALLY {"preview":["cH0zAPacOX5P"],"program":["3qwxSSU48QB9"]}
< STATE {…}
> CUT
< OK
< TALLY {"preview":["3qwxSSU48QB9"],"program":["cH0zAPacOX5P"]}
< STATE {…}

WebSocket /api/ws: pushes {"type":"tally","program":[…],"preview":[…]}, the full state with "type":"state", and clip positions with "type":"clip" (same fields as the TCP CLIP line) whenever they change (once each on connect). Send a text command (CUT) or a JSON command (below); each gets {"type":"reply","ok":true[,"result":…]} or {"type":"reply","ok":false,"error":"…"}.

6. HTTP endpoints​

GET /api/state · /api/tally · /api/inputs · /api/outputs · /api/audioAs above.
POST /api/textBody: text command(s), one per line → reply of the last.
GET|POST /api/do/<words…>/api/do/preview/3qwxSSU48QB9 = PREVIEW 3qwxSSU48QB9 (for simple button URLs).
POST /api/commandA JSON command (below).
POST /api/inputs{"spec":"…"} → {"id":"<ID>"}.
DELETE /api/inputs/<ID>Remove an input.
GET /The control page (pictures, switching, supers, audio, replay, PTZ, scripts, outputs). /#open=audio,replay opens those sections.
GET /api/snapshot/<src>?w=320A JPEG of pgm, pvw, mv<n> or an input (by ID), w pixels wide (16:9). Each source asked for is captured while it's asked for and closed after 15 s unasked; a request takes the next fresh frame (~20–40 ms).

JSON commands (POST /api/command, WebSocket)​

The switcher's native command form, if you prefer it to text:

"Cut"
"Auto"
"FadeToBlack"
{"Preview": {"Input": "3qwxSSU48QB9"}}
{"Program": "Bars"}
{"TBar": 0.5}
{"SetTransition": {"kind": "Mix", "frames": 25}}
{"SuperSource": {"index": 0, "source": {"Input": "3qwxSSU48QB9"}}}
{"SuperOnAir": {"index": 0, "on": true, "fade": true}}
{"AllSupers": {"on": false, "fade": true}}
{"Audio": {"Gain": {"input": "3qwxSSU48QB9", "db": -6.0}}}

Super index is 0-based here (SUPER 1 = index 0).

7. Errors​

  • TCP: ERROR <message> (single line). HTTP: status 400 with {"error":"…"}. WebSocket: {"type":"reply","ok":false,"error":"…"}.
  • Examples: unknown command "frobnicate" (try HELP); no input with ID or name "Cam 9"; inputs are addressed by their ID or name, not by number ("2")…; button 7: there are 6 custom take buttons.
  • A rejected line changes nothing. On POST /api/text with several lines, processing stops at the first error.

8. Coming from vMix​

vMix (Function= / TCP FUNCTION)Demon Switcher
PreviewInput Input=XPREVIEW <in>
ActiveInput / CutDirect Input=XPROGRAM <in>
CutCUT
Fade Duration=ms (preview → program)FADE (operator's duration), or TRANSITION mix <frames> then AUTO
Fade Input=XPREVIEW <in> then FADE
MergeMORPH (same idea: matching elements move into place)
Stinger1–4BUTTON n (the operator's stinger buttons), or TRANSITION stinger <clip> <frames> <cut> + AUTO
Transition1–4BUTTON n
SetTransitionEffect1 / SetTransitionDuration1TRANSITION <kind> <frames> / DURATION <frames>
SetFader Value=0–255TBAR <value/255>
FadeToBlackFTB
QuickPlay Input=XPREVIEW <in> then CUT (clips: they start when taken)
OverlayInput1In Input=X / Out / OverlayInput1SUPER 1 SOURCE <in> then SUPER 1 ON / OFF / TOGGLE (CUT = instant)
OverlayInputAllOffSUPERS off
SetText Input=X SelectedName=… Value=…HTML templates: CONTROL <in> update {"<field>":"<value>"}
Play / Pause / Restart (input)CONTROL <in> play / pause / restart
List input: ListAdd, ListRemoveAll + addsLIST <in> ADD <path> · LIST <in> LOAD <path> …
List input: SelectIndex Value=nLIST <in> SELECT <n> (1-based), optionally with IN/OUT
SetPosition Value=msSEEK <in> <seconds> (ms ÷ 1000)
Replay: ReplayMarkIn / ReplayMarkOut / ReplayPlayLastEventREPLAY IN / REPLAY OUT / REPLAY PLAY <event> (REPLAY LAST n for an instant replay)
Replay: ReplaySetSpeed Value=0.5 · ReplayPlay / ReplayPause · ReplayLiveREPLAY SPEED 50 · REPLAY TOGGLE / REPLAY PAUSE · REPLAY LIVE
Replay: ReplayACamera1–8REPLAY ANGLE 1–8
MarkIn / MarkOut (+ watching the position to stop)LIST <in> SELECT n IN t OUT t or LIST <in> MARK IN t OUT t — the player stops at OUT itself
XML <input position duration selectedIndex>STATE → inputs[].clip (position, duration, item, state), live via CLIP pushes
Multi View: set layer n inputCOMPOSITE <in> LAYER <n> SOURCE <src>
LoopOn / LoopOffLOOP <in> on / off
SetVolume Value=0–100GAIN <in> <dB> (decibels: 0 = unity, e.g. −6)
AudioOn / AudioOffMUTE <in> off / on
AudioAutoOn / AudioAutoOffAFV <in> on / off
SetMasterVolumeMASTER <dB>
StartRecording / StartStreaming / StartExternalOUTPUT START <id> for the operator's configured output (see OUTPUTS), or OUTPUT <spec>
AddInput Value=File|pathADD /path
RemoveInput · SetInputNameREMOVE <in> · RENAME <in> <name>
TCP TALLY → TALLY OK 0120TALLY → {"program":[IDs],"preview":[IDs]}
TCP SUBSCRIBE TALLYSUBSCRIBE (tally and state)
GET /api (XML state)GET /api/state (JSON) or STATE
Input number / key / titleInput ID (≈ vMix input key) or name — not numbers

Differences to plan for:

  • Durations are frames, not milliseconds — convert with the frame rate from STATE.format.
  • No input numbers. Map names → IDs once from INPUTS; refresh when STATE pushes a changed input list.
  • Overlays are "supers" 1–4, and stay on through cuts until taken off.
  • Titles are HTML templates driven with CONTROL … update {json} (CasparCG-style fields such as f0, f1), not GT titles.
  • Tally includes composite contents and supers on air.
  • Outputs (recording, streams, NDI, screens) are configured by the operator and started/stopped/routed by ID; there's no fixed "recording" singleton.
  • Out points are handled by the player: send IN/OUT with SELECT, and react to ENDED (a CLIP push) rather than polling the position to stop.
  • Composite layers are 1-based, bottom first (layer 1 is usually the background).