KUMA Timer — User Guide

Version 1.7.30 · The Bold & Alert Clock System

Installation

KUMA Timer is available as a direct download (macOS & Windows) and on the Microsoft Store (Windows). The Apple App Store (macOS) version is coming soon.

Apple App Store COMING SOON

The easiest way to install KUMA Timer on macOS — no Gatekeeper warnings, automatic updates, and no manual download needed.
The App Store price is £5.99. This is a one-time payment that covers Apple's developer programme fee ($99/year) and helps keep the project going. If you can, please consider installing through the App Store — it makes a real difference for an indie project like this. ☕

macOS — Direct Download

Download the .zip, unzip and drag KUMA Timer.app to your Applications folder. On first launch macOS Gatekeeper may warn about an unrecognised developer — right-click the app and choose Open, then confirm.

Windows — Microsoft Store RECOMMENDED

Installs silently without any SmartScreen warnings and updates automatically. Search for KUMA Timer in the Microsoft Store or use the link on the download page.

Windows — Direct Installer (.exe)

If you prefer the direct installer, Windows Smart App Control or SmartScreen may block it on first run. To bypass:

SmartScreen: click More info → Run anyway
Smart App Control: go to Windows Security → App & browser control and temporarily allow the file

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

Button	Action
START	Start the timer from the loaded time
PAUSE	Pause the running timer
RESUME	Resume after pause
RESET	Stop and clear the timer to zero
HIDE TIMER	Blank the display window (timer keeps running internally)
SHOW TIMER	Restore the display
−1m / +1m	Subtract or add 60 seconds while timer is running

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…).

Interaction	Action
Click	Load that duration and set the manual input fields
Hold (0.6 s)	Edit the preset value — enter new minutes in the dialog

Presets are saved automatically to config.

Cuesheet / Runsheet

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

Interaction	Action
Double-click a cue	Load that speaker's time and name into the timer
Drag & drop	Reorder cues — saved automatically
+ button	Add a new cue (name + minutes + seconds)
− button	Delete the selected cue
Clear button	Remove all cues (confirmation required)
✎ button	Edit the selected cue (name, minutes, seconds)
▶ NEXT button	Advance to the next cue in the runsheet

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.

Display Modes

Use the TIMER / CLOCK toggle in the control panel:

Mode	Display shows
TIMER	Countdown (or count-up in overtime)
CLOCK	Current wall clock time (HH:mm:ss)

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.

Click SEND SMS — a dialog opens
Pick a saved or recent message, or type a new one (max 300 characters)
Set duration (1–600 seconds) and optional effects
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 Glide

Time Glide adjusts the timer's tick speed so it reaches zero at a target moment — without changing the displayed value.

Click TIME GLIDE SETTINGS ▲ to expand the panel.

Duration Glide

Enter how many real minutes/seconds remain until the end of the session. KUMA recalculates the tick speed so the timer expires exactly then.

Clock Time Glide

Enter the wall clock time at which the timer should reach zero. KUMA calculates the difference from now and adjusts speed accordingly.

Button	Action
APPLY	Activate glide — replaced by CANCEL GLIDE
CANCEL GLIDE	Restore normal 1-second tick speed

Time Glide is transparent to the audience — the display always shows the original countdown value. Glide cancels automatically when the timer enters overtime.

Overtime

When the timer reaches zero:

Setting	Behaviour
Count Up	Timer continues with a − prefix and red colour
Stay at 00:00	Timer freezes at zero
Stop Timer	Timer stops completely

Additional options in Settings → Overtime: change background colour, blink, show a custom message (e.g. PLEASE WRAP UP), send an OSC trigger to Companion.

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

Action	Result
Drag centre	Move the window
Drag edge or corner	Resize — font auto-scales to fill
Hover over window	Reveal controls: START/STOP · PAUSE · −1m · +1m
Right-click	Bring the main KUMA Timer control panel to the front

Typical workflow

Set your duration and open Keynote / PowerPoint
Enable PVM in Settings → Display — the floating window appears
Position and resize the window (e.g. corner of your laptop screen)
Click into Keynote and start your slideshow
Press START (hover the floating window) or use OSC/Companion
The countdown stays visible — your clicker works as normal
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

Connect the LTC output of your timecode generator to the line input of your sound card
Open Settings → LTC
Check Enable LTC Input and select the correct audio input device
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

macOS: On first use, the system will ask for microphone access. Grant it — without this permission the audio input cannot be opened and LTC will not work.

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.

macOS: On first launch macOS may ask to allow incoming network connections. Click Allow — KUMA needs this for the Web Mirror / Companion API (port 5555) and OSC (port 9000).

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

Make sure Web Mirror / API Server is enabled in Settings → Connections
Set a Controller Password in the same section (leave blank to disable the controller)
Click Save Settings
Open http://<IP>:<PORT>/control in any browser — the settings dialog 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

No settings access. The Web Controller can only trigger the controls that the main operator has already configured in the app. It cannot change any settings.

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.).

