KUMA Timer — API Reference

HTTP/JSON API & OSC protocol for integration with Bitfocus Companion, show control systems, and custom automation

Overview

KUMA Timer exposes two integration protocols:

Both protocols are enabled and configured in Settings → Connections. The HTTP server runs on the same port as the Web Mirror (default 5555). No authentication is required — restrict access at network level if needed.

HTTP API

Base URL: http://<kuma-ip>:5555

All responses are application/json. CORS headers are set to * so browser-based dashboards can poll directly.

Status endpoint

{
  "status":        "live",       // "live" | "paused" | "standby" | "hidden"
  "timer":         "04:32",     // display string, "-MM:SS" in overtime
  "timer_seconds": 272,         // integer, negative in overtime
  "overtime":      false,       // true once timer passes zero
  "progress":      74.3,        // 100→0, matches progress bar
  "cue_name":      "Jan Kowalski",// empty string if no cue loaded
  "cue_index":     2,           // -1 if no cue selected
  "sms_active":    false        // true while a message is on screen
}

Command endpoint

Actions reference

Playback

Time

Cues

SMS — Send Message to Screen

To remove a message early:

OSC Protocol

KUMA listens for OSC/UDP on port 8000 (configurable in Settings → Connections). Useful for QLab, ETC Eos, MA consoles, and other show control systems.

Incoming — external device → KUMA

Outgoing — KUMA → external

Default target: 127.0.0.1 : 12321 (configurable)

Bitfocus Companion Module

The KUMA Timer Companion module is built on the HTTP API. It polls /api/status every 500 ms and sends all commands via POST /api/command.

Download from the Download page. Install as a developer module — see Documentation → Companion Module for step-by-step instructions.

Code examples

cURL — start the timer

curl -s -X POST http://192.168.1.10:5555/api/command \
  -H "Content-Type: application/json" \
  -d '{"action":"start"}'

cURL — send a red flashing SMS for 20 seconds

curl -s -X POST http://192.168.1.10:5555/api/command \
  -H "Content-Type: application/json" \
  -d '{
    "action":       "send_sms",
    "text":         "PLEASE WRAP UP",
    "duration":     20,
    "color":        "#ff4444",
    "border_color": "#ff0000",
    "size":         "large",
    "position":     "top",
    "flash":        true
  }'

cURL — load cue #3 and read status

# Load cue index 2 (third row)
curl -s -X POST http://192.168.1.10:5555/api/command \
  -H "Content-Type: application/json" \
  -d '{"action":"load_cue","index":2}'

# Poll current state
curl -s http://192.168.1.10:5555/api/status | python3 -m json.tool

Python — poll loop

import urllib.request, json, time

KUMA = "http://192.168.1.10:5555"

def command(action, **params):
    body = json.dumps({"action": action, **params}).encode()
    req  = urllib.request.Request(f"{KUMA}/api/command", body,
                                  {"Content-Type": "application/json"})
    urllib.request.urlopen(req)

def status():
    with urllib.request.urlopen(f"{KUMA}/api/status") as r:
        return json.loads(r.read())

command("load_time", seconds=300)
command("start")

while True:
    s = status()
    print(f"{s['timer']}  [{s['status'].upper()}]  cue: {s['cue_name'] or '—'}")
    if s["overtime"]:
        command("send_sms", text="OVERTIME!", duration=30,
                color="#ff4444", flash=True)
        break
    time.sleep(1)

Node.js — one-liner command

// npm i node-fetch   (or use native fetch in Node 18+)
await fetch("http://192.168.1.10:5555/api/command", {
  method:  "POST",
  headers: { "Content-Type": "application/json" },
  body:    JSON.stringify({ action: "next_cue" }),
})

QLab (OSC) — start on cue fire

// Network cue → UDP → 192.168.1.10:8000
/kuma/start