Everything you need to know about StageTime.
Download the latest version from the Downloads page. On macOS, open the DMG and drag StageTime to your Applications folder — choose the Apple Silicon build for M-series Macs and the Intel build for older ones. On Windows, run the installer and follow the prompts. The Windows installer is not yet code-signed, so SmartScreen may show a warning on first run; choose More info ▸ Run anyway.
When you open StageTime, you'll see two windows: the Display (the big timer) and the Remote (the control panel). The display is what your speakers see. The remote is what you operate from. If an external monitor is connected, the display goes fullscreen there automatically; otherwise it opens as a window on your main screen. The full manual is built in: press F1 or open Help ▸ StageTime Manual…; it is also served at http://<computer-ip>:8088/manual for any browser on the network.
Set a time using the + buttons on the remote, then press Start (or the space bar). The traffic light turns green and the countdown begins. At the wrap-up threshold it goes yellow. At zero it goes red and, past zero, the digits turn red with a leading minus sign.
StageTime checks for updates a few seconds after launch and only speaks up when a newer version is available. You can check any time from App ▸ Check for Updates….
The display shows a large countdown alongside a traffic-light circle. Place it fullscreen on a secondary monitor, projector, or confidence monitor facing the stage. Use App ▸ Display On… to pick a monitor; the timer keeps running while the window moves. Plug in an external monitor and the display moves there on its own. Unplug it and the display becomes a window on your main screen. When it's windowed there is no title bar — drag it by the black margin around the timer.
Green — timer running, plenty of time remaining.
Yellow — countdown entered the wrap-up zone.
Red — timer hit zero or is in overtime.
With Flash at Zero on, the red light blinks at 500 ms intervals. With Flash Border on, a red glow pulses around the timer box as well — much harder to miss from a lectern without washing out the whole screen.
Past zero the display shows a leading minus sign and the digits turn red, on both the display and the remote. Turn on Stop at Zero to hold at 00:00 instead. Every character is rendered in a fixed-width cell so the number never shifts as digits change.
The Blackout button in the remote header (or the B key) turns the display fully black instantly. With the blue keying background on it turns blue instead, so the keyer keeps a clean key and the picture simply disappears. The timer keeps running underneath and comes back exactly where it should. Also available from Companion or the API via /api/blackout/toggle.
Options ▸ Progress Bar adds a bar under the digits, colored to match the light, on both the display and the remote. Options ▸ Corner Clock shows a small time-of-day clock in the top corner of the display while a timer is showing, so speakers can see the actual time. Both are off by default.
Options ▸ Ends-at Time shows "Ends 3:45:00 PM" in the top-left corner of the display while a countdown runs, and "Ended 3:45:00 PM" in red once it has passed zero, using the display's clock zone and format. Off by default.
Toggle between black (default) and blue from Options ▸ Blue Background, the remote, or the API. Blue is useful for chroma-key compositing when you need to key the timer over a video feed. With the blue background the border flash becomes a hard-edged ring with no glow, so it keys cleanly.
App ▸ Mirror To… lists every attached monitor. Tick as many as you like and each gets a fullscreen copy of the display — confidence monitors on both sides of the stage, for example. Mirrors are remembered, follow hot-plugging, and paint what the main display reports, so they can never drift from it. Also on the API: /api/displays and /api/mirror/N/on.
http://<computer-ip>:8088/display is the display as a web page. Add it as a browser source in OBS or vMix, or open it in any browser on the network; it shows exactly what the main display shows — digits, light, flashing, messages, progress bar, corner clock, blackout and the keying background. Add ?bg=black, ?bg=blue or ?bg=transparent to pin the page background instead of following the app. Transparent is what an OBS browser source usually wants; blackout then simply hides the timer box. The address is listed under Help ▸ API Reference….
The selector at the top switches between three modes. Each shows only the options that apply, so the remote fits on a 13-inch laptop without scrolling. The mode is locked while a timer is running.
Countdown — set a time and count down to zero, then into overtime or hold at 00:00.
Stopwatch — count up from zero, with an optional milliseconds readout (MM:SS.mmm).
Clock — show the time of day in 12- or 24-hour format, in any time zone. The remote hides the timer controls and shows the zone and date beneath the time.
Add or subtract time with the ±1, ±5, ±10 minute and ±30 second buttons, while stopped or running. Press Clear to reset to 00:00. To count down to a specific clock time, enter it in the End at field: StageTime sets and starts a countdown that hits zero at that moment (tomorrow if it has already passed today), interpreted in the display's selected time zone. While a countdown runs, the header shows the wall-clock time it will finish, and "Ended" in red once it passes zero.
Wrap-Up — the light turns yellow below this threshold.
Flash at Zero — the red light blinks at zero.
Flash Border — a red glow pulses around the timer box at zero.
Stop at Zero — hold at 00:00 instead of counting into overtime.
Buzzer — three short beeps at zero, or your own sound: Options ▸ Buzzer Sound… takes an MP3, WAV, OGG or M4A up to 5 MB and has a volume slider. The Test button asks for confirmation first so it can't be fired by accident into a live audio line.
At zero, show — show a message of your choice automatically at zero (TIME'S UP by default). It clears itself when you add time or clear the timer, and never replaces a message you put up yourself.
Type a short message (up to six words) and click Show Message or press ⌘/Ctrl+Enter to put it on the display. Retract Message or Esc removes it. With Keep timer visible on, the message sits beneath the clock instead of replacing it. Type a message and click + Quick message to save it as a one-tap pill; save as many as you like, the row scrolls sideways. StageTime ships with WRAP UP, TIME'S UP, and Q&A. Messages can also be sent via the API or Companion.
Space — start / stop.
↑ ↓ — plus / minus one minute; hold Shift for ten. → ← — plus / minus one second.
B — blackout.
Esc — retract the message.
⌘/Ctrl+Enter — show the typed message.
Shortcuts are ignored while you're typing in a text field. The full list is under Help ▸ Keyboard Shortcuts….
Every option is remembered across launches: flash, border flash, stop at zero, wrap-up, buzzer, auto-message, background, milliseconds, keep timer visible, progress bar, corner clock, quick messages, time zone, and clock format. Global settings that affect the display live in the Options menu: Progress Bar, Blue Background, Corner Clock, Ends-at Time, Buzzer Sound, 12-hour Clock, and Clock Time Zone. Changes made from the API or Companion are saved too and mirrored on the remote.
Set your desired time and wrap-up, type a name (up to 10 characters), and click Save. Save as many as you need; the row scrolls sideways so the remote never grows. They persist across restarts, and each pill shows its wrap-up time. For an ordered list of segments with timing, use the Rundown instead.
Click a preset to clear and load its time and wrap-up settings. Presets can also be loaded by slot number or by name via the API or Companion (Companion status exposes slots 1–5).
App ▸ Rundown… (⌘/Ctrl+Shift+R) opens a cue list in its own window, so the remote stays exactly as it is. Each cue has a name, a planned time and a wrap-up. Add, reorder (↑ ↓) and delete cues, and edit them in place; the list is saved to its own file and restored at launch.
It works like a cue list: one cue is live, one is on standby. GO (or Space) fires the standby cue — clears the timer, sets its time and wrap-up, starts it — and puts the following cue on standby. Click any row or use ↑ ↓ to put a different cue on standby first. Go on a row fires it right now, Load sets it without starting, Prev goes back one. Pause / Resume (Ctrl/⌘+Space) holds the live cue and continues from where it stopped. StageTime always starts idle: the list is there at launch, nothing from it is on the display, and the cue after the one that was live last time is on standby.
While a cue is live the app measures how long the clock really runs — pauses don't count — and when you move on it keeps that actual time and the over/under against the plan, red when over and green when under, with show totals in the footer. A cue that reaches zero and moves on is exactly on time. Reset run data clears the measurements; Clear list deletes every cue. Both stop and clear the timer if a cue was live.
Tick Auto-advance at zero and the standby cue fires by itself when the live one runs out. Tick Show cue name on display and the live cue's name appears at the top of the display (and on mirrors and the browser source), so "Keynote" turning into "Q&A" is visible from the stage. The rundown is also on the API and in the Companion module, and on the web remote.
Open App ▸ Web Remote…, set a PIN of 4 to 8 digits (or click Generate), and turn it on. The dialog shows the address to open — http://<computer-ip>:8088/remote — and the PIN in plain digits so you can read it out. Off by default, and the PIN is what stands between the network and your timer, so choose it as you would for anything else on a show network.
Open the address on a phone or laptop on the same network, enter the PIN once, and you get the same remote you use in the app: modes, time controls, options, messages, presets and blackout, kept in sync with the app both ways. A Rundown link in the top bar opens the cue list in another tab with a live preview of the display above it, so a producer on a phone can see the room's clock and fire cues. A tab that has been in the background catches up the moment it comes back.
The dialog lists every signed-in device with its address and sign-in time. Disconnect Everyone signs them all out, as does setting a new PIN or turning the web remote off. Five wrong PINs from one address lock it out for a minute. Sign-ins, wrong PINs, lockouts and every command a web remote sends appear in the Connection Log. Web remotes never see the API key, the PIN, the port or the mirror settings, and can only send the commands the remote itself uses.
By default the HTTP API is open to anyone on the network, which is convenient on a closed show network and not what you want on a venue's Wi-Fi. App ▸ API Key… sets a key; from then on every request that changes something — start, clear, messages, options, cues — must carry it, as ?key=… on the URL or an X-API-Key header, or it gets a 401. Reading status, the event stream, the browser source and the manual never need it, so Companion feedback keeps working. Put the key in the Companion module's connection settings and it sends it with every command. Leave the field empty to turn the key off.
App ▸ Connection Log… shows every request the API has received since launch, live: time, source address, request and result, with rejected requests in red and the reason. Web remote sign-ins and commands are in there too. Filter it, hide the status polls, copy it, or reset it. Also available at /api/log (with the key, when one is set).
StageTime includes a dedicated Bitfocus Companion module for controlling the timer from a Stream Deck or any Companion surface. Module 1.2.1 covers the entire StageTime 1.2 API, rundown included. It is in the official Companion module store; install it from there or, on an offline machine, from a downloaded package. Prefer raw HTTP? See Using the API from Companion.
From the store (recommended): in Companion 4.0 or later, open the Modules tab, search for StageTime, and click Install. Companion downloads it and keeps it up to date.
Manually (offline machines): download stagetime-companion.tgz from the Downloads page, then in the Modules tab choose Import module package and pick the file.
Either way, go to the Connections tab next, add a connection, and search for StageTime or Wake Media.
Add a connection and set Host to the IP of the machine running StageTime (127.0.0.1 if it's the same machine) and Port to StageTime's API port (default 8088). The connection indicator should turn green as long as StageTime is running. If StageTime has an API key set, paste it into API key. The app's own IP addresses and port are listed under Help ▸ API Reference…. Live updates is on by default: the module subscribes to StageTime's event stream so button feedback changes the instant the timer does. Turn it off to poll instead.
Timer — start, stop, start/stop, clear, set time, add/subtract time (works while running), count down to a clock time, set wrap-up.
Presets — load slot 1–5 or by name.
Modes — Countdown / Stopwatch / Clock, stopwatch milliseconds.
Messages — show (with a layout choice: preference, beneath the timer, or full screen), hide, show/hide toggle, quick messages 1–6, set the auto-message text.
Rundown — GO (fire the standby cue), previous, go to cue N or load it without starting, put cue N on standby, auto-advance on/off, reset run data.
Display — blackout, background, clock format, time zone, mirror to a monitor.
Options — set any on/off option (flash light, flash border, stop at zero, buzzer, auto-message, progress bar, keep timer visible, corner clock, ends-at time, blue background, 12-hour clock, rundown auto-advance) to on, off, or toggle. Test buzzer, buzzer volume, back to the built-in beeps, clear the connection log. Text fields accept Companion variables.
Light colour — button background follows the traffic light (green/yellow/red/gray), or test for one colour.
Timer — running, stopped, in wrap-up zone, in overtime, remaining time below a threshold.
Mode is Countdown / Stopwatch / Clock.
Messages — message visible, quick message slot has text, preset slot is set (to hide unused buttons).
Option is on for any on/off option, time zone is, and blacked out.
Rundown — cue N is live, cue N is on standby, live cue is over its planned time.
$(wakemedia-stagetime:formattedTime) — live timer (e.g. "09:33"); formattedTimeSigned adds a minus sign in overtime.
Time: remainingSeconds, timerMinutes, timerSeconds, overtime, progress, progressPercent.
State: running, mode, lightColor, lightColorHex, wrapUpSeconds, wrapUpFormatted.
Every option as true/false: flashOn, flashBorder, stopAtZero, soundOn, showProgress, showMilliseconds, bgBlue, blackout, cornerClock, hour12, timeZone, clockFormat.
Messages: messageVisible, autoMessageText, quick_1_text … quick_6_text.
Presets: preset_1_name … preset_5_name and preset_1_time … preset_5_time.
Rundown: rundownCue, rundownNext, rundownIndex, rundownActual, rundownActualFormatted, rundownOver, rundownAutoAdvance.
1.2: showEndsAt, endsAt, buzzerSound, buzzerVolume, apiKeySet, mirrors, webRemoteEnabled, webRemoteSessions.
Ready-made buttons, one per job, in ten categories — Timer (with a live readout that follows the light colour), Adjust Time (±1 sec to ±10 min), Quick Set, Presets (labelled with the preset name and time), Messages (quick message buttons labelled from the app), Rundown (GO with the standby cue's name, Prev, auto-advance, a live cue readout that goes red when over), Stopwatch, Clock (12h/24h, corner clock, ends-at, time zones), Countdown (wrap-up, flash, buzzer, stop at zero, progress bar), and Display (blackout, keying background). Drag them onto your button grid from the Presets tab.
If you would rather not install the module, add a Generic HTTP connection with the base URL set to your StageTime machine, e.g. http://127.0.0.1:8088, then use one GET action per button: /api/blackout/toggle, /api/quickmessage/1, /api/sound/on, /api/endat?time=14:30, and so on. For feedbacks, poll /api/status or subscribe to /api/events and read lightColorHex for button color, formattedTimeSigned for the time, and preset_N_name / quick_N_text for button labels. The complete list is on the API Reference page.
