The control API
InterDirector has a documented API for anything you want to build around it: a remote control of your own, a panel in your scoreboard software, a plug-in for another app, or a script that runs part of the show. It is the same set of commands the Stream Deck, Bitfocus Companion and the web remote use, so whatever they can do, your code can do.
It needs InterDirector 1.33 or later.
What it can do
- Read the state: the inputs and what each can do, Program and Preview, overlays on air, mutes and solo, fader levels, whether you are streaming and recording and how the stream is doing, replay, data sources and the row on air, and your hotkeys. Over a WebSocket it is sent again whenever it changes.
- Act: 68 actions, from a cut or a fade to putting an overlay up, muting, setting a fader, starting the stream, capturing a replay or moving a data source’s row. See Commands.
- Press a hotkey: any hotkey in the Show, exactly as if you pressed its key.
Two ways to connect
| On the Mac running InterDirector | From another computer | |
|---|---|---|
| WebSocket | ws://127.0.0.1:49721 |
wss://<the Mac>:49722/socket |
| HTTP | http://127.0.0.1:49721/v2/… |
https://<the Mac>:49722/v2/… |
| Password | none | the Show’s web remote password |
| Available | while a Show is open | while a Show is open with its web remote on |
On the Mac itself the API is for apps and scripts, never for a web page: a browser’s request is refused, so a page you happen to have open cannot control your show. To control InterDirector from a browser, or from another computer, turn on the Show’s web remote and use its address and password. The certificate there is the Mac’s own, so your client must accept it (or pin it).
Every command the API carries out is written to the Show’s journal under your client’s name, so it is always clear what moved and why.
Saying what you are
Over a WebSocket, start by naming your client and the version you speak:
{"type": "hello", "client": "Scoreboard", "protocol": 2}
InterDirector answers with the state, and sends it again whenever something changes. Over HTTP, name your script with
an X-Client header. See The state and HTTP.
From another computer, sign in first: the examples show how.
Versions
This is version 2 of the API. The version only rises if something is removed or changes meaning; new fields, actions and answers are added without it, so ignore anything your code does not know. InterDirector keeps answering every version it has published, so a client written today keeps working.