The NDI runtime is bundled inside the app — end users do not need to install the NDI SDK or any separate tools.

Setup

Open Settings → Connections and scroll to the NDI Output section
On first enable, a licence acceptance dialog appears — scroll through and click Accept
Check Enable NDI Output and click Save Settings
The status bar shows NDI ● (amber while initialising, green when active)
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.

NDI initialises in the background on a separate thread — the UI never freezes. The stream becomes active a few seconds after enabling.

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

Open Settings → Connections → KUMA Live
Click Generate QR Code — a unique session URL is created
Share the QR code or URL with up to 2 remote viewers
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

KUMA Live requires an internet connection. No account or login is needed. The session is temporary and deleted when you close it or the app.

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)

Address	Argument	Action
`/kuma/start`	—	Start timer
`/kuma/pause`	—	Pause / resume toggle
`/kuma/reset`	—	Reset to zero
`/kuma/hide`	—	Toggle display visibility
`/kuma/time/add`	—	+1 minute
`/kuma/time/sub`	—	−1 minute
`/kuma/warp`	`int` seconds	Load duration (e.g. `300` = 5:00)
`/kuma/preset`	`int` 0–5	Load preset by index
`/kuma/cue`	`int` index	Load cue from runsheet by index
`/kuma/cue/next`	—	Advance to next cue
`/kuma/settime`	`string` HH:MM:SS	Load exact time (e.g. `"01:30:00"`)
`/kuma/sms`	`string` text · `int` duration	Send message to display

Outgoing OSC — KUMA → external

Default target: 127.0.0.1 : 12321

Address	Value	Sent when
`/kuma/status`	`"LIVE"` · `"PAUSED"` · `"STANDBY"` · `"HIDDEN"`	On state change
`/kuma/overtime`	`1`	On overtime start (path configurable)

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.

Make sure Web Mirror is enabled in Settings → Connections and note the port (default 5555). KUMA and Companion must be on the same network.

Installation

Download the .zip from the Download page, extract it and move the kuma-companion/ folder somewhere permanent
(e.g. ~/companion-modules/kuma-companion/)
Open the Companion launcher, click the ⚙ cog icon (top-right) → Advanced Settings
In the Developer section click Select and choose the folder containing kuma-companion/, then toggle Enable Developer Modules on
Close settings, click Launch GUI, add a new connection and search for KUMA Timer
In the connection settings enter KUMA's IP address and port (default 5555)

Actions

Action	Options	Description
Start	—	Start the timer
Pause / Resume	—	Toggle pause state
Reset	—	Stop and reset to zero
Hide / Show Display	—	Toggle display window visibility
+1 Minute	—	Add 60 seconds
−1 Minute	—	Subtract 60 seconds
Load Time (seconds)	seconds	Load a duration in seconds
Load Time (MM:SS)	minutes · seconds	Load duration as MM:SS
Load Preset	index 0–5	Activate a preset button by index
Load Cue	index	Load runsheet cue by index (0 = first)
Next Cue	—	Advance to the next cue in the runsheet
Previous Cue	—	Go back to the previous cue in the runsheet
Set Display Mode	TIMER · CLOCK	Switch between countdown timer and wall clock
Send Message (SMS)	text · duration · colour · border colour · size · position · flash · scroll	Send a styled text message to the display
Cancel SMS	—	Remove the current on-screen message

Feedbacks

Feedback	Active when
Timer is LIVE	Timer is running
Timer is PAUSED	Timer is paused
Timer in STANDBY	Timer is stopped / reset
Display is HIDDEN	Display window is hidden
Timer in OVERTIME	Timer has passed zero
Cue is active (by index)	The specified cue index is currently loaded
Low time warning	Progress percentage is below a set threshold (e.g. <20%)
SMS message active	A message is currently shown on screen

Variables

Variable	Value
`$(pltech-kumatimer:timer)`	Live countdown string, e.g. `04:32`
`$(pltech-kumatimer:timer_seconds)`	Timer value in seconds
`$(pltech-kumatimer:status)`	`LIVE` · `PAUSED` · `STANDBY` · `HIDDEN` · `OFFLINE`
`$(pltech-kumatimer:display_mode)`	`TIMER` or `CLOCK`
`$(pltech-kumatimer:cue_name)`	Name of the currently loaded speaker / cue
`$(pltech-kumatimer:cue_index)`	Index of the current cue (−1 if none)
`$(pltech-kumatimer:overtime)`	`true` / `false`
`$(pltech-kumatimer:progress)`	Progress bar percentage (100 → 0)
`$(pltech-kumatimer:sms_active)`	`true` while a message is on screen

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 dialog
Clear Recent — removes the automatic last-10 message history

Integrations

Interspace Ind (CDEther) — enable and set device IP; use RESCAN to auto-detect on the local network
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).

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

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 Glide is transparent to the audience — the display always shows the original countdown value
OSC feedback (/kuma/status) lets Companion buttons reflect the real timer state with no polling
On Windows, if the title bar is hidden behind the taskbar: right-click the taskbar icon → Move, then use the arrow keys