Remote control (Stream Deck, Companion, OSC)

There are two ways to press Show Clock's buttons from something that is not your mouse:

1. Keyboard shortcuts — works today, with any device that can send a key press: a Stream Deck's Hotkey action, a MIDI-to-key tool, a presentation clicker. The browser window with Show Clock has to be in front.
2. The control link — a secret web address per timetable. Bitfocus Companion, an OSC controller (through Companion or TouchDesigner), or any script calls it; the operator tab does not need focus, and it can even run on a different computer from the Stream Deck.

Stream Deck with keyboard shortcuts

In the Stream Deck app, drag System ▸ Hotkey onto a key and press the shortcut you want in its Hotkey field. Show Clock reacts as if you had typed it.

Things to know:

• Use N for Next, not Space. When a button in Show Clock has keyboard focus, Space presses that button instead.
• Arrows only change the offset when the focus is not on a row of the running order. On a focused row, ↑ / ↓ belong to the row (and Alt+↑ / ↓ move it), so the show's offset stays where it is. Click the big clock once before the show and the arrows go to the offset.
• Keyboard layouts: = is +1 min and Shift+= is +5 min on a US / UK layout. On a German layout the + key is +1 min and there is no +5 shortcut — use a Stream Deck Multi Action with five +1 presses, or the control link below. − and Shift+− work on both.
• Previous (Shift+N) makes the slot before the live one live again. If the live slot was started with Next, that Next is taken back. If it started on its own time, the act before it keeps going and the show runs late by the minutes needed (the offset grows; curfew, doors and broadcast never move). Press Next when the act comes off. It does nothing on the first slot or across a hard time that has started.
• Shortcuts pause while you type in a field or while a dialog (sheet) is open, and they only reach the window that is in front. If the laptop at FOH is also doing other things, use the control link instead.

The control link

A control link is a secret address for one timetable. Anything that can send a web request can drive the show with it: a Companion button, an OSC controller through Companion or TouchDesigner, a shell script.

It works while Show Clock is open on your operator device with Remote control switched on. Show Clock checks for commands every second, so a press lands in about one to two seconds. A command that nobody picks up within 30 seconds is dropped — a "Next" pressed while the laptop was asleep never fires ten minutes later. Commands run exactly like a click: your other devices and every share link follow.

Get your control link

1. Open the timetable you run. Click Show control in the control bar (on a phone: ⚙ Settings ▸ Show control · Blackout · Remote…).
2. Under Remote control, tap Create control link and Copy it. It looks like https://squaresmile.de/api/show-clock/control/scc_… — the part after /control/ is your token. The status address for a button that shows the time left is right below it.
3. Switch Remote control on this device on.

The link is shown once. Afterwards the panel shows only its last four characters and when it was last used. If you lose it, tap Rotate link (twice, to confirm) and paste the new one into your controller.

What you can send

Add an action to the end of the link. Every example below uses https://squaresmile.de/api/show-clock/control/TOKEN — replace TOKEN with yours.

Blackout and the message to the artist are explained in Blackout, stage messages, Artist link, OBS and the stage wall. A cue sent this way is shown in capitals, like one from the Cue the stage composer. A message keeps the "Also on crew screens" choice you last made in the Show control panel.

A plain GET (opening the address) is enough — that is on purpose, because Companion's Generic HTTP module and most OSC-to-HTTP bridges can only send GETs. If your tool can send a POST, send JSON to the link itself:

{ "action": "offset", "value": -1 }

A form body (action=offset&value=-1) works too. Action names take _ or - (offset_reset = offset-reset).

Answers: 202 with {"ok":true,"id":…,"action":"next","value":null} means queued. 422 means the action or value was wrong — the answer's error says which: unknown_action, missing_value, invalid_value or value_too_long. 404 means the token is wrong or was revoked. 429 means too many presses: each link takes up to 20 commands in 10 seconds.

Show the clock on a button: the status address

…/TOKEN/status answers with what is on stage right now, for a Stream Deck button to display:

{
  "ok": true, "online": true,
  "slot": "Band A", "next": "Band B",
  "remaining": 734, "remaining_text": "12:14", "over": false,
  "offset": 120, "offset_text": "+2:00",
  "blackout": false, "cue": "5 MIN", "paused": false,
  "reported_at": "2026-09-29T20:14:05Z", "age": 2
}

remaining is seconds left in the live slot (negative when it runs over; then over is true), offset is the offset in seconds. If Show Clock has not reported for a minute — tab closed, Remote control off, no network — online is false and the fields are empty. Poll it at most once a second.

Bitfocus Companion

Add a connection Generic: HTTP Requests. Leave Base URL empty (or set it to https://squaresmile.de/api/show-clock/control/TOKEN/ and type only the action in each button).

Button recipes — each is one GET action on the button's press:

A live countdown on a button: under Triggers, add a trigger on a time interval of 1 second whose action is a GET of …/TOKEN/status with JSON Response Data Variable set to sc_status and JSON Stringify Result switched off. Then set a button's text to an expression (Companion 3.2 or later), for example jsonpath($(custom:sc_status), '$.remaining_text') for the time left or jsonpath($(custom:sc_status), '$.slot') for the band on stage.

OSC through Companion

Companion listens for OSC itself (Settings ▸ Protocols; port 12321 by default). Point your iPad OSC controller at the Companion computer and send /location/<page>/<row>/<column>/press to press the Companion button that holds the GET — for example /location/1/0/0/press for the NEXT button at page 1, top-left.

TouchDesigner

Drop a Web Client DAT (webclient1). To fire an action from Python — from a button's callback or an OSC In DAT callback:

BASE = 'https://squaresmile.de/api/show-clock/control/TOKEN'

def onReceiveOSC(dat, rowIndex, message, bytes, timeStamp, address, args, peer):
    if address == '/showclock/next':
        op('webclient1').request(BASE + '/next', 'GET')
    elif address == '/showclock/offset' and args:
        op('webclient1').request(BASE + '/offset/' + str(int(args[0])), 'GET')
    return

That turns /showclock/next and /showclock/offset -1 from your OSC controller into Show Clock presses. For the status, request BASE + '/status' on a Timer CHOP and parse the reply in the Web Client DAT's onResponse callback with json.loads.

curl and scripts

TOKEN=scc_…   # your token
curl https://squaresmile.de/api/show-clock/control/$TOKEN/next
curl https://squaresmile.de/api/show-clock/control/$TOKEN/offset/-1
curl -X POST https://squaresmile.de/api/show-clock/control/$TOKEN \
     -H 'Content-Type: application/json' \
     -d '{"action":"cue","value":"5 MIN"}'
curl https://squaresmile.de/api/show-clock/control/$TOKEN/status

Keep the link safe

• Keep it in Companion or TouchDesigner, not in a group chat or a shared show file.
• Rotate the link after a tour, after lending the Stream Deck or the Companion config to someone, or whenever you are not sure who has it. The old link stops working at once, and anything it had queued is thrown away. Paste the new link into your controller.
• Revoke it when you no longer use remote control (Revoke, then tap again to confirm). Each timetable has its own link, so revoking one leaves the others alone. A device with Remote control on switches it off by itself.
• Commands are kept only a few minutes and then deleted; nothing a controller sends is stored with your show.

Next

• Blackout, stage messages, Artist link, OBS and the stage wall — blackout, stage messages, the Artist link and the OBS source.
• Getting started — the offset, the cue and the rest of the operator screen.
• Multiple devices & accounts — running the show from several of your own devices.