Fantareel remote control — protocol specification
For writers of control clients (the Fantacore handler first). It describes the protocol as the code is now; where something a controller might expect does not exist, it says NOT IMPLEMENTED. The field-by-field reference of every data shape is the field reference below; this document is the contract around it: transport, security, message framing, identity, commands, continuous values, events, lists, a recorded session and how to test.
1. Transport
Fantareel embeds one HTTP server (ASP.NET Core / Kestrel, in-process) that carries both a REST API and a WebSocket.
| Base URL | http://<host>:<port> — plain HTTP / WS. TLS (https, wss): NOT IMPLEMENTED. |
| Default port | 8088 (TCP), the same for REST and WebSocket. |
| Configurable | Yes: Settings › Remote control › Port (RemotePort in %AppData%\Fantago\FantaReel\settings.json). Changing it restarts the server at once. |
| Interfaces | Only from this PC (the default): localhost (127.0.0.1 and ::1). From the network: every interface, IPv4 and IPv6. Settings › Remote control shows the addresses to use. |
| WebSocket | ws://<host>:<port>/ws, query time=<ms> (timing rate, see §7) and apiKey=<key>. |
| REST | under http://<host>:<port>/api/…; JSON bodies (Content-Type: application/json), JSON answers. |
| Discovery | GET / (never needs the key): {"name":"FantaReel","version":"0.1.9","api":"/api/status","websocket":"/ws?time=100"}. mDNS / broadcast discovery: NOT IMPLEMENTED. |
Which one to use. Both reach the same commands (RemoteCommands, shared code). Recommended for a controller:
one WebSocket for everything — commands go up as JSON messages, each answered by a result; state and events come
down on the same socket. REST is for scripts, one-off reads and the few things only REST has (§5, marked REST only).
Events exist only on the WebSocket: REST has no long-poll / SSE.
Clients. No limit on the number of WebSocket clients or HTTP callers; all receive the same events. Each WebSocket client has its own outgoing queue (256 messages; when full the oldest are dropped), so a slow client never slows down Fantareel or the others. Commands from several clients are applied in the order they reach the engine; there is no locking or ownership between controllers, and the operator at the PC keeps full control at the same time.
2. Security
| Authentication | Optional API key (a shared secret), set in Settings › Remote control › API key. Empty = no authentication. |
| How to send it | HTTP header X-Api-Key: <key>, or the query parameter ?apiKey=<key> (for WebSocket clients that cannot set headers). Checked on every request except GET /, including the WebSocket upgrade. |
| Wrong / missing key | HTTP 401 with {"error":"Missing or wrong API key (header X-Api-Key, or ?apiKey= for WebSockets)."}; on /ws the upgrade is refused with that 401, so the WebSocket never opens. |
| Users, roles, read-only keys, rate limiting | NOT IMPLEMENTED: a client with the key can do everything listed in §5. |
| Encryption | NOT IMPLEMENTED (plain HTTP): with From the network, keep Fantareel on a trusted network. |
| CORS | Open to any origin (a browser page can call it). |
| Enabled by default | No. Off until Settings › Remote control › Enable remote control is ticked; Only from this PC by default. Kept in the settings across restarts. |
| Licence | Not required. Without a licence everything works, the remote control included; the program output carries a watermark. GET /api/license tells whether this PC is licensed. |
3. Message format
Conventions (REST and WebSocket)
- JSON, UTF-8, camelCase property names. Enums are strings (
"Video","Next"); string values sent to Fantareel are case-insensitive. - Times in seconds (numbers, up to 3 decimals); transition and fade lengths in milliseconds (
durationMs). Moments (scheduled start, recording window) are ISO 8601 strings with Fantareel's UTC offset. - Ids are GUID strings (
"937b9bc9-44fc-4d89-a2af-c4fada300b0a"), see §4.
WebSocket: request
{"id": "42", "action": "take", "itemId": "937b9bc9-44fc-4d89-a2af-c4fada300b0a"}
action is required; the arguments are siblings of action (no nested params). id is optional, any string or number,
and is echoed in the result — always as a string ("id": 8 comes back as "id": "8"). Messages are handled one
at a time per connection, in the order sent.
WebSocket: response
{"type": "result", "id": "42", "ok": true, "data": null}
{"type": "result", "id": "4", "ok": false, "error": "No item at index 7 (the rundown has 3)."}
data is null for pure actions, or the object / array listed in §5. Errors carry a human-readable English error
only: machine-readable error codes on the WebSocket are NOT IMPLEMENTED (REST has the HTTP status). A message that
is not valid JSON gets ok: false with id: null.
The engine applies commands on the next output frame (a take on a clip still loading waits for it, up to a few
seconds, with the previous item on air). So ok: true means accepted and queued; the program event confirms what
went on air. Events caused by a command can arrive before or after its result (in the recording in §9 they arrive
before).
WebSocket: events
Every message from Fantareel has a type: state, result, or one of the events of §7. Unknown types must be ignored
(new ones may be added).
REST
The body is the arguments (same names as on the WebSocket, minus action and the id in the path); the answer is the
data directly. Errors: an HTTP status and {"error":"message"} — 400 bad request, 401 key, 404 unknown item /
index / file / graphic, 409 the action cannot be done now (recording or stream cannot start…, the reason in error),
503 the function is not available in this server.
Version, handshake, heartbeat, reconnection
- Protocol version: NOT IMPLEMENTED. There is no version field and no negotiation.
GET /gives the application version ("0.1.9"); changes so far only add fields, actions and event types. - Handshake: none to perform. Right after the WebSocket opens, Fantareel sends one
statemessage (the complete state, §7). There is nohellofrom the client. - Client identification (optional): Fantacore says who it is with the header
X-Client: Fantago/<version>on REST requests and?client=Fantagoin the WebSocket URL (aUser-Agentholding "Fantago" or "FantaCore" counts too). Nothing changes in the answers: Fantareel only notes it for its anonymous usage statistics ("controlled by Fantago"). - Heartbeat: Fantareel sends WebSocket ping frames every 15 s (protocol level: clients answer pong
automatically). An application-level
pingaction is NOT IMPLEMENTED (it getsUnknown action "ping"); a client can usegetStateas one. Fantareel does not close a silent client on its own; a dead peer is noticed when the TCP connection fails. - Disconnect / reconnect: there are no sessions. A dropped client loses nothing on the Fantareel side (nothing is on
hold for it) and what it missed is not replayed. On reconnecting it gets a fresh
state: take it as the truth and rebuild. Reconnection is up to the client (suggested: retry every 1–2 s, with back-off). The server also closes all connections when its settings change (port, key, access) or Fantareel closes. - Known defect: when the client sends a close frame, Fantareel ends the TCP connection without sending its close frame back (seen in §9: "The remote party closed the WebSocket connection without completing the close handshake"). Treat that as a normal close.
4. Object identity
| Object | Identified by | Stable? |
|---|---|---|
| Rundown item | id (GUID) |
Yes. Made when the item is created and saved in the .frl: it does not change when items are reordered, renamed, edited, skipped, or when the rundown is saved and opened again (verified in §9: same ids after save + open). A copy, a duplicate or a paste is a new item with a new id. Adding the same file twice gives two ids. |
| Item position | index (0-based) |
No: changes with every insert, delete or move. |
| Graphic of the rundown | id (GUID) |
Yes, saved in the .frl like the items. |
| SRT input | id (GUID) |
Yes, saved in Fantareel's settings (an item refers to it by liveInputId). |
| Outputs | fixed names | There is one program output; recording, stream and NDI are fixed objects with their own commands (no ids). |
| Rundown (file) | path relative to the rundown folder ("News/News evening.frl") |
Yes while the file is not renamed or moved (a rename shows in the rundowns event). The open rundown is openRundown; its path is null when it was never saved or is outside the folder (§5, Rundowns). |
Every command that addresses an item accepts itemId; take and cue also accept index. A controller should use
itemId only: an itemId either reaches that very item or fails with No item <id> in the rundown. — it never
reaches another one after a reorder. Ids are unique within one rundown; the same .frl opened twice gives the same ids,
so a button bound to an id keeps working across save / reopen, and fails cleanly when that item has been deleted or a
different rundown is loaded.
No protocol change was needed for this point.
5. Commands
WebSocket action name, then the REST equivalent. "Item" / "Graphic" etc. are the shapes of the field reference below.
Every item-addressed command fails with No item <id> in the rundown. (404) for an unknown id, and with a .NET format
message for an id that is not a GUID. index arguments are integers.
Session
| Action | Arguments | data |
REST |
|---|---|---|---|
getState |
— | the state message (§7) |
GET /api/status (status only), GET /api/rundown |
getInputs |
— | SRT inputs (array) | GET /api/inputs; one input with its streams and events: GET /api/inputs/{id} (REST only) |
Playout / transport
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
take |
itemId (GUID) or index (0…count−1); itemId wins if both |
null | "take" needs "index" or "itemId".; No item at index 7 (the rundown has 3). (404) |
POST /api/items/{id}/take, POST /api/playout/take/{index} |
cue |
as take |
null | as take |
POST /api/items/{id}/cue, …/cue/{index} |
next, previous |
— | null | — (skips items marked skipped; follows the rundown repeat) | POST /api/playout/next, /previous |
black |
— | null | — | POST /api/playout/black (cut to black) |
fadeToBlack |
durationMs (number > 0, optional; default = the default transition's length, at least 500) |
null | — | POST /api/playout/fade-to-black |
pause, resume, togglePause |
— | null | — | POST /api/playout/pause, /resume, /toggle-pause |
restart |
paused (bool, optional): wait on the first frame |
null | — | POST /api/playout/restart |
seek |
position (seconds, file time; < 0 → 0) required |
null | "seek" needs "position" (seconds).; Seek needs a clip on air. (400) |
POST /api/playout/seek |
setTransition |
kind required: cut / fade / wipe; durationMs (> 0, default 500); wipe: shape (LeftToRight, RightToLeft, TopToBottom, BottomToTop, DiagonalDown, DiagonalUp, BarnDoorHorizontal, BarnDoorVertical, BoxOut, BoxIn, CircleOut, CircleIn, DiamondOut, Clock, Blinds; default LeftToRight) |
null | Unknown transition "x" (cut, fade or wipe).; Unknown wipe "x" (…). |
GET / PUT /api/playout/transition |
cue puts the item on air, paused on its first frame (there is no preview channel: Fantareel has one program).
The default transition is used by takes of items without their own transition, and is the toolbar's Transition.
Selection (the cursor of the rundown list)
There is one selection: the one of Fantareel's rundown list, which the operator sees and moves with the mouse and the keyboard. A client reads and moves the very same one, so a knob or two arrow keys on a panel move the highlight the operator sees, and a key takes what is selected.
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
selection |
— | Selection, or null | — | GET /api/selection |
select |
itemId (GUID, or null = nothing selected) or index (0…count−1, or null) |
Selection, or null | "select" needs "itemId" or "index" (null: nothing selected).; No item <id> in the rundown. (404); No item at index 7 (the rundown has 5). (404) |
PUT /api/selection {"itemId": "…"} |
moveSelection |
steps required, a whole number: +1 down, −1 up, any size |
Selection | "moveSelection" needs "steps", a whole number (negative: up). |
POST /api/selection/move {"steps": 1} |
takeSelected |
— | null | No item is selected in the rundown. (409) |
POST /api/selection/take (answers {program, time}) |
cueSelected |
— | null | as takeSelected |
POST /api/selection/cue |
Selection: {"itemId": "f12196fd-…", "index": 4, "count": 1}, or null when nothing is selected. count is how many
items are selected: more than 1 only when the operator selected several (Ctrl / Shift + click, Ctrl+A); itemId is then
the list's current one. select and moveSelection always leave one item selected.
moveSelectionstops at the first and at the last item, never wraps round (+1 on the last item answers the last item again, without aselectionevent). With nothing selected it starts from the item on air (+1 selects the one after it), or, with nothing on air, from before the first item (+1 or −1 select the first).- Skipped items can be selected like any other (and taken:
takeSelectedis a take by hand). - The list scrolls to keep the item selected remotely in view. The keyboard focus is never taken: an operator typing in a field (an item's title, a time, the volume) keeps typing there. Only when the operator is in the list itself does its keyboard cursor follow, so the arrow keys go on from the item selected remotely.
- Selecting never puts anything on air. At the PC, a plain click on a row selects it and takes it (that is
Fantareel's click); Ctrl / Shift + click and the arrow keys only select. Both send a
selectionevent.
Where the selection goes by itself:
| When | The selection |
|---|---|
The selected item is deleted (at the PC or removeItem) |
the item now in its place (the one that followed), or the last item when it was the last; none when the rundown is empty |
| The selected item is moved (or others around it) | stays on that item; its index changes (selection event) |
A rundown is loaded (loadRundown, or File › Open / New / Close at the PC), even the same file again |
nothing selected (selection: null) |
| An item goes on air, ends, or the program goes to black | unchanged |
A knob: send one moveSelection per detent (steps: ±1), or the detents counted since the last message (steps: ±n).
Every message is applied, in the order sent, none is dropped or merged: messages of one connection are handled one
after the other, each moving from where the previous one left the selection. The selection lives on Fantareel's window
thread, not the playout thread: moving it never touches the output. Measured on Fantareel (§9): 200 moves at 25 a
second, each answered in about 1 ms (3.4 ms the slowest); 200 sent at once, all answered in order within 0.1 s; no late
or dropped output frame. There is no limit to respect for a knob (25 a second is far below what it handles); above a
few hundred a second, prefer steps: n. Each move that changes the selection also sends a selection event to every
client.
Rundown and items
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
updateItem |
itemId required, then only the fields to change: title (non-empty string), loop (bool; true also sets the end action to Hold), endAction (Hold / Black / Next), gainDb (−60…+20, rounded to 0.5 dB, clamped), markIn (s; ≤ 0 removes it), markOut (s), clearMarks (bool, applied first), displayTime (s, stills; ≤ 0 = until the next take), clearDisplayTime (bool), transition (default / cut / fade), transitionMs (fade length, default 500), skip (bool), startAt (start in time: HH:MM or HH:MM:SS, local time of the Fantareel PC), clearStartAt (bool), audioVisual (Spectrum / Waveform / Black, audio items), audioCaption (TrackTitle / FileName / None, audio items) |
Item | Empty title.; Unknown end action "x" (Hold, Black or Next).; Mark out must be after mark in.; Unknown transition "x" (default, cut or fade).; "x" is not a time of day (HH:MM or HH:MM:SS).; audioVisual and audioCaption apply to audio items only. |
PATCH /api/items/{id} |
addItem |
path required (a file on the Fantareel PC), index (optional, clamped; default: at the end) |
Item (with its new id) | File not found: … (404); Unsupported file type: .xyz |
POST /api/items (201) |
removeItem |
itemId |
null | — | DELETE /api/items/{id} (204) |
moveItem |
itemId, index (clamped to the list) required |
null | "moveItem" needs "index". |
POST /api/items/{id}/move |
skip, unskip |
itemId |
null | — | POST /api/items/{id}/skip, /unskip |
setPlanned |
itemId, or itemIds (array), or nothing = every item |
null | — | POST /api/items/{id}/planned, POST /api/rundown/planned |
copyParameters |
from (item id), to (array of item ids, ≥ 1), parameters (All default, Playback, Audio, Transition, Framing, Graphics) |
null | "copyParameters" needs "from".; "to" lists no item.; Unknown parameters "x" (…). |
POST /api/items/{id}/copy-parameters |
repeat |
— | Repeat | — | GET /api/rundown/repeat |
setRepeat |
mode (Once / Times / Loop) required; times (1…999, for Times) |
Repeat | "Times" needs "times" from 1 to 999.; Unknown repeat mode "x": Once, Times or Loop. |
PUT /api/rundown/repeat |
schedule |
— | {at, startsIn} |
— | GET /api/rundown/schedule |
scheduleStart |
at required: a time of day ("18:00", "18:00:30": the next one on Fantareel's clock) or an ISO 8601 date and time |
{at, startsIn} |
"at": "x" is neither a time of day … nor an ISO 8601 date and time. |
PUT /api/rundown/schedule |
cancelScheduledStart |
— | {at: null, startsIn: null} |
— | DELETE /api/rundown/schedule |
Not available remotely (NOT IMPLEMENTED): adding colour bars, a solid colour, an SRT input or a video input as an
item (addItem takes media files only); an item's own wipe transition (updateItem sets cut / fade / default);
image framing; the item's graphics; duplicate / copy / paste; new / save / save as / close the rundown; the recent
rundowns.
Rundowns (the rundown folder)
The rundowns a client can list and load are the .frl files of one folder and its subfolders: Settings › Remote
control › Rundown folder, by default Documents\FantaReel\Rundowns (made when Fantareel starts and it is missing).
Fantareel watches it: a rundown added, deleted, renamed, moved or saved there — a subfolder renamed or deleted too —
sends a rundowns event within about a second, without a restart (and the folder is read again every 30 s in case the
system missed a change). Changing the folder in the settings sends a rundowns event with the new list.
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
listRundowns |
— | Rundown array, sorted by path |
503 when the folder is not available | GET /api/rundowns |
openRundown |
— | Open rundown | — | GET /api/rundown/open |
loadRundown |
rundown required: the path of a rundown, relative to the rundown folder ("News/News evening.frl"; / or \, any case); discardChanges (bool, default false) |
Open rundown (the new one) | see below | POST /api/rundown/load {"rundown": "…", "discardChanges": false} |
Rundown: {"name": "News evening", "path": "News/News evening.frl", "modified": "2026-10-29T00:15:14.6066401+01:00"} —
name is the file name without .frl, path is relative to the folder with /, modified is when it was last
saved (ISO 8601, Fantareel's offset; JSON may write the + as \u002B, as every JSON parser reads it).
Open rundown: {"name": "News evening", "path": "News/News evening.frl", "unsaved": false} — name is "Untitled" and
path null for a rundown never saved; path is also null for a file outside the rundown folder (opened at the PC);
unsaved is true once it has changes not saved yet (by the operator or remotely).
loadRundown refuses (nothing is loaded, what is on air does not change):
| Status (REST) | When | error (example) |
|---|---|---|
| 400 | an absolute path, a drive letter, a UNC path, a : |
"C:\Users\Public\show.frl": only paths relative to the rundown folder are accepted. |
| 400 | a .. anywhere |
"../../Desktop/show.frl": ".." is not accepted, the rundown must be in the rundown folder. |
| 400 | another extension (also .fvu: open those at the PC and save them as .frl) |
"notes.txt": only .frl rundowns can be loaded. |
| 400 | the old path argument |
"path" is no longer accepted: give "rundown", the path relative to the rundown folder (listRundowns). |
| 400 | the file is not a valid rundown | 'x.frl' is not a valid FantaReel rundown: … |
| 404 | a valid path, but no such rundown | No rundown "News/Missing.frl" in the rundown folder. |
| 409 | the open rundown has unsaved changes and discardChanges is not true |
The open rundown has unsaved changes ("News evening"): save it, or load with "discardChanges": true. |
| 503 | the rundown folder cannot be used | The rundown folder is not available (Settings › Remote control). |
No file outside the rundown folder can be opened remotely: absolute paths are no longer accepted at all (the former
path argument is refused, not kept for compatibility). Links or junctions placed inside the folder by the operator
are followed.
What a load does. The same as opening the file at the PC (File › Open), without asking anything:
- The items, the repeat and the graphics of the rundown come from the file; every item is planned, the
pass is 1. Fantareel's window shows the new rundown's name and file, saved (
unsaved: false), and it joins the recent rundowns: saving at the PC afterwards writes that file. - What is on air stays on air, untouched: the same picture and sound, position, pause, its own graphics, a
transition in progress. The output is never cut and nothing new is taken. If the output was in black it stays in
black. The item on air no longer belongs to the rundown:
program.indexis-1whileprogram.itemId/titlestill name it (in black,itemIdis null). Its end action Next holds it (on its last frame, or the still stays) instead of taking an item of the new rundown; Black still goes to black at its end; a loop goes on looping. When the new rundown contains that very item (the same file loaded again: same ids), it is that item, at itsindex, and the rundown goes on from it. - The operator's (or the client's) next take, Next or a scheduled start then plays the new rundown: Next takes its first item not skipped.
- Graphics of the rundown: those of the previous rundown go off; those of the new one marked On when the rundown
opens come on, the others are off. Several
outputsevents can arrive in a row while this happens. - Scheduled start: kept as it was (a load neither sets nor cancels it); at its time it starts the new rundown from the top.
- Not changed: the default transition, the recording (and its schedule), the stream, NDI, the SRT inputs.
Events of a load, in this order (§9): rundown, program, one or more outputs, openRundown, then the result.
Graphics (the rundown's graphics: logo, clock, crawl…)
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
graphics |
— | Graphic array (id, name, kind, on) |
— | GET /api/graphics |
graphicOn, graphicOff, graphicToggle |
graphicId required |
Graphic array | No graphic <id> in the rundown. (404) |
POST /api/graphics/{id}/on / off / toggle |
allGraphicsOn, allGraphicsOff |
— | Graphic array | — | POST /api/graphics/all/on / off |
Switching uses each graphic's own fade. Editing a graphic (text, position, opacity, speed…) and the graphics that belong to an item (they follow the item on air): NOT IMPLEMENTED remotely.
Outputs
| Action | Arguments | data |
Errors | REST |
|---|---|---|---|---|
recordStart, recordStop |
— | Recording | reason (409), e.g. the folder is not writable | POST /api/recording/start / stop, GET /api/recording |
recordingSchedule |
— | Recording schedule | — | GET /api/recording/schedule |
setRecordingSchedule |
mode required (Manual / Rundown / Window / Duration), start + stop (Window: times of day or ISO 8601), length (Duration: seconds, ≤ 7 days) |
Recording schedule | 400 for wrong values; 409 when Duration cannot start recording |
PUT /api/recording/schedule |
streamStart, streamStop |
— | Stream | reason (409), e.g. no address set | POST /api/stream/start / stop, GET /api/stream |
ndiOn, ndiOff |
— | NDI output | reason (409), e.g. NDI runtime missing | POST /api/ndi/on / off, GET /api/ndi |
The program output itself (DeckLink or the software clock) is read in status.output (§7); choosing the output, the
video mode, the full-screen monitor output and the sound card: NOT IMPLEMENTED remotely (Settings at the PC).
Audio
The item's volume is updateItem → gainDb (§6). Peak levels of every program channel arrive in time.levelsDb.
A master / output volume, mute, and the audio routing: NOT IMPLEMENTED (not in Fantareel).
Other (REST only)
| REST | |
|---|---|
GET /api/items/{id} |
one Item |
GET /api/license |
Licence |
GET /api/update, POST /api/update/check, POST /api/update/download |
Updates (installing is done at the PC: Windows asks for permission) |
Confirmations
Nothing sent remotely asks the operator anything: every command is carried out at once. In the GUI only these ask
first: deleting several items at once (removeItem deletes one, without asking), opening / creating a rundown when
the current one has unsaved changes (loadRundown refuses with 409 instead, unless discardChanges), and installing an
update (not possible remotely). Take, Next, Black, Fade to Black and the outputs never ask, in the GUI or remotely.
The GUI follows every remote change live (rundown list, program, buttons).
6. Continuous values (faders, knobs, dials)
| Parameter | Command | Range, unit, step | Absolute / relative |
|---|---|---|---|
| Item volume | updateItem gainDb |
−60…+20 dB, rounded to 0.5 dB, out-of-range values clamped | absolute only |
| Position in the clip on air (jog / shuttle) | seek position |
0…clip length, seconds, any precision (lands on a frame) | absolute only |
| Default transition length | setTransition durationMs |
> 0 ms (the GUI offers up to a few seconds) | absolute only |
| Fade to black length | fadeToBlack durationMs |
> 0 ms | per command |
| Item fade length | updateItem transitionMs |
> 0 ms | absolute only |
| Marks, display time | updateItem markIn / markOut / displayTime |
seconds | absolute only |
Relative steps (+1 dB, −1 s): NOT IMPLEMENTED — the client keeps the current value (from the rundown event
or time) and sends the new absolute one. Graphic opacity, crawl speed, master volume: NOT IMPLEMENTED remotely.
Rate. There is no server-side limit or coalescing. Each updateItem re-publishes the item, which sends a full
rundown event (every item) and a program event to every client and refreshes the GUI. Recommended: coalesce in the
client and send at most 10–15 changes per second per control (latest value wins), plus the final value when the
control stops. seek: at most one per output frame (25 / s at 50i), less is better.
7. State and events
Complete state
Sent by Fantareel on connect, and the data of getState:
{"type":"state",
"status": {"program":{…},"time":{…},"transition":{…},"output":{…},"itemCount":3,"repeat":{…},"schedule":{…}},
"items": [ …Item, in rundown order ],
"inputs": [ …SRT input ],
"outputs": {"type":"outputs","graphics":[…],"recording":{…},"recordingSchedule":{…},"stream":{…},"ndi":{…}},
"rundowns": [ …Rundown of the rundown folder, by path ],
"openRundown": {"name":"News evening","path":"News/News evening.frl","unsaved":false},
"selection": {"itemId":"f12196fd-…","index":4,"count":1}}
selection is null when nothing is selected in the rundown list (§5, Selection).
- On air:
status.program={index, itemId, title, kind, paused};index−1 and nulls in black. - Cue / preview: there is no preview channel. A cued item is on air and
paused: true. - Rundown:
items(each withstatus:Planned/OnAir/Sent/Skipped,onAir,skip),repeat,schedule;openRundown(its name, its path in the rundown folder, unsaved changes);rundowns, the rundowns that can be loaded. - Outputs:
status.output= the program output:{name, mode, framesOutput, framesLate, framesDropped, fault}(namee.g."DeckLink Duo 2 (1)"or"Preview (no card)";faulta message when the card has a problem);outputs= graphics, recording, recording schedule, stream, NDI. - Errors:
status.output.fault, and theproblemof recording / stream / NDI. A general error list or log of the operator's messages: NOT IMPLEMENTED. outputs.recording/stream/ndi/recordingScheduleandopenRundownarenull(andrundownsempty) only on a server without the GUI (as in the first recording of §9); in Fantareel they are always filled.
Events
type |
Sent when | Content | Rate |
|---|---|---|---|
program |
the program changes: take, cue, next / previous, black, fade to black (at its start), pause / resume, restart, an end action, a scheduled start; also when the item on air is edited or moved (its index may change) |
{program, time} |
on change |
rundown |
items added, removed, moved, edited, skipped, set planned; an item's status changes (goes on air, becomes sent); a rundown loaded; repeat changed; a new pass | {items: [all], repeat} — always the whole list |
on change |
time |
while the timing or the audio levels change | {time: {position, duration, remaining, markIn, markOut, paused, levelsDb}} |
every ?time= ms (default 100, minimum 20, 0 = never), only when different from the last one sent: continuous while a clip plays or a timed still counts down; silent when paused, in black, or on a still without display time |
outputs |
a graphic of the rundown switched on / off, or the rundown's graphics changed; recording or stream started / stopped / connected; recording schedule changed; NDI switched, its receivers or tally changed | {graphics, recording, recordingSchedule, stream, ndi} |
on change |
schedule |
a start scheduled, changed, cancelled or reached | {schedule: {at, startsIn}} |
on change (count down from at yourself) |
startedInTime |
an item went on air by itself at its start time (startAt); program and rundown follow |
{itemId, title, at: "HH:mm:ss"} |
when it happens |
inputs |
an SRT input changes state, message or format, or is added / edited | {inputs: [all]} |
checked every 1 s, sent on change |
rundowns |
a rundown of the rundown folder added, deleted, renamed, moved or saved (a subfolder too); the folder changed in the settings | {rundowns: [all, by path]} |
on change, within about a second |
openRundown |
another rundown opened (remotely or at the PC), new or closed; saved (also under another name); its first unsaved change | {openRundown: {name, path, unsaved}} |
on change, once per load |
selection |
the selection of the rundown list changes: select / moveSelection from any client, the operator (click, arrows, Ctrl / Shift), the selected item deleted or moved, a rundown loaded |
{selection: {itemId, index, count}} or {selection: null} |
on change (a move that stops at an end sends none) |
Not sent as events (NOT IMPLEMENTED): a dedicated item ended event (an end action Next or Black shows as a
program event; Hold shows as time.remaining reaching 0 and the time messages stopping); the output's fault and frame counters (read status via getState / GET /api/status;
poll every few seconds if needed); the recording's growing duration (read GET /api/recording); DeckLink card
presence / signal; error messages.
remaining is the time to the end action (to the mark out when set). elapsed is not a field: it is
position − (markIn ?? 0).
8. Lists for menus
| List | How to get it | Display name | Changed when |
|---|---|---|---|
| Rundown items | state.items, rundown event, GET /api/rundown |
title (+ kind, index) |
rundown event (the whole list again) |
| Graphics of the rundown | state.outputs.graphics, graphics action, GET /api/graphics |
name (+ kind) |
outputs event |
| SRT inputs | state.inputs, getInputs, GET /api/inputs |
name |
inputs event |
| Outputs | fixed: program (status.output), recording, stream, NDI |
— | outputs event |
| Wipe shapes | fixed list in §5 | — | — |
| Rundowns that can be loaded | state.rundowns, listRundowns, GET /api/rundowns |
name (+ path for the folder, modified) |
rundowns event (the whole list again) |
| The rundown open | state.openRundown, openRundown, GET /api/rundown/open |
name (unsaved for a mark) |
openRundown event |
| The selected item (a cursor over the item list) | state.selection, selection, GET /api/selection |
the item's title, from the items |
selection event |
9. Recorded session
Recorded on 2026-10-28 against the real server code (RemoteServer, PlayoutEngine, the software output, FFmpeg
decoding three small test files), driven by a test program instead of the GUI — so outputs is empty and graphics
would answer 503 there; in Fantareel they carry the graphics, recording, stream and NDI. Server started with API key
demo-key, the client asked for time=500. The messages are copied from the log; the only change is the media folder,
shortened to D:\Show. [s] is the time since the start, → sent, ← received.
The rundown (Opening clip with end action Next, Lower third still for 3 s, Report clip) was saved and opened again
first:
[ 0.169] ids after save + open: Opening same, Lower third same, Report same
REST: discovery, a missing key, loading a rundown:
[ 0.476] HTTP GET / (no key)
[ 0.477] -> 200 {"name":"FantaReel","version":"0.1.9","api":"/api/status","websocket":"/ws?time=100"}
[ 0.484] HTTP GET /api/status (no key)
[ 0.484] -> 401 {"error":"Missing or wrong API key (header X-Api-Key, or ?apiKey= for WebSockets)."}
[ 0.512] HTTP POST /api/rundown/load {"path":"D:\\Show\\News.frl"}
[ 0.512] -> 200 [{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":2,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}]
WebSocket: connect and initial state:
[ 0.528] WS connected ws://localhost:18088/ws?time=500&apiKey=demo-key
[ 0.547] ← {"type":"state","status":{"program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]},"transition":{"kind":"Cut","durationMs":0,"wipe":null},"output":{"name":"Preview (no card)","mode":"1080i 50","framesOutput":9,"framesLate":0,"framesDropped":0,"fault":null},"itemCount":3,"repeat":{"mode":"Once","times":1,"pass":1},"schedule":{"at":null,"startsIn":null}},"items":[{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":2,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"inputs":[],"outputs":{"type":"outputs","graphics":[],"recording":null,"recordingSchedule":null,"stream":null,"ndi":null}}
Take by id (program, then rundown with the new statuses, then the result), then the volume (−6 dB) of the item on
air:
[ 1.030] → {"id":"1","action":"take","itemId":"937b9bc9-44fc-4d89-a2af-c4fada300b0a"}
[ 1.036] ← {"type":"program","program":{"index":0,"itemId":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","title":"Opening","kind":"Video","paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 1.037] ← {"type":"rundown","items":[{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":2,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 1.038] ← {"type":"result","id":"1","ok":true,"data":null}
[ 1.048] ← {"type":"time","time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 1.431] → {"id":"2","action":"updateItem","itemId":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","gainDb":-6}
[ 1.437] ← {"type":"rundown","items":[{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":2,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 1.437] ← {"type":"program","program":{"index":0,"itemId":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","title":"Opening","kind":"Video","paused":false},"time":{"position":0.36,"duration":1,"remaining":0.64,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-21,-21]}}
[ 1.437] ← {"type":"result","id":"2","ok":true,"data":{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false}}
[ 1.549] ← {"type":"time","time":{"position":0.48,"duration":1,"remaining":0.52,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-26.9,-26.9]}}
Reorder: Report moved to the top. Ids stay, indexes change, the item on air goes from index 0 to 1:
[ 1.732] → {"id":"3","action":"moveItem","itemId":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":0}
[ 1.733] ← {"type":"rundown","items":[{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":0,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":1,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":2,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 1.733] ← {"type":"program","program":{"index":1,"itemId":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","title":"Opening","kind":"Video","paused":false},"time":{"position":0.64,"duration":1,"remaining":0.36,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-26.9,-26.9]}}
[ 1.733] ← {"type":"result","id":"3","ok":true,"data":null}
Errors: an index that does not exist; then, while the clip ends by itself and its end action Next takes Lower third,
an id that does not exist and an unknown action:
[ 2.033] → {"id":"4","action":"take","index":7}
[ 2.036] ← {"type":"result","id":"4","ok":false,"error":"No item at index 7 (the rundown has 3)."}
[ 2.048] ← {"type":"time","time":{"position":0.96,"duration":1,"remaining":0.04,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-26.9,-26.9]}}
[ 2.067] ← {"type":"program","program":{"index":2,"itemId":"13618658-0b5e-4a9d-984c-132a84569a77","title":"Lower third","kind":"Image","paused":false},"time":{"position":0.96,"duration":1,"remaining":0.04,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-26.9,-26.9]}}
[ 2.067] ← {"type":"rundown","items":[{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":0,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":1,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Sent","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":2,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 2.334] → {"id":"5","action":"take","itemId":"f1f91a4b-8e97-42e3-8011-8c8743440329"}
[ 2.335] ← {"type":"result","id":"5","ok":false,"error":"No item f1f91a4b-8e97-42e3-8011-8c8743440329 in the rundown."}
[ 2.549] ← {"type":"time","time":{"position":0.44,"duration":3,"remaining":2.56,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 2.634] → {"id":"6","action":"jump"}
[ 2.635] ← {"type":"result","id":"6","ok":false,"error":"Unknown action \u0022jump\u0022."}
The still counts down (time every 500 ms, only while it changes; after remaining 0 they stop), then a fade to black
and getState with a numeric id (echoed as a string):
[ 3.049] ← {"type":"time","time":{"position":0.92,"duration":3,"remaining":2.08,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 3.547] ← {"type":"time","time":{"position":1.44,"duration":3,"remaining":1.56,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 4.047] ← {"type":"time","time":{"position":1.92,"duration":3,"remaining":1.08,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 4.548] ← {"type":"time","time":{"position":2.44,"duration":3,"remaining":0.56,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 5.049] ← {"type":"time","time":{"position":2.92,"duration":3,"remaining":0.08,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 5.548] ← {"type":"time","time":{"position":3,"duration":3,"remaining":0,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 5.935] → {"id":"7","action":"fadeToBlack","durationMs":500}
[ 5.936] ← {"type":"program","program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":3,"duration":3,"remaining":0,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 5.936] ← {"type":"result","id":"7","ok":true,"data":null}
[ 6.048] ← {"type":"time","time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 7.136] → {"id":8,"action":"getState"}
[ 7.137] ← {"type":"result","id":"8","ok":true,"data":{"type":"state","status":{"program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]},"transition":{"kind":"Cut","durationMs":0,"wipe":null},"output":{"name":"Preview (no card)","mode":"1080i 50","framesOutput":174,"framesLate":0,"framesDropped":0,"fault":null},"itemCount":3,"repeat":{"mode":"Once","times":1,"pass":1},"schedule":{"at":null,"startsIn":null}},"items":[{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":0,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":1,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Sent","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":2,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Sent","skip":false}],"inputs":[],"outputs":{"type":"outputs","graphics":[],"recording":null,"recordingSchedule":null,"stream":null,"ndi":null}}}
Closing, and REST again (an error status, the list):
[ 7.638] → (close frame, normal closure)
[ 7.656] WS close: OperationCanceledException: The remote party closed the WebSocket connection without completing the close handshake.
[ 7.661] HTTP POST /api/playout/take/9
[ 7.661] -> 404 {"error":"No item at index 9 (the rundown has 3)."}
[ 7.663] HTTP GET /api/rundown
[ 7.663] -> 200 [{"id":"c9ddc4de-6881-45a2-8582-d8ee96492156","index":0,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"937b9bc9-44fc-4d89-a2af-c4fada300b0a","index":1,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":-6,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Sent","skip":false},{"id":"13618658-0b5e-4a9d-984c-132a84569a77","index":2,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":3,"mediaDuration":3,"onAir":false,"transition":null,"liveInputId":null,"status":"Sent","skip":false}]
Rundown folder and loading
Recorded on 2026-10-29 with Fantareel itself (the application, no DeckLink card: the software output), remote control
on port 8088 without a key, the client on the same PC asking for time=0 (no timing messages). The rundown folder held
Morning.frl (one clip) and News/News evening.frl (the Opening clip, the Lower third still, and a Clock graphic
of the rundown marked On when the rundown opens). The messages are copied from the log; the only change is the media
folder, shortened to D:\Show.
Connect: the state ends with rundowns and openRundown (nothing saved open yet):
[ 1.107] HTTP GET /
[ 1.164] → {"name":"FantaReel","version":"0.1.9","api":"/api/status","websocket":"/ws?time=100"}
[ 1.173] WS connected ws://localhost:8088/ws?time=0
[ 1.175] ← {"type":"state","status":{"program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]},"transition":{"kind":"Wipe","durationMs":500,"wipe":"Clock"},"output":{"name":"Preview (no card)","mode":"1080i 50","framesOutput":350,"framesLate":0,"framesDropped":0,"fault":null},"itemCount":0,"repeat":{"mode":"Once","times":1,"pass":1},"schedule":{"at":null,"startsIn":null}},"items":[],"inputs":[],"outputs":{"type":"outputs","graphics":[],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}},"rundowns":[{"name":"Morning","path":"Morning.frl","modified":"2026-10-29T00:15:14.6076636\u002B01:00"},{"name":"News evening","path":"News/News evening.frl","modified":"2026-10-29T00:15:14.6066401\u002B01:00"}],"openRundown":{"name":"Untitled","path":null,"unsaved":false}}
Load News/News evening.frl: the items, the program (in black, it stays so), the rundown's graphics (Clock arrives,
then comes on by itself), the open rundown, then the result:
[ 1.974] → {"id":"1","action":"loadRundown","rundown":"News/News evening.frl"}
[ 2.064] ← {"type":"rundown","items":[{"id":"ab7efe45-c9f2-4edc-a152-8d571bfbc38f","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"3f2ce067-9d84-4440-8d61-9c94cc761e77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 2.064] ← {"type":"program","program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 2.066] ← {"type":"outputs","graphics":[],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}}
[ 2.068] ← {"type":"outputs","graphics":[{"id":"80eb4d71-71e0-4c1a-ac8a-17bd1554c473","name":"Clock","kind":"Clock","on":false}],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}}
[ 2.070] ← {"type":"outputs","graphics":[{"id":"80eb4d71-71e0-4c1a-ac8a-17bd1554c473","name":"Clock","kind":"Clock","on":true}],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}}
[ 2.088] ← {"type":"openRundown","openRundown":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
[ 2.093] ← {"type":"result","id":"1","ok":true,"data":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
The still goes on air; then a remote edit gives the rundown unsaved changes (openRundown with unsaved: true):
[ 3.175] → {"id":"2","action":"take","index":1}
[ 3.177] ← {"type":"program","program":{"index":1,"itemId":"3f2ce067-9d84-4440-8d61-9c94cc761e77","title":"Lower third","kind":"Image","paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 3.177] ← {"type":"rundown","items":[{"id":"ab7efe45-c9f2-4edc-a152-8d571bfbc38f","index":0,"title":"Opening","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"3f2ce067-9d84-4440-8d61-9c94cc761e77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 3.177] ← {"type":"result","id":"2","ok":true,"data":null}
[ 3.884] → {"id":"3","action":"updateItem","itemId":"ab7efe45-c9f2-4edc-a152-8d571bfbc38f","title":"Opening (new cut)"}
[ 3.888] ← {"type":"rundown","items":[{"id":"ab7efe45-c9f2-4edc-a152-8d571bfbc38f","index":0,"title":"Opening (new cut)","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false},{"id":"3f2ce067-9d84-4440-8d61-9c94cc761e77","index":1,"title":"Lower third","kind":"Image","filePath":"D:\\Show\\Lower third.jpg","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":true,"transition":null,"liveInputId":null,"status":"OnAir","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 3.888] ← {"type":"program","program":{"index":1,"itemId":"3f2ce067-9d84-4440-8d61-9c94cc761e77","title":"Lower third","kind":"Image","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 3.888] ← {"type":"openRundown","openRundown":{"name":"News evening","path":"News/News evening.frl","unsaved":true}}
[ 3.888] ← {"type":"result","id":"3","ok":true,"data":{"id":"ab7efe45-c9f2-4edc-a152-8d571bfbc38f","index":0,"title":"Opening (new cut)","kind":"Video","filePath":"D:\\Show\\Opening.mp4","color":null,"endAction":"Next","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":1,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}}
Refused: unsaved changes, .., an absolute path, the former path argument:
[ 4.584] → {"id":"4","action":"loadRundown","rundown":"Morning.frl"}
[ 4.587] ← {"type":"result","id":"4","ok":false,"error":"The open rundown has unsaved changes (\u0022News evening\u0022): save it, or load with \u0022discardChanges\u0022: true."}
[ 5.285] → {"id":"5","action":"loadRundown","rundown":"../../Desktop/show.frl"}
[ 5.285] ← {"type":"result","id":"5","ok":false,"error":"\u0022../../Desktop/show.frl\u0022: \u0022..\u0022 is not accepted, the rundown must be in the rundown folder."}
[ 5.986] → {"id":"6","action":"loadRundown","rundown":"C:\\Users\\Public\\show.frl"}
[ 5.986] ← {"type":"result","id":"6","ok":false,"error":"\u0022C:\\Users\\Public\\show.frl\u0022: only paths relative to the rundown folder are accepted."}
[ 6.687] → {"id":"7","action":"loadRundown","path":"C:\\Shows\\show.frl"}
[ 6.687] ← {"type":"result","id":"7","ok":false,"error":"\u0022path\u0022 is no longer accepted: give \u0022rundown\u0022, the path relative to the rundown folder (listRundowns)."}
A rundown saved into the folder (News/Late news.frl, by another program): the rundowns event:
[ 7.638] ← {"type":"rundowns","rundowns":[{"name":"Morning","path":"Morning.frl","modified":"2026-10-29T00:15:14.6076636\u002B01:00"},{"name":"Late news","path":"News/Late news.frl","modified":"2026-10-29T00:15:21.8978283\u002B01:00"},{"name":"News evening","path":"News/News evening.frl","modified":"2026-10-29T00:15:14.6066401\u002B01:00"}]}
Load Morning.frl discarding the changes. The still stays on air (program.index −1, itemId / title still
Lower third), Clock goes off and the graphics of Morning (none) replace it, the open rundown is Morning, saved;
then the list:
[ 8.889] → {"id":"8","action":"loadRundown","rundown":"Morning.frl","discardChanges":true}
[ 8.893] ← {"type":"rundown","items":[{"id":"1d045151-e39a-4358-aa7f-37593d534bd9","index":0,"title":"Report","kind":"Video","filePath":"D:\\Show\\Report.mp4","color":null,"endAction":"Hold","loop":false,"gainDb":0,"markIn":null,"markOut":null,"displayTime":null,"mediaDuration":null,"onAir":false,"transition":null,"liveInputId":null,"status":"Planned","skip":false}],"repeat":{"mode":"Once","times":1,"pass":1}}
[ 8.893] ← {"type":"program","program":{"index":-1,"itemId":"3f2ce067-9d84-4440-8d61-9c94cc761e77","title":"Lower third","kind":"Image","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 8.893] ← {"type":"outputs","graphics":[{"id":"80eb4d71-71e0-4c1a-ac8a-17bd1554c473","name":"Clock","kind":"Clock","on":false}],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}}
[ 8.893] ← {"type":"outputs","graphics":[],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}}
[ 8.894] ← {"type":"openRundown","openRundown":{"name":"Morning","path":"Morning.frl","unsaved":false}}
[ 8.894] ← {"type":"result","id":"8","ok":true,"data":{"name":"Morning","path":"Morning.frl","unsaved":false}}
[10.389] → {"id":"9","action":"listRundowns"}
[10.390] ← {"type":"result","id":"9","ok":true,"data":[{"name":"Morning","path":"Morning.frl","modified":"2026-10-29T00:15:14.6076636\u002B01:00"},{"name":"Late news","path":"News/Late news.frl","modified":"2026-10-29T00:15:21.8978283\u002B01:00"},{"name":"News evening","path":"News/News evening.frl","modified":"2026-10-29T00:15:14.6066401\u002B01:00"}]}
Selection
Recorded on 2026-10-29 with Fantareel itself (software output, remote control on port 8088 without a key,
time=0), the rundown News/News evening.frl: 0 Opening (clip), 1 Headlines (color), 2 Lower third (still),
3 Report (clip), 4 Weather (color). The messages are copied from the log; the rundown and outputs events (the
whole item list, the outputs) are left out where marked (left out), and the media folder is shortened to D:\Show.
Connect (selection: null) and load:
[ 1.160] WS connected ws://localhost:8088/ws?time=0
[ 1.172] ← {"type":"state","status":{"program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]},"transition":{"kind":"Wipe","durationMs":500,"wipe":"Clock"},"output":{"name":"Preview (no card)","mode":"1080i 50","framesOutput":338,"framesLate":0,"framesDropped":0,"fault":null},"itemCount":0,"repeat":{"mode":"Once","times":1,"pass":1},"schedule":{"at":null,"startsIn":null}},"items":[],"inputs":[],"outputs":{"type":"outputs","graphics":[],"recording":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"recordingSchedule":{"mode":"Manual","start":null,"stop":null,"length":null},"stream":{"active":false,"state":"Off","target":null,"duration":null,"problem":null},"ndi":{"active":false,"state":"Off","name":"FantaReel","groups":null,"receivers":0,"onProgram":false,"onPreview":false,"problem":null}},"rundowns":[{"name":"Morning","path":"Morning.frl","modified":"2026-10-29T00:51:02.5607490\u002B01:00"},{"name":"News evening","path":"News/News evening.frl","modified":"2026-10-29T00:51:02.5597493\u002B01:00"}],"openRundown":{"name":"Untitled","path":null,"unsaved":false},"selection":null}
[ 1.769] → {"id":"1","action":"loadRundown","rundown":"News/News evening.frl","discardChanges":true}
[ 1.842] ← {"type":"rundown",…} (left out)
[ 1.842] ← {"type":"program","program":{"index":-1,"itemId":null,"title":null,"kind":null,"paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 1.843] ← {"type":"outputs",…} (left out)
[ 1.843] ← {"type":"outputs",…} (left out)
[ 1.860] ← {"type":"openRundown","openRundown":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
[ 1.864] ← {"type":"result","id":"1","ok":true,"data":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
select by index, then a knob turned six detents down at 25 a second: it stops at the last item (the three last moves
answer Weather again, without an event):
[ 2.969] → {"id":"2","action":"select","index":1}
[ 2.977] ← {"type":"selection","selection":{"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","index":1,"count":1}}
[ 2.978] ← {"type":"result","id":"2","ok":true,"data":{"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","index":1,"count":1}}
[ 3.570] → {"id":"3","action":"moveSelection","steps":1}
[ 3.573] ← {"type":"selection","selection":{"itemId":"0986c783-9544-4da7-b429-c0f9c8fc449c","index":2,"count":1}}
[ 3.574] ← {"type":"result","id":"3","ok":true,"data":{"itemId":"0986c783-9544-4da7-b429-c0f9c8fc449c","index":2,"count":1}}
[ 3.610] → {"id":"4","action":"moveSelection","steps":1}
[ 3.612] ← {"type":"selection","selection":{"itemId":"b9fa0a4a-4650-419f-a2b1-485a9b921746","index":3,"count":1}}
[ 3.612] ← {"type":"result","id":"4","ok":true,"data":{"itemId":"b9fa0a4a-4650-419f-a2b1-485a9b921746","index":3,"count":1}}
[ 3.651] → {"id":"5","action":"moveSelection","steps":1}
[ 3.652] ← {"type":"selection","selection":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":4,"count":1}}
[ 3.652] ← {"type":"result","id":"5","ok":true,"data":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":4,"count":1}}
[ 3.692] → {"id":"6","action":"moveSelection","steps":1}
[ 3.693] ← {"type":"result","id":"6","ok":true,"data":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":4,"count":1}}
[ 3.732] → {"id":"7","action":"moveSelection","steps":1}
[ 3.733] ← {"type":"result","id":"7","ok":true,"data":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":4,"count":1}}
[ 3.772] → {"id":"8","action":"moveSelection","steps":1}
[ 3.773] ← {"type":"result","id":"8","ok":true,"data":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":4,"count":1}}
takeSelected:
[ 4.413] → {"id":"9","action":"takeSelected"}
[ 4.416] ← {"type":"program","program":{"index":4,"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","title":"Weather","kind":"SolidColor","paused":false},"time":{"position":null,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 4.416] ← {"type":"rundown",…} (left out)
[ 4.416] ← {"type":"result","id":"9","ok":true,"data":null}
At the PC, a real mouse click on row 1 (Headlines): the selection event arrives, and the click also takes it (the
program event). Then a knob detent up moves from there:
[ 6.544] ← {"type":"selection","selection":{"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","index":1,"count":1}}
[ 6.604] ← {"type":"program","program":{"index":1,"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","title":"Headlines","kind":"SolidColor","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 6.604] ← {"type":"rundown",…} (left out)
[ 6.827] PC: clicked row 1 at 2624,840 (5 rows)
[ 7.627] → {"id":"10","action":"moveSelection","steps":-1}
[ 7.628] ← {"type":"selection","selection":{"itemId":"a91a0f5d-66c1-4d33-b790-01dcf7394ac1","index":0,"count":1}}
[ 7.628] ← {"type":"result","id":"10","ok":true,"data":{"itemId":"a91a0f5d-66c1-4d33-b790-01dcf7394ac1","index":0,"count":1}}
The selected item deleted (Report, index 3): the selection goes to the item now in its place (Weather, index 3).
Then another rundown loaded: nothing selected, and takeSelected says so:
[ 8.227] → {"id":"11","action":"select","index":3}
[ 8.228] ← {"type":"selection","selection":{"itemId":"b9fa0a4a-4650-419f-a2b1-485a9b921746","index":3,"count":1}}
[ 8.228] ← {"type":"result","id":"11","ok":true,"data":{"itemId":"b9fa0a4a-4650-419f-a2b1-485a9b921746","index":3,"count":1}}
[ 8.837] → {"id":"12","action":"removeItem","itemId":"b9fa0a4a-4650-419f-a2b1-485a9b921746"}
[ 8.838] ← {"type":"rundown",…} (left out)
[ 8.838] ← {"type":"program","program":{"index":1,"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","title":"Headlines","kind":"SolidColor","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 8.838] ← {"type":"result","id":"12","ok":true,"data":null}
[ 8.838] ← {"type":"openRundown","openRundown":{"name":"News evening","path":"News/News evening.frl","unsaved":true}}
[ 8.842] ← {"type":"selection","selection":{"itemId":"f12196fd-5383-4578-97de-d9c1716fe819","index":3,"count":1}}
[ 9.638] → {"id":"13","action":"loadRundown","rundown":"Morning.frl","discardChanges":true}
[ 9.644] ← {"type":"selection","selection":null}
[ 9.644] ← {"type":"rundown",…} (left out)
[ 9.644] ← {"type":"program","program":{"index":-1,"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","title":"Headlines","kind":"SolidColor","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[ 9.644] ← {"type":"outputs",…} (left out)
[ 9.644] ← {"type":"outputs",…} (left out)
[ 9.646] ← {"type":"openRundown","openRundown":{"name":"Morning","path":"Morning.frl","unsaved":false}}
[ 9.646] ← {"type":"result","id":"13","ok":true,"data":{"name":"Morning","path":"Morning.frl","unsaved":false}}
[10.838] → {"id":"14","action":"takeSelected"}
[10.840] ← {"type":"result","id":"14","ok":false,"error":"No item is selected in the rundown."}
The knob test: the rundown loaded again, then 200 moveSelection (±1 to ±3) every 40 ms, and 200 sent at once; the
results and the selection events were counted, not printed:
[11.439] → {"id":"15","action":"loadRundown","rundown":"News/News evening.frl","discardChanges":true}
[11.441] ← {"type":"rundown",…} (left out)
[11.441] ← {"type":"program","program":{"index":1,"itemId":"12a73ede-e00c-4351-aa8d-face157e736b","title":"Headlines","kind":"SolidColor","paused":false},"time":{"position":0,"duration":null,"remaining":null,"markIn":null,"markOut":null,"paused":false,"levelsDb":[-120,-120]}}
[11.441] ← {"type":"outputs",…} (left out)
[11.441] ← {"type":"outputs",…} (left out)
[11.443] ← {"type":"openRundown","openRundown":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
[11.494] ← {"type":"result","id":"15","ok":true,"data":{"name":"News evening","path":"News/News evening.frl","unsaved":false}}
[12.444] status before: framesLate 1, framesDropped 0
[20.547] 200 moveSelection every 40 ms: 200 results, in order: True, answer after 1.0 ms (median), 3.4 ms (slowest), all in 8.10 s
[20.651] 200 moveSelection at once: 200 results, in order: True, answer after 44.0 ms (median), 87.5 ms (slowest), all in 0.10 s
[20.651] selection events during the knob: 400
[20.652] status after: framesLate 1, framesDropped 0
10. Testing without a DeckLink card
- No card needed. Without a DeckLink card (or without Desktop Video) Fantareel uses its software clock output,
"Preview (no card)", 1080i 50 by default: the whole engine runs, the program shows in the window, and it can also go full screen on a monitor (Playout › Screen output), be recorded, streamed or sent as NDI. Any Windows 10 / 11 x64 PC will do; without a licence the program carries a watermark, nothing else changes. - On the Fantareel PC: Settings › Remote control → tick Enable remote control, port
8088(or another), choose From the network, optionally set an API key, set the Rundown folder (the rundowns a client may list and load), OK. The same page lists the addresses to use. - Windows Firewall: inbound TCP on the chosen port must be allowed.
- Installed Fantareel: the setup option Allow remote control, SRT listeners and NDI receivers from the network through Windows Firewall adds a program rule for Fantareel.exe (private and domain networks; the PC's network must then be Private, not Public). Otherwise Windows asks on the first start with From the network — answer Allow for private networks.
- Any build (also one run from Visual Studio /
dotnet run, whose exe is not the installed one), from an administrator prompt:netsh advfirewall firewall add rule name="FantaReel remote control" dir=in action=allow protocol=TCP localport=8088 profile=private,domain
- From the Linux server:
curl http://<fantareel-pc>:8088/(should answer{"name":"FantaReel",…}without a key), thencurl -H "X-Api-Key: <key>" http://<fantareel-pc>:8088/api/status, and a WebSocket, e.g.websocat "ws://<fantareel-pc>:8088/ws?time=500&apiKey=<key>"then type{"id":"1","action":"getState"}. Ifcurltimes out: firewall or network profile; if it is refused: remote control off, Only from this PC, or another port. The status bar of Fantareel showsremote :8088 (n live)with the number of WebSocket clients.
Fantareel remote control API
Fantareel can be driven by a control system over HTTP (REST) and followed in real time over a WebSocket. Enable it in Settings › Remote control:
| Setting | Meaning |
|---|---|
| Port | TCP port of both the REST API and the WebSocket (default 8088). |
| Access | Only from this PC listens on localhost; From the network listens on every interface (Windows may ask to allow Fantareel through the firewall). |
| API key | Optional. When set, every request except GET / must carry it in the X-Api-Key header, or as ?apiKey= in the URL (useful for WebSocket clients that cannot set headers). A missing or wrong key gets 401. |
| Client name | Optional: X-Client: <name>/<version> header, or ?client=<name> in the URL. Changes no answer; a client named Fantago (or FantaCore) is counted in Fantareel's anonymous usage statistics. |
| Rundown folder | The rundowns (.frl, subfolders included) a client can list and load; no other file can be opened remotely. Default Documents\FantaReel\Rundowns, made at the first start. |
The status bar shows remote :<port> (<n> live), where n is the number of connected WebSocket clients.
Conventions
- JSON, camelCase property names. Enums are strings (
"Video","Next", …); string values sent to the API are case-insensitive. - Times are seconds (numbers with up to 3 decimals), except transition and fade durations, which are in milliseconds (
durationMs). - Items are addressed by index (0-based position in the rundown) or by id (a GUID that stays the same while the item is in the rundown, even when items are moved).
- CORS is open (any origin), so a browser page can call the API.
- Errors return a status code and
{"error": "message"}:400for a bad request, such as a missing field, a wrong value, or seeking when no clip is on air;401for a missing or wrong API key;404for an unknown item, an index out of range, or a file that is not found.
- Commands are queued to the playout engine and take effect on the next output frame (a take waits for a clip that is still loading). The state a command returns may be from just before the change; the WebSocket
programevent confirms it.
Data shapes
Item
{
"id": "6f1c…", "index": 2, "title": "Opening", "kind": "Video",
"filePath": "D:\\Media\\opening.mov", "color": null,
"endAction": "Next", "loop": false, "gainDb": -3,
"markIn": 1.5, "markOut": 12.0, "displayTime": null,
"mediaDuration": 14.24, "onAir": true, "transition": null, "liveInputId": null,
"status": "OnAir", "skip": false, "startAt": "18:30:00", "captureDevice": null, "audio": null
}
| Field | Meaning |
|---|---|
kind |
Video, Image, Audio (an audio file, played like a clip), SolidColor, TestPattern, Srt (a live SRT input), Capture (a video input: a DeckLink input, a camera or an NDI® source). |
filePath |
The media file (clips, images and audio files), otherwise null. |
color |
#RRGGBB for solid colors, otherwise null. |
endAction |
What happens at the end: Hold (stop on the last frame), Black, Next (take the next item). |
loop |
The clip loops between its marks (the end action is then Hold). |
gainDb |
Item volume, −60…+20 dB in 0.5 dB steps. |
markIn, markOut |
Marks in file time, null when not set. |
displayTime |
For stills: how long they stay on air before the end action; null means "until the next take". |
mediaDuration |
Length of a clip, once it has been loaded (otherwise null). For stills it equals displayTime. |
onAir |
This item is the one on air. |
transition |
The item's own transition into it, {"kind": "Fade", "durationMs": 1000} or {"kind": "Cut", …}; null = the default transition (/api/playout/transition). |
liveInputId |
For Srt items, the SRT input they show (see SRT input below); otherwise null. |
status |
Where the item stands in the show: Planned, OnAir, Sent (has been on air since the rundown was loaded) or Skipped. |
skip |
Set aside by the operator: Next, Previous and an end action Next go past it. It can still be taken by hand. |
startAt |
Start in time: the time of day (HH:mm:ss, local time of the Fantareel PC) when the item goes on air by itself, every day while the output runs, and the rundown goes on from it; null = only when taken. A skipped item does not start. |
captureDevice |
For Capture items, the video input: decklink:…, dshow:… (a camera) or ndi: + the NDI name of the source (PC (source)); otherwise null. |
audio |
For Audio items: {"visual": "Spectrum" | "Waveform" | "Black", "caption": "TrackTitle" | "FileName" | "None", "trackTitle": "Artist – Title" or null} — the picture drawn from the sound, the text shown over it (the track title comes from the file's tags; without them, the file name); otherwise null. |
Graphic (a graphic of the rundown: logo, clock, ticker…)
{ "id": "0b7e…", "name": "Logo", "kind": "Image", "on": true }
kind is Text, Clock, Crawl, Image or Video. The graphics of an item come on and go off with it: they are not listed.
Recording / stream
{ "active": true, "state": "Recording", "target": "D:\\Recordings\\FantaReel 2026-10-24 21.00.00.mp4", "duration": 754.2, "problem": null }
state is Off, Recording (recording) or Connecting, Connected, Retrying (stream). target is the file or the SRT
address; duration the length recorded, or how long the stream receiver has been connected. Folder, format and address are
set in Fantareel's settings.
Recording schedule (when the recorder starts and stops by itself)
{ "mode": "Window", "start": "2026-10-28T18:00:00.0000000+01:00", "stop": "2026-10-28T19:30:00.0000000+01:00", "length": null }
mode |
The recorder… |
|---|---|
Manual |
…records only when told (REC button, /api/recording/start). |
Rundown |
…starts when the rundown starts (3 s before a scheduled start, so its first frame is in the file) and stops when the rundown stops: the program goes to black, or its last item is over with nothing to follow; the recording goes on for the transition plus 2 s. One file per run. A recording stopped by hand during a run is not started again until the next run; one started by hand is never stopped by it. |
Window |
…records from start to stop, once (a recording already running at start is taken over); then Manual. |
Duration |
…records from when it is set for length seconds (a recording already running goes on for that long); then Manual. |
Stopping by hand a recording of Window or Duration ends the schedule (back to Manual). The schedule is kept while
Fantareel runs, not saved.
NDI output
{ "active": true, "state": "On", "name": "FantaReel", "groups": null, "receivers": 2, "onProgram": true, "onPreview": false, "problem": null }
The program as an NDI® source (receivers list it as "PC NAME (name)"). state is Off, On, or Unavailable when it is
switched on but NDI cannot start (problem says why, e.g. the NDI runtime is missing). receivers is the number connected;
onProgram / onPreview the tally of the receivers. groups: null = the default group. Name and groups are set in
Fantareel's settings (Output); the source stays on across restarts. NDI® is a registered trademark of Vizrt NDI AB
(https://ndi.video/).
Licence
{ "licensed": true, "edition": "subscription", "customer": "Studio Uno", "expiresAt": "2027-05-10T00:00:00.0000000Z",
"updatesUntil": null, "problem": "None", "problemText": "", "machineId": "3F0A…", "releaseDate": "2026-10-27", "term": "yearly" }
edition is lifetime or subscription (null without a licence); term: a subscription's monthly or yearly (null when
the licence does not tell it). expiresAt: when a subscription ends (it renews by itself
while the computer reaches the Internet); updatesUntil: a lifetime licence opens the versions released until then. Unlicensed
(licensed false, the reason in problem / problemText), the program carries a watermark. The licence key is never given.
Activating is done in Fantareel (Help › Licence).
Update
{ "stage": "Available", "current": "0.1.0", "version": "0.2.0", "released": "2026-11-10", "notes": "What is new…",
"newest": null, "message": null, "progress": 0, "checkedAt": "2026-11-10T09:05:00.0000000Z" }
stage: Idle (not checked yet), Checking, UpToDate, Available, Downloading (progress from 0 to 1), Ready
(downloaded and checked), Failed (message says why). version is the newer version this computer may install;
newest a still newer one its licence does not open (a lifetime licence whose updates have ended: message says so).
Installing closes Fantareel and Windows asks to allow it, so it is done at the computer (Help › Check for updates).
Program (what is on air)
{ "index": 2, "itemId": "6f1c…", "title": "Opening", "kind": "Video", "paused": false }
index is -1 and the other fields are null when the output is in black.
Time (timing of the item on air)
{
"position": 4.32, "duration": 14.24, "remaining": 7.68,
"markIn": 1.5, "markOut": 12.0, "paused": false,
"levelsDb": [-18.2, -17.9]
}
| Field | Meaning |
|---|---|
position |
Current position in file time. |
duration |
Full length of the clip, or the display time of a still. |
remaining |
Time left until the end action (until the mark out, when there is one). |
markIn, markOut |
Marks of the item on air. |
levelsDb |
Peak level per program audio channel, in dBFS (−120 means silence). |
In black, all the timing fields are null. For a still without a display time, duration and remaining are null.
Status
{
"program": { … }, "time": { … },
"transition": { "kind": "Fade", "durationMs": 500 },
"output": { "name": "DeckLink Duo 2 (1)", "mode": "1080i 50", "framesOutput": 81234, "framesLate": 0, "framesDropped": 0, "fault": null },
"itemCount": 12,
"repeat": { "mode": "Times", "times": 3, "pass": 2 },
"schedule": { "at": "2026-10-28T18:00:00.0000000+01:00", "startsIn": 754.3 }
}
schedule is the scheduled start of the rundown (at and startsIn, in seconds, are null when none is set).
output.fault contains a message when the video output has a problem.
Rundown (a rundown of the rundown folder)
{ "name": "News evening", "path": "News/News evening.frl", "modified": "2026-10-29T00:15:14.6066401+01:00" }
path is relative to the rundown folder, with /: it is what loadRundown takes. modified: when the file was last saved.
Lists are sorted by path.
Selection (the selected item of the rundown list)
{ "itemId": "f12196fd-5383-4578-97de-d9c1716fe819", "index": 4, "count": 1 }
The one selection of Fantareel's rundown list, shared with the operator; null when nothing is selected. count > 1 only
when the operator selected several items (itemId is then the list's current one). See docs/remote-control.md, Selection.
Open rundown
{ "name": "News evening", "path": "News/News evening.frl", "unsaved": false }
name is "Untitled" and path null for a rundown never saved; path is also null for a file outside the rundown folder
(opened at the PC). unsaved: it has changes not saved yet.
Repeat (how many times the whole rundown plays)
{ "mode": "Times", "times": 3, "pass": 2 }
| Field | Meaning |
|---|---|
mode |
Once, Times or Loop. |
times |
How many times the rundown plays: 1 for Once, 2–999 for Times, 0 for Loop (for ever). |
pass |
The pass playing, from 1. |
Next after the last item (taken by hand or by an end action Next) starts the rundown again from the first item that is not skipped while passes are left: every item is planned again. Saved in the rundown file.
Audio bed (a sound under the whole program)
{ "set": true, "title": "Music bed", "file": "Music bed.mp3", "playing": true, "loop": true, "mode": "Only", "gainDb": -6,
"position": 83.42, "duration": 215.1, "problem": null }
| Field | Meaning |
|---|---|
set |
false when the rundown has no audio bed (the other fields are then empty). |
title, file |
The file's name without and with its extension (the file is chosen at the console only). |
playing |
It plays (started by the operator or remotely). Stopped, it fades out in 1 s and stays where it got to: playing again goes on from there. At its end (not looping) it stops and goes back to the start. |
loop |
At its end the file starts again with no gap. |
mode |
Mix: added to the items' audio. Only: while it plays the items' audio is faded out (in 1 s) and comes back when it stops. |
gainDb |
Its level, −60 to +12 dB. |
position, duration |
Seconds in the file (null while unknown). |
problem |
Why the file cannot be played, or null. |
The bed is added to channels 1-2 of the program (SDI, sound card, recording, stream, NDI alike), whatever is on air, black included. Its file, loop, mode and level are saved in the rundown file; whether it plays is not.
SRT input
The SRT inputs are configured in Fantareel (Settings › SRT inputs); the API reads them. An input connects while at least one rundown item uses it.
{
"id": "a41e…", "name": "Camera 1", "mode": "Listener", "address": "", "port": 9000, "latencyMs": 120,
"encrypted": true, "streamId": null, "audioTrack": "eng",
"state": "Connected", "message": "Receiving", "format": "1920×1080 25 fps · audio", "inUse": true,
"link": {
"peer": "10.0.0.9:51000", "connectedFor": 754, "latencyMs": 200, "encryption": "Secured",
"receiveMbps": 8.25, "rttMs": 2.5, "bufferMs": 118, "bandwidthMbps": 900,
"packetsReceived": 562310, "packetsLost": 12, "packetsRetransmitted": 12, "packetsDropped": 0,
"lossPercent": 0.002, "connections": 1
},
"streams": null, "events": null
}
| Field | Meaning |
|---|---|
mode |
Listener (Fantareel waits for the sender) or Caller (Fantareel calls address:port). |
address |
Caller: the sender. Listener: the local address it listens on, empty for all. |
encrypted |
A passphrase is set (the passphrase itself is never sent). |
audioTrack |
The audio stream played when the feed carries several: a PID ("0x101", "257") or a language ("ita"); null = automatic. |
state |
Idle (not in use), Listening, Connecting, Connected, Error. message says more; format is set while the stream is received. |
link |
The open connection, or null: the figures of the last second (receiveMbps, rttMs, bufferMs, bandwidthMbps; null before the first second) and the packet counts since it opened. Without Fantareel's own libsrt (srt.dll) there is no link. |
streams |
Only from /api/inputs/{id}: the elementary streams, {"pid": 256, "kind": "Video", "codec": "H.264 (AVC)", "profile": "High, level 4.1", "details": "1920×1080 · 25 fps …", "language": null, "inUse": true}; inUse marks the ones played. |
events |
Only from /api/inputs/{id}: the last 50 events (connected, lost, …), {"time": "…", "text": "…", "problem": false}, oldest first. |
REST endpoints
| Method | Path | Body | Returns |
|---|---|---|---|
| GET | / |
– | Name, version, and where the API and the WebSocket are (never needs the key). |
| GET | /api/status |
– | Status |
| GET | /api/rundown |
– | Array of items |
| GET | /api/items/{id} |
– | Item |
| POST | /api/playout/take/{index} |
– | {program, time} |
| POST | /api/items/{id}/take |
– | {program, time} |
| POST | /api/playout/cue/{index} |
– | {program, time}: puts the item on air paused on its first frame. |
| POST | /api/items/{id}/cue |
– | {program, time} |
| POST | /api/playout/next |
– | {program, time} |
| POST | /api/playout/previous |
– | {program, time} |
| POST | /api/playout/black |
– | {program, time}: cut to black. |
| POST | /api/playout/fade-to-black |
{"durationMs": 1000} (optional) |
{program, time}. The default is the transition duration, with a minimum of 500 ms. |
| POST | /api/playout/pause |
– | {program, time} |
| POST | /api/playout/resume |
– | {program, time} |
| POST | /api/playout/toggle-pause |
– | {program, time} |
| POST | /api/playout/restart |
{"paused": true} (optional) |
{program, time}: back to the start (or mark in) and play; with paused, wait there on the first frame, ready to go. |
| POST | /api/playout/seek |
{"position": 12.5} |
{program, time}: position in file time; needs a clip on air. |
| GET | /api/playout/transition |
– | {kind, durationMs, wipe} (wipe only for a wipe) |
| PUT | /api/playout/transition |
{"kind": "wipe", "durationMs": 750, "wipe": "CircleOut"} |
{kind, durationMs, wipe}. kind is cut, fade or wipe; the wipe shapes are listed under the WebSocket setTransition command. |
| PATCH | /api/items/{id} |
see below | Item |
| POST | /api/items |
{"path": "D:\\Media\\clip.mov", "index": 3} |
201 + Item. index is optional; without it the item is appended. |
| DELETE | /api/items/{id} |
– | 204 |
| POST | /api/items/{id}/move |
{"index": 0} |
Array of items |
| GET | /api/selection |
– | Selection, or null |
| PUT | /api/selection |
{"itemId": "…"}, {"index": 3}, {"itemId": null} (nothing selected) |
Selection, or null; 404 for an unknown item or index, 400 without itemId / index. One item selected, the list scrolled to it; the keyboard focus is not taken. |
| POST | /api/selection/move |
{"steps": 1} (negative: up) |
Selection: stops at the first and the last item; with nothing selected it starts from the item on air (or before the first item). |
| POST | /api/selection/take, /api/selection/cue |
– | {program, time}; 409 when nothing is selected. |
| GET | /api/rundowns |
– | Array of rundowns of the rundown folder; 503 when the folder is not available. |
| GET | /api/rundown/open |
– | Open rundown |
| POST | /api/rundown/load |
{"rundown": "News/News evening.frl", "discardChanges": false} |
Open rundown (the new one). rundown is relative to the rundown folder: absolute paths, drive letters, .., other extensions and the former path argument get 400; no such rundown 404; unsaved changes in the open rundown 409 unless discardChanges is true. It loads the items, the repeat and the graphics of the rundown, and the window's file, as File › Open does; what is on air stays on air (see docs/remote-control.md, Rundowns). |
| GET | /api/inputs |
– | Array of SRT inputs, by name (without streams and events). |
| GET | /api/inputs/{id} |
– | SRT input, with its streams and events; 404 if there is no such input. |
| POST | /api/items/{id}/skip |
– | Item: skipped, Next goes past it. |
| POST | /api/items/{id}/unskip |
– | Item: back in the sequence. |
| POST | /api/items/{id}/planned |
– | Item: not skipped, no longer sent. |
| POST | /api/rundown/planned |
– | Array of items: every item back to planned (and the rundown on its first pass). |
| GET | /api/rundown/repeat |
– | Repeat. |
| PUT | /api/rundown/repeat |
{"mode": "Times", "times": 3} (Once, Times with times 1–999, Loop) |
Repeat; 400 for an unknown mode or a missing / wrong times. |
| GET | /api/audiobed |
– | Audio bed. |
| PUT | /api/audiobed |
{"loop": true, "mode": "Only", "gainDb": -6} (each optional) |
Audio bed; 400 without a bed, for an unknown mode or a level out of range. |
| POST | /api/audiobed/play, /api/audiobed/stop, /api/audiobed/toggle |
– | Audio bed; 400 without a bed, or when its file cannot be played. |
| POST | /api/audiobed/restart |
– | Audio bed: back to the start of its file (playing on if it was). |
| GET | /api/rundown/schedule |
– | {"at": …, "startsIn": …} (nulls when no start is scheduled). |
| PUT | /api/rundown/schedule |
{"at": "18:00"} |
The same. at is a time of day (18:00, 18:00:30: the next one on Fantareel's clock) or an ISO 8601 date and time (without an offset: Fantareel's time zone; already past: starts at once). At that time, on the frame, the rundown starts from the top: every item planned again, the first pass, the first item not skipped taken with its transition, whatever is on air. Kept when another rundown is loaded, not saved. 400 when at cannot be read. |
| DELETE | /api/rundown/schedule |
– | The same (cancelled). |
| POST | /api/items/{id}/copy-parameters |
{"to": ["…", "…"], "parameters": "All"} |
Array of items. Copies the item's settings onto the others: All, or Playback (loop, end action, display time), Audio (gain), Transition, Framing, Graphics (as copies). Only what fits each item's kind; never the media, title or marks. |
| GET | /api/graphics |
– | Array of graphics of the rundown. |
| POST | /api/graphics/{id}/on, /off, /toggle |
– | Array of graphics; 404 if there is no such graphic. |
| POST | /api/graphics/all/on, /api/graphics/all/off |
– | Array of graphics. |
| GET | /api/recording |
– | Recording |
| POST | /api/recording/start, /api/recording/stop |
– | Recording; 409 with the reason when it cannot start (output stopped, folder not writable…). |
| GET | /api/recording/schedule |
– | Recording schedule |
| PUT | /api/recording/schedule |
{"mode": "Rundown"}, {"mode": "Window", "start": "18:00", "stop": "19:30"}, {"mode": "Duration", "length": 5400}, {"mode": "Manual"} |
Recording schedule. Window: two times of day (the window in progress, else the next; 23:00–01:00 goes past midnight) or two ISO 8601 dates and times. Duration starts recording now: 409 with the reason when it cannot. 400 for an unknown mode, missing or wrong times or length (at most 7 days). |
| GET | /api/stream |
– | Stream |
| POST | /api/stream/start, /api/stream/stop |
– | Stream; 409 with the reason when it cannot start (no address set…). |
| GET | /api/ndi |
– | NDI output |
| POST | /api/ndi/on, /api/ndi/off |
– | NDI output (kept in the settings); 409 with the reason when it cannot start. |
| GET | /api/license |
– | Licence |
| GET | /api/update |
– | Update |
| POST | /api/update/check |
– | Update (the check runs in the background: read /api/update again for its result). |
| POST | /api/update/download |
– | Update; 409 when there is no newer version to download. |
PATCH /api/items/{id}
Send only the fields to change:
{
"title": "New title",
"loop": true,
"endAction": "next",
"gainDb": -6,
"markIn": 2.0,
"markOut": 10.0,
"displayTime": 8,
"clearMarks": true,
"clearDisplayTime": true,
"skip": true,
"startAt": "18:30",
"clearStartAt": true,
"audioVisual": "Waveform",
"audioCaption": "TrackTitle"
}
clearMarksremoves both marks. It is applied beforemarkIn/markOut, so both can be sent together to replace the marks.markIn: 0removes the mark in.displayTime: 0(orclearDisplayTime) makes a still stay on air until the next take."transition": "default" | "cut" | "fade"(with"transitionMs"for a fade, default 500) sets the item's own transition into it;"default"goes back to the default transition.startAt(HH:MMorHH:MM:SS) sets the item's start in time;clearStartAtremoves it. A time already past today comes tomorrow; it is checked on every frame while the output runs.audioVisual(Spectrum,Waveform,Black) andaudioCaption(TrackTitle,FileName,None) apply toAudioitems only (400otherwise).- Changes to the item on air apply live: gain, loop, end action, the picture and caption of an audio item, and the mark out on its next crossing.
POST /api/itemswith{"path": "…"}adds an audio file too (.mp3,.wav,.aif,.flac,.m4a,.aac,.ogg,.opus,.wma,.ac3,.mp2).
Examples
curl http://fantareel-pc:8088/api/status
curl -X POST http://fantareel-pc:8088/api/playout/take/0
curl -X POST -H "Content-Type: application/json" -d "{\"durationMs\":1000}" http://fantareel-pc:8088/api/playout/fade-to-black
curl -X PATCH -H "Content-Type: application/json" -H "X-Api-Key: 3f9a…" -d "{\"gainDb\":-6}" http://fantareel-pc:8088/api/items/6f1c…
WebSocket
Connect to ws://host:port/ws. The optional query parameters are:
time: interval of the timing messages, in ms. The default is100and the minimum is20;0turns them off.apiKey: the API key, when one is set.
ws://fantareel-pc:8088/ws?time=40&apiKey=3f9a…
Messages from Fantareel
Every message has a type:
type |
When | Content |
|---|---|---|
state |
Right after connecting, and in answer to getState |
{"type":"state","status":{…Status},"items":[…Item],"inputs":[…SRT input],"outputs":{…},"rundowns":[…Rundown],"openRundown":{…Open rundown},"selection":{…Selection} or null} (outputs as below) |
program |
Whenever the program changes: a take, black, pause or resume, an item ending | {"type":"program","program":{…},"time":{…}} |
rundown |
Whenever the rundown changes: items added, removed, moved, edited or skipped, a rundown loaded, an item becoming sent or set back to planned, the repeat changed, a new pass | {"type":"rundown","items":[…Item],"repeat":{…Repeat}} (the whole list) |
outputs |
When a graphic of the rundown is switched, a recording or a stream starts or stops, the recording schedule changes, the NDI output is switched or its receivers or tally change | {"type":"outputs","graphics":[…Graphic],"recording":{…},"recordingSchedule":{…Recording schedule},"stream":{…},"ndi":{…NDI output}} |
audioBed |
When the audio bed is set, changed, started, stopped, ends by itself or cannot be played | {"type":"audioBed","audioBed":{…Audio bed}} |
schedule |
When a start of the rundown is scheduled, changed, cancelled or reached | {"type":"schedule","schedule":{"at":…,"startsIn":…}} (the countdown itself: from at, or status.schedule) |
startedInTime |
When an item went on air by itself at its start time (startAt); a program message comes too |
{"type":"startedInTime","itemId":"…","title":"…","at":"18:30:00"} |
time |
Every time ms, only when something changed |
{"type":"time","time":{…Time}} |
inputs |
When an SRT input changes state, message or format (checked every second), or is added or edited | {"type":"inputs","inputs":[…SRT input]} (all of them; the link figures are those of that moment) |
rundowns |
When a rundown of the rundown folder is added, deleted, renamed, moved or saved, or the folder is changed | {"type":"rundowns","rundowns":[…Rundown]} (all of them) |
openRundown |
When another rundown is opened (remotely or at the PC), a new one made, the rundown saved, or it gets unsaved changes | {"type":"openRundown","openRundown":{…Open rundown}} |
selection |
When the selection of the rundown list changes: remotely, by the operator, the selected item deleted (the next one is selected) or moved, a rundown loaded (nothing selected) | {"type":"selection","selection":{…Selection} or null} |
result |
In answer to each command | {"type":"result","id":"…","ok":true,"data":…} or {"type":"result","id":"…","ok":false,"error":"…"} |
While a clip plays, the timing (and the audio levels) changes all the time, so time messages arrive at the requested rate. When everything is still, they stop.
A client that does not read fast enough loses the oldest queued messages; it never slows down Fantareel or the other clients. Ask for a fresh state with getState if needed.
Commands
Send {"id": "any string", "action": "…", …arguments}. id is optional and is echoed back in the result. An event caused by the command (for example a program message) can arrive before or after the result.
action |
Arguments | data in the result |
|---|---|---|
getState |
– | the state message |
getInputs |
– | the SRT inputs (array) |
take |
index or itemId |
– |
cue |
index or itemId |
– |
next, previous |
– | – |
black |
– | – |
fadeToBlack |
durationMs (optional) |
– |
pause, resume, togglePause |
– | – |
restart |
paused (optional, true to wait on the first frame) |
– |
seek |
position (seconds) |
– |
setTransition |
kind (cut/fade/wipe), durationMs, wipe (for a wipe: LeftToRight, RightToLeft, TopToBottom, BottomToTop, DiagonalDown, DiagonalUp, BarnDoorHorizontal, BarnDoorVertical, BoxOut, BoxIn, CircleOut, CircleIn, DiamondOut, Clock, Blinds) |
– |
updateItem |
itemId + the same fields as PATCH |
Item |
addItem |
path, index (optional) |
Item |
removeItem |
itemId |
– |
moveItem |
itemId, index |
– |
selection |
– | Selection, or null |
select |
itemId or index (null: nothing selected) |
Selection, or null |
moveSelection |
steps (whole number, negative: up) |
Selection |
takeSelected, cueSelected |
– | – (error when nothing is selected) |
listRundowns |
– | array of rundowns |
openRundown |
– | Open rundown |
loadRundown |
rundown (relative to the rundown folder), discardChanges (optional) |
Open rundown; errors as POST /api/rundown/load |
skip, unskip |
itemId |
– |
setPlanned |
itemId or itemIds (none: every item) |
– |
repeat |
– | Repeat |
setRepeat |
mode (Once/Times/Loop), times (for Times) |
Repeat |
audioBed |
– | Audio bed |
audioBedPlay, audioBedStop, audioBedToggle, audioBedRestart |
– | Audio bed |
setAudioBed |
loop, mode (Mix/Only), gainDb (each optional) |
Audio bed |
schedule |
– | {"at": …, "startsIn": …} |
scheduleStart |
at (as PUT /api/rundown/schedule) |
the same |
cancelScheduledStart |
– | the same |
copyParameters |
from (item id), to (array of item ids), parameters (optional, All) |
– |
graphics |
– | array of graphics |
graphicOn, graphicOff, graphicToggle |
graphicId |
array of graphics |
allGraphicsOn, allGraphicsOff |
– | array of graphics |
recordStart, recordStop |
– | Recording |
recordingSchedule |
– | Recording schedule |
setRecordingSchedule |
mode, start, stop, length (as PUT /api/recording/schedule) |
Recording schedule |
streamStart, streamStop |
– | Stream |
ndiOn, ndiOff |
– | NDI output |
Example session:
→ {"id":"1","action":"take","index":0}
← {"type":"program","program":{"index":0,"itemId":"…","title":"Opening","kind":"Video","paused":false},"time":{…}}
← {"type":"result","id":"1","ok":true,"data":null}
← {"type":"time","time":{"position":0.04,"duration":14.24,"remaining":14.2,…}}
→ {"id":"2","action":"updateItem","itemId":"…","gainDb":-6}
← {"type":"rundown","items":[…]}
← {"type":"result","id":"2","ok":true,"data":{…Item}}
A minimal browser client:
const ws = new WebSocket("ws://fantareel-pc:8088/ws?time=100");
ws.onmessage = e => {
const m = JSON.parse(e.data);
if (m.type === "time" && m.time.remaining != null) console.log("remaining", m.time.remaining);
if (m.type === "program") console.log("on air:", m.program.title);
};
ws.onopen = () => ws.send(JSON.stringify({ id: "1", action: "next" }));
The server sends WebSocket pings every 15 s to keep idle connections open.