KUMA Timer — User Guide

Version 1.10.14 · Professional stage countdown for live events

Installation

KUMA Timer ships as direct downloads only — no third-party storefront required. The macOS and Windows builds are code-signed, so Gatekeeper and SmartScreen will not flag them; the Linux and Raspberry Pi AppImage is unsigned, which is standard practice on desktop Linux.

Every install includes a 30-day Full trial with every feature unlocked. After the trial ends, KUMA Timer keeps working in Lite mode — core countdown, OSC, Companion — or you can enter a £8 licence to stay on Full forever. See pricing for the full feature matrix.

macOS

Signed & Apple-notarized .dmg. Open the disk image, drag KUMA Timer.app to Applications, launch. No Gatekeeper warning. First launch starts the 30-day Full trial automatically — no sign-up needed.

When the trial ends (or earlier, if you already have a code): Settings → License Info → Activate with key. Codes arrive by email from Stripe within seconds of checkout.

Windows

Signed via Azure Trusted Signing. Standard Windows installer .exe, runs without SmartScreen warnings. First launch starts the 30-day Full trial.

The same £8 licence code works on macOS, Windows and Raspberry Pi — one code, one machine at a time. Switch any time via the deregister portal.

Raspberry Pi (kiosk mode, one-liner)

KUMA runs as a dedicated kiosk appliance on Raspberry Pi: fullscreen timer on boot, zero desktop, controlled entirely from the web admin panel at http://<pi-ip>/.

Kiosk mode requires a Full licence — the web admin is a Full feature. The same £8 code that activates your Mac or PC also activates your Pi (one machine at a time). During the 30-day trial everything works with no code; after that, enter the licence via the web admin's License panel.

What you need

• Raspberry Pi 4 (1 GB RAM minimum, 2 GB recommended — 2 GB is required if you want NDI output) or Pi 5
• 16 GB SD card or larger, flashed with Raspberry Pi OS Bookworm 64-bit (Lite or Desktop both work)
• Network — Ethernet or Wi-Fi configured via Pi Imager's advanced options

Install (one command)

SSH into the Pi (or open a local Terminal) and paste:

curl -fsSL https://raw.githubusercontent.com/pltech-dev/kuma-timer-releases/main/install-pi.sh | sudo bash

The installer:

1. Installs system libraries (libfuse2, libportaudio2) via apt
2. Downloads the latest KUMA AppImage from GitHub releases
3. Registers a systemd service that starts KUMA fullscreen on every boot
4. Redirects port 80 → 5555 so http://<pi-ip>/ reaches the admin panel
5. Seeds default admin credentials kuma / kuma (change under System after first login)

Takes 2-3 minutes on a good connection. Reboot when prompted.

After reboot

• Pi boots straight to a fullscreen timer (black background, 00:00)
• From any device on the same network, open http://<pi-ip>/ → log in as kuma / kuma → admin panel
• Need the Pi's IP? The Pi's hostname is kuma-timer.local on most networks — try http://kuma-timer.local/ first

Updates & maintenance

• One-click update: admin panel → System → Update KUMA Timer → Update now
• SSH update: sudo /opt/kuma-timer/update-kuma.sh
• Sync settings from your Mac/Windows: on the source machine open the web admin, System → Download this device's config. On the Pi, System → Import & Restart, select the downloaded JSON. Presets, cues, colours, integrations — everything portable — copy over. Password stays local.
• Emergency exit (plug a USB keyboard into the Pi): hold Ctrl+Alt+Q for 3 seconds
• Uninstall: sudo /opt/kuma-timer/install-kiosk.sh --uninstall --user kuma

Quick-Entry Keyboard (Pi-only)

Plug a USB or Bluetooth numeric keypad into a Pi running KUMA in kiosk mode and you get a dedicated remote for time entry and transport — no second screen, no admin panel, no touch needed. Works equally well with a full keyboard, a USB-numpad, an Elgato Stream Deck Pedal, or any HID device that emits standard key codes.

Pick the device under Settings → Devices → Quick-Entry Keyboard. Once selected, KUMA grabs that device exclusively via the Linux evdev kernel interface — keystrokes never reach the desktop or any other application, so there is zero conflict with whatever else might be running on the Pi.

Live-preview rule of thumb: numeric keypads use the rightmost two digits as seconds, the next two as minutes, and any further digits as hours. Type 5 Enter → 00:05. Type 500 Enter → 05:00. Type 10000 Enter → 1:00:00.

Overview

KUMA Timer has two windows:

• Control Window — your operator view
• Display Window — the output sent to a projector or second screen

The display window can be sent to any connected screen and goes fullscreen automatically on secondary screens.

Timer Controls

Setting the Time

Use the H / M / S spinboxes to enter the desired duration, then click SET to load it without starting.

• In MM:SS mode the H field is hidden
• In HH:MM:SS mode (Settings → Display) the H field appears

The status label above the controls shows the current state: STANDBY, LIVE, PAUSED, or the active speaker name.

