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
| Transport | Default | Best for |
|---|---|---|
| TCP text | port 7892 | Automation: one command per line, one reply per line, plus pushed tally/state after SUBSCRIBE. Closest to vMix's TCP API. |
| HTTP REST | port 7890 | One-off commands, polling state, adding inputs. |
| WebSocket | ws://host:7890/api/ws | Browser/JS clients: pushed state + tally, send commands on the same socket. |
| OSC (UDP) | port 7891 | Lighting/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 (replyOK <role>); before that every line getsERROR … 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 answersnot allowed: that needs Operator (key … is Viewer). - Refused: HTTP
401({"error", "login": true, "setup"}),429after 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.
- HTTP:
- 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(0disables 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
SUBSCRIBEonce, then send commands on it. Treat any line that starts withTALLYorSTATEas 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 asidinINPUTS/STATEand 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.) Thenumberfield inINPUTSis display order only. - Two built-in sources need no ID:
BLACK(orBLK) andBARS. - 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
| Command | Does |
|---|---|
PREVIEW <src> (PVW) | Put a source on preview. |
PROGRAM <src> (PGM) | Hot-cut a source straight to program (preview unchanged). |
CUT | Swap program and preview instantly. |
AUTO (TAKE) | Run the current transition (see TRANSITION). |
FADE | Mix 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). |
FTB | Toggle 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 / TOGGLE | Fade on / off over the super's fade time. |
CUT | Toggle instantly. |
PIP full|tl|tr|bl|br | Full 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 / DISABLE | Use 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|off | Audio 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>|off | Low cut / high cut (12 dB/octave). |
EQ <in|MASTER> <band 1–4> <Hz> <dB> [Q] [peak|lowshelf|highshelf] · EQ … <band> off | A 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> reset | All 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
| Command | Reply |
|---|---|
ADD <spec> | {"id":"<new ID>"} — see specs below. |
REMOVE <in> | |
RENAME <in> <new name> | |
MOVE <in> <position> | 1 = first. |
PLAYMODE <in> take|background | Clips: wait cued and play when taken to program, or play all the time. |
LOOP <in> on|off | Clips. |
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:
| Spec | Source |
|---|---|
/path/clip.mp4, file:///… | Video/still file (clips start cued: PLAYMODE take). |
stinger:/path/clip.mov | A 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.m3u8 | Network 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.json | An EBU OGraf graphic (in the HTML engine). |
device:<name>, v4l2:/dev/videoN, decklink:N | Capture devices. |
composite | An empty composite input (layers are set by the operator). |
syn:bars, syn:nv12:50, syn:lowerthird | Test 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|br | Placement 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> CLEAR | Add 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 / restart | restart = back to the IN point. |
PLAYMODE <in> take|background · LOOP <in> on|off | See 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; withLOOP onit 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:00while p is off air → take p to program → the clip plays and stops at its OUT point;CLIPpushes reportENDED→ 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|4x4 | Change 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|off | Audio meters on the tiles (on by default): each input's own level, the master mix on PROGRAM. |
MULTIVIEW <n> NAME <name> · MULTIVIEW <n> REMOVE | Removing 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> REMOVE | Later buses move down; outputs follow; outputs on it go silent. |
SEND <in> <bus> on|off | The 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|off | Whether 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 | |
|---|---|
OUTPUTS | List (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|off | Start 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|toggle | REC 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|toggle | The 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) #n | Anywhere 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 OFF | The 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 CANCEL | Take 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 OUT | Mark 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 TOGGLE | Pause (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 NEXT | Change angle — on the same frame, while playing. |
REPLAY STEP [frames] | Step (negative: back); pauses. |
REPLAY LIVE | Back 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 CLEAR | Move an event earlier / later · empty the reel. |
REPLAY [B] PLAY REEL | Play 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 CLEAR | Stop 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:vertical | A vertical (9:16) mix following the main switcher (a sub-mix; M and up). |
ADD composite:portrait | A 9:16 composite. |
VERTICAL <in> PARTNER <in>|NONE | The 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> VERTICAL | Build 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 ALL | Stop 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 OFF | Set 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>|AUTO | In + / out −; far + / near −. Speed 0 stops. Focus isn't available over ONVIF. |
PTZ <in> STOP · PTZ <in> HOME | Stop moving and zooming · the home position. |
PTZ <in> PRESET <n> · PTZ <shot> PRESET | Recall 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, orERROR: <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;itemis 1-based. Durations of other items fill in shortly afterLOAD. -
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 inSUBSCRIBEpushes, which they'd otherwise send every second). -
controllable: acceptsCONTROLcommands (clips, HTML templates). -
chroma:nullor{"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>}}.position0..1 during a transition (auto_runningtrue while an AUTO runs).supers[n].on_airis the target state;mixis 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/audio | As above. |
POST /api/text | Body: 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/command | A 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=320 | A 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/textwith several lines, processing stops at the first error.
8. Coming from vMix
vMix (Function= / TCP FUNCTION) | Demon Switcher |
|---|---|
PreviewInput Input=X | PREVIEW <in> |
ActiveInput / CutDirect Input=X | PROGRAM <in> |
Cut | CUT |
Fade Duration=ms (preview → program) | FADE (operator's duration), or TRANSITION mix <frames> then AUTO |
Fade Input=X | PREVIEW <in> then FADE |
Merge | MORPH (same idea: matching elements move into place) |
Stinger1–4 | BUTTON n (the operator's stinger buttons), or TRANSITION stinger <clip> <frames> <cut> + AUTO |
Transition1–4 | BUTTON n |
SetTransitionEffect1 / SetTransitionDuration1 | TRANSITION <kind> <frames> / DURATION <frames> |
SetFader Value=0–255 | TBAR <value/255> |
FadeToBlack | FTB |
QuickPlay Input=X | PREVIEW <in> then CUT (clips: they start when taken) |
OverlayInput1In Input=X / Out / OverlayInput1 | SUPER 1 SOURCE <in> then SUPER 1 ON / OFF / TOGGLE (CUT = instant) |
OverlayInputAllOff | SUPERS 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 + adds | LIST <in> ADD <path> · LIST <in> LOAD <path> … |
List input: SelectIndex Value=n | LIST <in> SELECT <n> (1-based), optionally with IN/OUT |
SetPosition Value=ms | SEEK <in> <seconds> (ms ÷ 1000) |
Replay: ReplayMarkIn / ReplayMarkOut / ReplayPlayLastEvent | REPLAY IN / REPLAY OUT / REPLAY PLAY <event> (REPLAY LAST n for an instant replay) |
Replay: ReplaySetSpeed Value=0.5 · ReplayPlay / ReplayPause · ReplayLive | REPLAY SPEED 50 · REPLAY TOGGLE / REPLAY PAUSE · REPLAY LIVE |
Replay: ReplayACamera1–8 | REPLAY 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 input | COMPOSITE <in> LAYER <n> SOURCE <src> |
LoopOn / LoopOff | LOOP <in> on / off |
SetVolume Value=0–100 | GAIN <in> <dB> (decibels: 0 = unity, e.g. −6) |
AudioOn / AudioOff | MUTE <in> off / on |
AudioAutoOn / AudioAutoOff | AFV <in> on / off |
SetMasterVolume | MASTER <dB> |
StartRecording / StartStreaming / StartExternal | OUTPUT START <id> for the operator's configured output (see OUTPUTS), or OUTPUT <spec> |
AddInput Value=File|path | ADD /path |
RemoveInput · SetInputName | REMOVE <in> · RENAME <in> <name> |
TCP TALLY → TALLY OK 0120 | TALLY → {"program":[IDs],"preview":[IDs]} |
TCP SUBSCRIBE TALLY | SUBSCRIBE (tally and state) |
GET /api (XML state) | GET /api/state (JSON) or STATE |
| Input number / key / title | Input 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 whenSTATEpushes 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 asf0,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 toENDED(aCLIPpush) rather than polling the position to stop. - Composite layers are 1-based, bottom first (layer 1 is usually the background).