Presets

Six quick-load buttons (e.g. 5M, 10M, 20M…).

Presets are saved automatically to config.

Cuesheet / Runsheet

The left column is a runsheet of named speakers with individual times.

The sidebar can be hidden in Settings → Display → Show Runsheet. The cue name can be shown above the timer on the display window — toggle in Settings → Display → Show Cue Name on Display.

Import / Export

Cuesheets can be saved to disk and reloaded later — useful for re-running the same show, sharing between Mac / PC / Pi installs, or building your runsheet in a spreadsheet first. Two formats are accepted on import; export writes whichever extension you pick.

Download example files as a starting point and edit them in any text editor or spreadsheet:

• cues-example.json — JSON format (recommended; supports schedule fields)
• cues-example.csv — CSV format (opens directly in Excel / Numbers / Google Sheets)

JSON format

Wrapped object with a cues array (recommended), or a bare list of cue objects. Each cue needs at minimum name plus a duration:

{
  "kind": "cuesheet",
  "cues": [
    { "name": "Welcome speech",     "min":  5, "sec":  0 },
    { "name": "Maureen Fitzgerald", "min": 30, "sec":  0, "scheduled_at": "10:15" },
    { "name": "Coffee break",       "min": 15, "sec":  0 },
    { "name": "John — keynote",     "min": 45, "sec":  0, "scheduled_at": "11:00" }
  ]
}

Field reference — most have aliases so casual hand-writing works:

CSV format

One row per cue. Header row is optional but recommended — the importer auto-detects column meaning from header names. Without a header it expects column order: name, minutes, seconds, scheduled_at. Comma, semicolon and tab delimiters are all auto-detected, and a UTF-8 BOM (Excel's "Save as CSV UTF-8") is stripped silently.

name,minutes,seconds,scheduled_at
Welcome speech,5,0,
Maureen Fitzgerald,30,0,10:15
Coffee break,15,0,
John — keynote,45,0,11:00
Q & A,20,0,

Same field aliases as JSON: column header name / cue / title / speaker, minutes / min / m, seconds / sec / s, scheduled_at / schedule / scheduled / start / start_time. A column called time / duration / length is treated as a single "MM:SS" / "HH:MM:SS" string and replaces separate min/sec columns.

How import works

1. Click Import on the cuesheet sidebar (or Settings → Cuesheet → Import).
2. Pick a .json or .csv file. Format is auto-detected by extension; if the extension is unfamiliar the file's first byte decides ({ / [ → JSON, anything else → CSV).
3. The file is parsed defensively. Rows with missing name or non-numeric durations are skipped with a warning rather than aborting the whole import — you'll see a summary dialog if any rows were skipped.
4. Imported cues replace the current cuesheet. The previous list is overwritten — make a quick Export first if you want a backup.

Display Modes

Use the TIMER / CLOCK toggle in the control panel:

Visual styles

Each mode has its own visual style picker in Settings → Display. Pick separately for the timer and for the clock — the count-down look does not have to match the time-of-day look.

RounDOT — BBC pip / Wharton clock face

The classic broadcast countdown look — black panel, red LED-style dots. The outer ring of 60 dots ticks one per second; the inner ring of 12 dots lights every 5 seconds, marking the pip moments. The big HH:MM in the centre and the smaller SS below are 5×7 dot-matrix glyphs. RounDOT is time-of-day only — it doesn't make sense for a count-down, so the picker only offers it on the Clock side.

RounDOT in CLOCK mode — host's main display, 11:57:18.

Once picked on the host, RounDOT renders identically on every surface that mirrors the time of day:

• Main display window — Mac / Windows secondary screen, Raspberry Pi kiosk in fullscreen.
• NDI output — vMix / OBS / Resolume see the same dot-matrix face on their video bus.
• KUMA Live web viewer — anyone you've shared the QR / link with sees RounDOT on their phone.
• Web mirror served from the host (http://<host-ip>:5555).
• iOS / iPadOS Companion Monitor mode — iPhone or iPad on the lectern shows the same look.
• Presenter View Mode (PVM) floating window for the operator.

Progress bar position (v1.12.x)

Settings → Display → Bar Position picks where the bar sits relative to the timer:

• Bottom (window edge) — default, bar pinned to the bottom of the window
• Top (window edge) — Irisdown-style, bar above the digits
• Adjacent (below timer) — bar tucked directly below the digit baseline; the [digits + bar] block sits as a vertically-centred unit. Tunable signed offset (-50…+100 px) for fine control over the gap; negative pulls the bar up into the digit baseline area for tight integration.

Timer size adjustment (v1.12.x)

Settings → Display → Timer size is a signed delta percentage that scales the auto-fit timer font. 0 = auto (default), +50 = 50 % larger (great for picture-in-picture / preview-monitor setups where the auto calc is too small), -30 = 30 % smaller. Range -90…+500 %.

Screen Selection

The dropdown at the top of the control panel lists all connected screens (e.g. Primary 2560×1600, Ext 2 3840×2160). Select a screen to move the display window there. On a secondary screen it goes fullscreen automatically; on the primary screen it opens as a regular window.

Send Message to Screen

The SEND SMS button sends a text message to the display window.

1. Click SEND SMS — a dialogue opens
2. Pick a saved or recent message, or type a new one (max 300 characters)
3. Set duration (1–600 seconds) and optional effects
4. Click OK

Display modes

• Bar (default) — message appears in a horizontal bar at the top or bottom of the display window, scrolling from right to left if wider than the container
• Fullscreen — check Fullscreen to take over the entire display window; the timer is hidden and the message auto-scales to the largest readable font size that fits the screen. The timer reappears automatically when the message expires or is cancelled.

Enable Scroll to force scrolling even for short messages. Enable Flash for a flashing background effect. The button changes to CANCEL SMS while the message is active.

Display defaults (text colour, border colour, size, position) and saved messages are managed in Settings → SMS. The Invert scroll direction option is available there for right-to-left languages (Arabic, Hebrew).

The browser mirror page (http://<ip>:5555) shows both the bar and fullscreen SMS overlay in sync with the display window.

Time cut — Glide & Jump

KUMA gives you two ways to bring a running countdown forward to finish at a specific time. Both are transparent — the audience never sees an explicit "we're cutting time" event. Pick the mode that suits your show:

Switching mode

The GLIDE / JUMP segmented control sits at the top of the time-cut panel on the host display, in the web admin's Time cut card, and is reachable on iOS Companion via long-press of the TIME GLIDE / TIME JUMP button. The chosen mode is saved per show, so if you always run hidden cuts, set it once and forget.

Applying a cut

Open TIME GLIDE SETTINGS ▲ (or TIME JUMP SETTINGS ▲ when in jump mode) on the host. Two ways to specify the target:

• By duration — "finish in H:M:S from now" (e.g. cut a 25-min preset down to end in 20 min).
• By clock time — "finish at HH:MM" (e.g. wrap by 14:00).

The panel APPLY button computes the difference and either glides or jumps depending on mode. The same panel exists in the web admin SPA and on iOS — they all drive the same engine.

How JUMP picks landing points

When you ask JUMP to cut N seconds, the engine plans the campaign in advance:

1. Reserves the last 3 minutes (180 s) as a "no-jump zone" so your finish reads cleanly.
2. Picks the largest block size (30 / 20 / 10 s) that divides N cleanly and fits enough jumps into the available time without crowding.
3. Spreads the jumps roughly evenly across the remaining countdown.
4. Snaps each landing to a round multiple of 10 s, scoring :00 highest, :30 next, :10/:20/:40/:50 as fallback. The result reads as a series of "I blinked and it skipped a beat" moments, never a visible fast-forward.

Example: cut 5 minutes from a 40-minute timer → 10 jumps of 30 s, spread one every ~3:30, each landing on the nearest :00 minute boundary.

Overtime

When the timer reaches zero:

Additional options in Settings → Behaviour: change background colour, blink, show a custom message (e.g. PLEASE WRAP UP), send an OSC trigger to Companion. (Behaviour tab also hosts Scheduled Cues — moved here from the old Misc tab.)

OVERTIME box overlay (v1.12.x — Count Up & Stay at 00:00)

An optional block label that appears next to the digits as soon as the timer enters overtime — meant for stage productions where audience must see an unmistakable "you've gone past time" cue. Available only when Behaviour at 00:00 is Count Up or Stay at 00:00 (Stop Timer drops to STANDBY at 00:00, no overtime to flag).

Configurable in Settings → Behaviour → OVERTIME:

• Box text — custom label, max 40 chars (empty = built-in "OVERTIME")
• Box colour & Text colour — full hex pickers (default: red block, black text)
• Size — block height as % of window height (2–20 %, default 6 %)
• Position — Above timer / Below timer
• Distance — signed gap from the digits (-50…+200 px); negative pulls the block into the digit area for tight integration

Renders on the host display and PVM. Hidden when SMS is overlaying the screen so messages take priority.

Audio Cues

Settings → Audio Cues — audible chimes that fire at the same moments the display changes colour, so the speaker hears the warning without watching the screen. Full-tier feature.

How it works

Cues are tied to the colour-transition thresholds you've already set in Settings → Display (Orange at N min remaining and Red at N min remaining). Because the thresholds derive from the colour settings, they scale with event length automatically — a 10-minute talk and a 60-minute keynote use proportional warning windows.

Bundled sounds

Six procedurally-generated samples ship with KUMA Timer — designed for stage-friendly, not aggressive sirens:

• Warm chime — Tibetan-bowl style, soft 1-min warning
• Bright chime — sharper alternative
• Double bell (two-strike) — classic 30-second pattern
• Soft gong — long warm decay, time-up
• Three-beep alarm — harder time-up alternative
• Subtle tick — used for GTS pips and red-zone beeps

Each cue has a volume slider (0–100) and a Test button so you can preview before showtime.

Custom WAV / MP3 upload

Click Add custom sound… at the bottom of the Audio Cues tab to import your own sample. The file is copied into ~/.kumatimer/sounds/ and added to all three sound dropdowns as Custom: yourfile.wav.

Two opt-in extras

• BBC GTS pips — last 5 seconds: short clicks at remaining 5, 4, 3, 2, 1, the same Greenwich Time Signal pattern broadcast by the BBC since 1924. Off by default; broadcast operators turn it on for live TV / radio handovers.
• Red-zone continuous beep: every other second while remaining is in the red zone (Limitimer-style). Off by default; useful when the speaker isn't watching the screen and a single chime won't cut through.

Mirror to iOS Companion (Monitor mode)

If the speaker has an iPad on the lectern running KUMA Companion in Monitor mode, the host normally plays cues only on its own audio output. Toggle "Play on iOS Companion" to mirror every fired cue to subscribed iPads / iPhones, which then play their own bundled equivalents.

What happens after time-up

By industry convention (matches BBC, Stagetimer, DSAN Limitimer defaults): after the time-up gong, audio goes silent. Visual overtime cues continue (background colour change, blink, OVERTIME label), but no further chimes — the gong already signalled "time's up" and additional beeps would be antagonistic. Operators who specifically want to keep nudging the speaker should enable the red-zone continuous beep, which fires every other second leading up to zero.

Presenter View Mode

Settings → Display → Enable Presenter View Mode

PVM creates a small floating window that stays always on top of all other applications — including PowerPoint and Keynote in fullscreen. The window does not steal keyboard focus, so your presentation clicker continues to work normally.

Window controls

Transparent background (v1.12.x)

Settings → Display → Transparent background swaps the solid black PVM panel for full alpha — the slide underneath shows through, only the digits, controls and a hover-only dashed orange frame remain visible. Useful when overlaying PVM on top of a Keynote / PowerPoint slide so the visual context is preserved. Off-hover the frame disappears entirely so the slide is unobstructed; mouse-in re-paints a 3-px dashed border around the window so you can spot the resize edges.

One-time macOS permission prompt (first PVM launch)

The first time you enable PVM on macOS, the system will show a one-time permission dialog asking to allow KUMA Timer to control "System Events":

Click Allow. This grants the auto-focus-return feature: when you click any PVM button (START / PAUSE / ±1m), focus jumps back to your slideshow within ~2 seconds so the next clicker press advances the slide instead of doing nothing. Without this, you'd have to manually click into Keynote / PowerPoint after every PVM interaction.

The permission is stored once in System Settings → Privacy & Security → Automation → KUMA Timer. You will not see the dialog again on this Mac. If you click Don't Allow, PVM still works — you just lose the auto-focus return; you can re-enable later from the same Privacy & Security panel.

macOS requires this consent for any app to send AppleScript / Apple Events to another app (Mojave 10.14+). KUMA Timer uses it only to read the currently-frontmost app and bring it back to the front after a PVM click — no other automation, no scripting of your slides, no data is read.

Typical workflow

1. Set your duration and open Keynote / PowerPoint
2. Enable PVM in Settings → Display — the floating window appears
3. Position and resize the window (e.g. corner of your laptop screen)
4. Click into Keynote and start your slideshow
5. Press START (hover the floating window) or use OSC/Companion
6. The countdown stays visible — your clicker works as normal
7. Right-click the floating window to bring the control panel back

LTC Receiver Mode

KUMA Timer can read incoming LTC (SMPTE Linear Timecode) from a sound card and display it on the output screen — useful as a timecode reader in broadcast or live production rigs.

Setup

1. Connect the LTC output of your timecode generator to the line input of your sound card
2. Open Settings → LTC
3. Check Enable LTC Input and select the correct audio input device
4. Click Save Settings

When LTC is active

• The display window shows the timecode as HH:MM:SS:FF in cyan
• The status label shows ● LTC RX
• All timer controls are disabled — KUMA is in read-only mode

Web Mirror

When enabled (Settings → Network → Enable Web Mirror Server), KUMA runs a local HTTP server. Open http://localhost:<port> in any browser on the same network to see the timer — useful for confidence monitors, tablets, or phones.

The progress bar in the web view follows the global Enable Progress Bar setting.

Web Controller

The Web Controller is a browser-based control panel protected by a password — useful for a second operator, a director's tablet, or a phone on the production desk.

Setup

1. Make sure Web Mirror / API Server is enabled in Settings → Connections
2. Set a Controller Password in the same section (leave blank to disable the controller)
3. Click Save Settings
4. Open http://<IP>:<PORT>/control in any browser — the settings dialogue shows the exact link

Available controls

• Live timer display with progress bar
• START · PAUSE · RESET · HIDE TIMER
• −1 min / +1 min
• Preset buttons (loaded dynamically from app config)
• PREV CUE / NEXT CUE navigation
• Scrollable cue list — click any cue to load it directly

Web Admin SPA — full settings in the browser

Alongside the minimal /control page, KUMA hosts a complete admin single-page app at http://<IP>:<PORT>/admin. This is the same set of settings, presets, cuesheet, and SMS that you'd reach from the desktop's ⚙️ Settings dialog — but in the browser, so a director on a tablet or a producer on a second laptop can edit everything without standing over the operator's shoulder.

Login uses the same Controller Password with username kuma. Default credentials on a fresh install are kuma / kuma — the SPA shows a banner reminding you to change them.

• Edit presets (length + colour) without restarting
• Add / reorder / delete cues
• Toggle iOS Companion remote control, KUMA Live, audio cues
• Tweak warning thresholds, fonts, colours, progress bar style
• Send / cancel SMS overlays
• Trigger time cuts (GLIDE / JUMP) with the same picker as the host

NDI Output

KUMA Timer can broadcast a full 1920×1080 NDI® video stream that mirrors the display window — timer, cue name, SMS bar and progress bar — to any NDI-compatible application on the network (vMix, OBS with NDI plugin, Resolume, Wirecast, etc.). Powered by NDI® — learn more at ndi.video.

Setup

1. Open Settings → Connections and scroll to the NDI Output section
2. On first enable, a licence acceptance dialogue appears — scroll through and click Accept
3. Check Enable NDI Output and click Save Settings
4. The status bar shows NDI ● (amber while initialising, green when active)
5. In your NDI receiver, look for the source named KUMA Timer

What the NDI stream includes

• Timer text — same font, colour and size as the display window
• Cue name (if enabled in Settings → Display)
• Progress bar (respects the Show Progress Bar setting)
• SMS bar when a message is active

Timer Font

Choose the font used in both the display window and the NDI stream in Settings → Display → Timer Font. All available options are monospace — the font size stays perfectly consistent regardless of which digits are displayed.

Wireless Secondary Displays

KUMA can mirror the countdown to dedicated hardware screens over Wi-Fi — no cables, no extra software on the display side. Two device types are supported:

• Ulanzi TC001 — 8×32 RGB LED matrix, ~$50. Ships without KUMA firmware; one-click flash from the browser. Great for stage-edge / desk use.
• ESP32-S3-BOX-3 — 320×240 IPS colour LCD, ~$40. Flash once from the browser; mounts anywhere with a USB-C cable for power.

Both mirror: countdown value, zone colours, background colour, overtime blink, progress bar and SMS messages. Both support Local mode (same LAN as host, UDP) and Cloud mode (different Wi-Fi network, polls the relay).

Flash your device

Chrome or Edge required. Open the flasher page, connect the device via USB, click Install.

Connect to KUMA host

1. After flashing, the device broadcasts a Wi-Fi hotspot (KUMA-Display-XXXX or KUMA-TC001-XXXX).
2. Connect your phone or laptop to that hotspot and open http://192.168.4.1.
3. Enter your Wi-Fi credentials and (for Cloud mode) the Poll URL from Settings → Connections → ESP32-S3-BOX / Ulanzi TC001 → Cloud → Copy URL.
4. The device reboots and joins your network. It appears in KUMA's bottom status bar when active.

Ulanzi TC001 button controls

The three buttons on top of the TC001 (left / middle / right):

On connect the device scrolls its IP for a few seconds so you can find it on the network. In a frame-accurate (FR) clock format the LED shows the plain MM:SS / HH:MM:SS (frame digits don't fit the matrix). When the screen is mounted upside-down, enable Settings → Connections → Ulanzi TC001 → Rotate display 180°.

KUMA Live (Cloud Relay)

Share your timer with remote speakers over the internet. KUMA Live pushes the timer state to the cloud so anyone with the link can watch the countdown in a browser — no LAN or VPN required.

How it works

1. Open Settings → Connections → KUMA Live
2. Click Generate QR Code — a unique session URL is created
3. Share the QR code or URL with up to 2 remote viewers
4. Viewers open the link on any device — the timer mirrors in real-time

Remote messaging

Enable Allow remote viewers to send messages in settings. Viewers can type a message in their browser which appears on your timer display — useful for stage managers or producers giving timing cues to speakers remotely.

Session limits

• Maximum 2 viewers per session (additional viewers see "Session Full")
• Sessions auto-close after 60 minutes of inactivity (no active countdown)
• Time-of-Day (clock) mode does not stream to save bandwidth

Controls

• Generate QR Code — starts a new session and shows the QR code
• Save QR as PNG — save the QR code image to disk
• End Session — immediately stops the relay and disconnects all viewers

iOS Companion App

KUMA Companion is a free iPhone & iPad app that turns your phone or tablet into a remote control surface for the host. Use it from front-of-house, the green room, the production gallery — anywhere on the same Wi-Fi or, with KUMA Live enabled, anywhere with internet.

Getting it

Currently in TestFlight beta while we collect operator feedback. Email pawel@lygan.co.uk with the Apple ID address you use for the App Store and we'll add you to the test group within a day. App Store release follows after the beta loop.

Pairing modes

• LAN (Bonjour) — open the app, tap the host that appears in the discovery list. Zero configuration, but only works on the same network.
• Manual IP — type the host's IP and port directly. Useful when Bonjour is blocked by the venue's switch (common at large conferences).
• Pairing code (cloud / KUMA Live) — host generates a 4-character code in Settings → Connections → Remote Control. The Show Caller types the code into the app and connects through the relay — no port forwarding, works anywhere with internet. Saving your licence in the app pre-loads the host list automatically next time.

Modes

After connecting, choose one of two views:

• CONTROLLER — full control surface mirroring the host's web admin: START / PAUSE / RESET / HIDE, ±1 minute, count-up, presets row, cuesheet with prev / next / tap-to-load, Send Message, Time cut (Glide / Jump — long-press the button to switch mode), mode toggle (TIMER / CLOCK).
• MONITOR — fullscreen timer with the same colour states as the host display. No controls, designed for the talent or stage manager who needs the same readout the speaker sees.

Note: the iOS Companion Monitor mirrors timer text, colour states, SMS overlays and (in CLOCK mode) the BBC RounDOT face — but always renders on a black background. Custom background images set on the host (Settings → Display → Background type → Image) appear on the host display, web mirror, and NDI output, but not on the iPad. This keeps the Monitor readable at any brightness and avoids streaming wallpaper bytes over the relay.

Stages mode iPad only

Stages turns the iPad into a multi-host control surface — one app, several KUMA hosts, one swipe between them. Built for multi-room conferences, multi-stage festivals, A/B redundant timer setups and any situation where the same operator runs more than one timer at once. iPad only; the iPhone build deliberately keeps a single-host-per-app model.

How it works

• Add a stage — tap +, give it a nickname (e.g. Hall A), enter the host's 4-character pairing code from Settings → Connections → Remote Control, optionally set a colour and a per-stage password. Up to eight stages per device.
• Tap a row to take control of that host. The right pane (or full screen on portrait) becomes the same Controller surface single-host mode uses — START / PAUSE / RESET / cuesheet / presets / Send Message — wired to that specific host. A coloured banner across the top reminds you which stage is active.
• Swipe a row left or right for quick actions: Edit (rename / change password / change colour) or Delete. Long-press and drag to reorder.
• Live mini-status on every row shows the host's current timer state and a transport icon — wifi for direct LAN, cloud for relay — without needing to open each stage.
• LAN auto-promote — when the iPad and a host land on the same Wi-Fi, the Companion discovers the host via Bonjour, fetches its /api/status, matches the returned remote_control_code against your stored stages, and quietly upgrades that stage's connection from cloud relay to a direct LAN WebSocket. Latency drops from typical 50-150 ms to sub-20 ms. The transport icon flips from cloud to wifi to confirm. Falls back to cloud automatically if the LAN host disappears (laptop closed, switched networks, etc.).
• Connection states per stage: connected, connecting, interrupted (host went silent — kept the last known timer extrapolating locally for ~30 s), lost (gave up, will retry on tap or server-push notification when the host comes back). Operators see exactly which stage is healthy at a glance.
• Per-stage password — if a host requires a password (set in its Settings → Connections), the Companion saves it per-stage so each tap into that row authenticates without re-typing.

Use cases: a single operator at front-of-house running parallel session timers in two breakout rooms; a touring AV tech bringing one iPad to a festival with three KUMA hosts on three stages; a redundancy setup with a primary and standby host on the same network where switching between them is one tap.

iPad in landscape (single stage)

Rotate an iPad to landscape and the Controller switches to a two-column layout: the cuesheet sits permanently on the left, transport and presets fill the right two-thirds. Both columns are tappable simultaneously, so the operator can advance cues while the other hand is on START / PAUSE without swapping screens. Monitor view stays full-screen and simply uses the wider canvas for an even larger countdown.

Features

• Latency chip in the Controller header shows round-trip to the host in milliseconds — green < 30 ms, amber 30-150 ms, red > 150 ms. Most LAN setups stay under 20 ms; cloud relay is typically 50-120 ms depending on geography.
• Live Activity on iPhone Lock Screen and Dynamic Island — countdown stays visible without unlocking the phone.
• Authoritative colour mirroring — when the host display goes orange or red, the Companion timer flips at the same moment using the host's display_color field.
• Optimistic action feedback — START / PAUSE / RESET reflect on the iPad instantly, then reconcile with the host's authoritative state on the next status push (~200 ms).
• SMS-style quick messages — tap a saved message preset to send "Wrap up" or "2 minutes left" to the host's on-screen banner.
• Universal Links — tapping a pairing-code QR link from the host's Settings opens the app directly with the code pre-filled.

Requirements

• iPhone or iPad on iOS / iPadOS 17 or newer.
• Same Wi-Fi network as the host for LAN mode, or any internet connection for cloud mode.
• Host running KUMA Timer 1.10.10 or newer for full feature parity (latency chip, authoritative colours, Universal Links). Older hosts work with reduced features.

TCP / UDP Show Control Full

KUMA Timer can receive plain-text ASCII commands over TCP or UDP — ideal for integration with show control systems that support custom string output: Dataton Watchout, QLab, Cue Pilot, Green Hippo, and similar.

Enable in Settings → Connections → TCP / UDP Show Control. Default listen port: 36702 (TCP + UDP, same port).

Command reference

One command per line, terminated with \r\n or \n. UDP packets may omit the newline. Commands are case-insensitive.

TCP connections receive a response to each command (OK START, ERR unknown command etc.). UDP is fire-and-forget.

Watchout V6 setup

1. In Watchout, open the Output window and add a String Output.
2. Set Protocol to TCP (or UDP), IP to your KUMA machine's IP, Port to 36702.
3. In the Data to Send field, enter the command followed by CR+LF: e.g. START$0D$0A or SET 10:00$0D$0A.
4. Place the String Output cue at the point on the Watchout timeline where you want KUMA to react.

Test from Terminal

# TCP
echo -e "START\r" | nc localhost 36702

# UDP (Python — most reliable on macOS)
python3 -c "import socket; s=socket.socket(socket.AF_INET,socket.SOCK_DGRAM); s.sendto(b'START\n', ('127.0.0.1',36702))"

Frame-accurate countdown Full

For broadcast and video production workflows where frames matter (Watchout, QLab, vMix), KUMA Timer can display countdowns with SMPTE-style frame digits.

Enabling

1. Open Settings → Display
2. Change Clock Format to MM:SS:FR or HH:MM:SS:FR
3. Pick your project's Frame Rate: 23.976 / 24 / 25 / 29.97 / 30 / 50 / 60 fps

Direction

Frames count down through each second (at 25 fps: 00:05:00:24 → 00:05:00:23 → … → 00:05:00:00 → 00:04:59:24). The standby display always shows :00 so the set value looks clean before you press START; the moment START is pressed the digit jumps to fps−1 and races toward :00. In Count Up overtime the frame digit behaves the same way, counting down within each elapsed second.

Where frames are shown

• Floating display window / full-screen output — your primary stage feed
• Monitor preview in the control window
• Presenter View Mode floating window
• NDI output — auto-fits the wider 11-character string
• TCP / UDP show control input — Watchout cue lists can send SET HH:MM:SS:FR; the FR field is accepted but rounded to whole seconds (the engine is second-resolution)

Where frames are NOT shown

Network and small-display surfaces always render HH:MM:SS regardless of the clock format. Wire latency would race the frame digits and the result wouldn't be reliable enough to cue from.

• iOS Companion app
• KUMA Live web viewer
• Bitfocus Companion module
• OSC outputs
• Web admin / browser admin SPA
• Ulanzi TC001 LED matrix & ESP32-S3-BOX wireless displays
• CDEther bridge (3-byte UART protocol)

Limitations

• Round and RounDOT clock styles are not compatible — there's no horizontal room for the extra :FR segment. If you switch to a round style while frame mode is active, the picker reverts the format and shows a notice.
• CLOCK display mode (Time of Day) renders the system wall clock — frames are not applicable.
• LTC mode uses its own HH:MM:SS:FF timecode read from the incoming LTC stream — independent of the frame-rate picker.
• Time Glide is disabled while frame mode is active. Glide changes the tick interval which would desync the frame anchor — the system automatically falls back to Time Jump for large enough cuts, otherwise the cut is ignored. Time Jump itself works normally.
• Lite tier is locked to MM:SS; frame-accurate formats require Full or Trial.

OSC Reference

OSC is supported for integration with third-party show control systems and lighting desks. For Bitfocus Companion, the dedicated HTTP module (see below) gives richer control and feedback.

Incoming OSC — external device → KUMA

Default listen port: 9000 (Settings → Connections)

Outgoing OSC — KUMA → external

Default target: 127.0.0.1 : 12321

Bitfocus Companion Module

The KUMA Timer Companion module communicates over HTTP/JSON — no OSC configuration needed. It polls KUMA's built-in web server for live state and sends commands via HTTP POST.

Installation

1. Download the .tgz (importable package) from the Download page
2. Open the Companion admin page (http://localhost:8000 on the machine running Companion)
3. In the left sidebar click Modules, then the yellow Import module package button at the top — select the downloaded .tgz
4. Go to Connections, add a new connection and search for KUMA Timer; enter KUMA's IP address and port (default 5555)

Actions

Feedbacks

Variables

Settings Reference

Display

• Clock format: MM:SS or HH:MM:SS
• Timer Font — Courier New, Menlo, Monaco, Consolas; applies to display window and NDI output
• Timer Style — Text (digits + progress bar) or Round (circular ring)
• Background — choose Solid Color or Image (JPEG/PNG/GIF, max 5 MB); image fills the display window without preserving aspect ratio. Background image is available in both Text and Round styles. Presenter View always uses a solid colour.
• Text colour
• Progress bar and colour warnings (orange at N min, red at N min)
• Show/hide sidebar (runsheet)
• Show cue name above the timer on the display window
• Enable Presenter View Mode

Misc

• Touch keyboard — shows on-screen numeric keyboard next to time input fields (for touch screens)
• Time of Day Timezone — IANA timezone name used in Time of Day (Clock) mode, e.g. Europe/Warsaw, US/Eastern, Asia/Tokyo. Leave blank to use the system timezone.

Connections

• Web Mirror / Companion API — enable and set port (default 5555); Companion polls /api/status and posts to /api/command
• Web Controller Password — set a password to enable the browser control panel at IP:PORT/control; leave blank to disable
• NDI Output — enable to broadcast a 1920×1080 NDI stream; one-time licence acceptance required on first use
• OSC — enable for external show control devices; set listen port (default 9000) and feedback target IP:port

SMS

• Default text colour, border colour, size, position for all messages
• Invert scroll direction (for Arabic / Hebrew right-to-left text)
• Saved messages list — always available in the Send Message dialogue
• Clear Recent — removes the automatic last-10 message history

Integrations

• Interspace Ind (CDEther)
  
  Standard setup — use a router with DHCP. The CDEther ships in DHCP mode from the factory; just plug it into the same router as your laptop and enable the integration in KUMA. KUMA broadcasts UDP frames on the network and every CDEther on the same LAN picks them up. No IP discovery, no pairing, no NIC selection — it just works.
  
  This is how the device is designed to operate per the Interspace manual. Stick with this unless you have no network infrastructure available.
  
  Direct-Attach Mode (advanced fallback). If you're at a small venue with just a laptop and the CDEther on one Ethernet cable — no router, no switch — KUMA can host a tiny built-in DHCP server so the CDEther still gets an IP. Settings → Connections → CDEther → Direct-Attach Mode → Enable.
  
  Important things to know:
  • ~30 s for the first lease. After enabling Direct-Attach Mode, allow the CDEther 20–30 seconds to issue its DHCP request and receive an IP. The status indicator goes from yellow ("waiting") to green ("CDEther online") once the handshake completes. If you power-cycle the CDEther mid-session, expect a similar wait before it shows online again.
  • Requires admin / UAC password to reconfigure the Ethernet adapter; reverts automatically when you Disable or quit KUMA.
  • Single CDEther per session. Multiple CDEthers in the same show require a real router — the built-in server hands out only one lease.
  • The chosen Ethernet adapter loses internet access while Direct-Attach is active. Use a USB-Ethernet adapter dedicated to the CDEther if your laptop also needs LAN access for other things.
  Use it only when you really have no other option — a router is always the cleaner path.
• Dsan Limitimer — enable and select the RS-485 serial port (USB adapter supported); KUMA sends a 55-byte DSAN PCT-2 packet at 19 200 baud every 250 ms with countdown time, run/pause state and overtime blink flag.
  Driver requirement: The Limitimer USB adapter uses an FTDI chip. If the serial port does not appear in the list, you need to install the FTDI VCP driver first — download it from ftdichip.com/drivers/vcp-drivers (check the chip model printed on your adapter — most common are FT232R or FT231X).
• Quick-Entry Keyboard (Pi kiosk only) — pick a USB or Bluetooth keypad here to use as a dedicated remote for time entry and transport. Full key map and entry rules are documented in the Pi installation section's "Quick-Entry Keyboard" sub-heading.

Overtime

• Behaviour (count up / freeze / stop), message, background colour, blink, OSC trigger path

LTC

• Enable LTC receiver mode and select an audio input device
• Select output screen for the LTC timecode display
• Note: LTC mode disables the cue list — cue names are not shown during LTC playback

Tips & Shortcuts

Keyboard shortcuts (host, v1.12.x)

Global shortcuts — work regardless of which widget has focus, including while typing in the H/M/S time fields:

Manual time-entry workflow

1. Press S — focus lands on M (or H), value pre-selected
2. Type the minutes — auto-replaces the highlighted value
3. Press Tab — focus jumps to seconds, value pre-selected
4. Type the seconds
5. (Tab again to reach SET if you want explicit confirmation; otherwise the auto-update fires on each keystroke)
6. Press Space — timer starts

Click on a time field also selects its value, so you can mix mouse + keyboard freely.

General tips

• Double-click a cue to instantly load a speaker — no typing needed
• Hold a preset button to change its value without opening Settings
• HIDE TIMER keeps the timer running internally — useful during breaks
• Time cuts (Glide / Jump) are transparent to the audience — Glide accelerates seconds smoothly, Jump hides 10–30 s skips on round boundaries with the last 3 min clean
• OSC feedback (/kuma/status) lets Companion buttons reflect the real timer state with no polling — and now publishes OVERTIME as a distinct status when the timer crosses 00:00
• On Windows, if the title bar is hidden behind the taskbar: right-click the taskbar icon → Move, then use the arrow keys