HTTP API

Everything the web app does goes through this API, so anything else can do it too: scripts, Home Assistant, a Stream Deck, a lighting desk. It is plain HTTP with JSON bodies on the same port as the web app (8080 by default), plus one WebSocket for live data. The routes are registered in packages/server/src/core.js and the modules it plugs in; the route table below is generated from the code (node scripts/gen-api-routes.js), and npm test fails when a route is missing from this page.

TL=http://tempolight.local:8080
curl -s $TL/api/status | jq '{source, bpm, part, effect}'
curl -s -X POST $TL/api/power -H 'content-type: application/json' -d '{"on": true}'
curl -s -X PATCH $TL/api/show -H 'content-type: application/json' -d '{"effect": "laser"}'
curl -s -X POST $TL/api/action -H 'content-type: application/json' -d '{"type": "flash", "color": "#ff0066"}'
curl -s -X POST $TL/api/scenes/party/apply

Conventions

• Bodies are JSON (content-type: application/json; an empty body is {}), at most 12 MB. Answers are JSON with cache-control: no-store.
• Ids are short random strings: devices d…, scenes s… (the five built-in scenes are party, chill, movie, focus, relax), schedules t…, songs m…, custom effects u-…, requests r…, fixtures f….
• Times in songs and shows are seconds on the song's clock; wall-clock times are ISO strings or HH:MM, and sunrise/sunset with an optional offset in minutes (sunset+30, sunrise-15) once a location is set.
• Colours are #rrggbb. Brightness values are 0 to 1.
• Numbers out of range are clamped; unknown values (an effect id, a mode) are a 400 error.
• In the online demo the same calls run inside the browser; routes that need the computer (Hue pairing, now playing, integrations, HomeKit, updates) answer that they need Tempolight running on your network, or don't exist.

Auth

Without a PIN lock, every call works for everyone who can reach the port. With a lock (POST /api/lock):

• calls in the admin area need an unlock token: POST /api/unlock {pin} gives {token}, valid for 12 hours (kept in memory: a restart logs everyone out). Send it as the header x-tempolight-token: <token> or as ?token=<token>;
• calls in a guest area (effects, scenes, pads, brightness) work without a token when that area is allowed in Settings (settings.guest, all four by default), else they need one too;
• open calls always work. A few check something of their own: the wake-up and sleep calls also take the wake-up link key (?key=, header x-tempolight-key or key in the body), the game-state posts need the game's token, and song requests need settings.requests on.

TOKEN=$(curl -s -X POST $TL/api/unlock -H 'content-type: application/json' -d '{"pin": "1234"}' | jq -r .token)
curl -s -X PATCH $TL/api/settings -H "x-tempolight-token: $TOKEN" -H 'content-type: application/json' -d '{"fps": 50}'

Origin rule. Calls that change something (any method but GET) are refused with 403 when a browser sends them from another website: their Origin header's host doesn't match the Host Tempolight was reached at. WebSocket connections from other websites are refused the same way. Scripts, Home Assistant and other apps send no Origin and aren't affected. Behind a reverse proxy that changes the Host header, list the public address in TEMPOLIGHT_ALLOWED_ORIGINS (comma-separated, for example lights.example.com). More in internals/security.md.

Errors

A failed call answers with an HTTP status and {"error": "<a sentence for people>"}:

Inside the server these are HttpError(code, message) (core.js); anything else thrown becomes a 500.

All routes

114 routes. Area: open needs nothing, admin needs an unlock token while a PIN lock is set, guest: <area> works without one when that guest area is allowed in Settings (see Auth).

Besides the API, the server answers GET /ws (the WebSocket), the web app's files, /engine/… (the engine's modules), /packages/…, and the pages /phone (a phone as a light), /request (guest song requests), /obs (the OBS browser source), /playground (the effects playground) and /demo.mp3.

State

Lights and show

Actions for POST /api/action (also over the WebSocket, OSC and MQTT):

Your own effects

Scenes and schedules

Home and sleep

Sunrise alarm, sleep timer and the ambient plan for the day; see wake-up.md for phone automations. The wake and sleep calls work for guests when the brightness area is allowed, or with the link key (?key=<key>, header x-tempolight-key, or key in the body), which opens these calls only.

These answer the home status: {wake: {phase: "pending"|"rising"|"snoozed"|"holding"|"ending", start, end, progress, snoozeUntil} | null, nextWake, sleep: {start, end, progress, left} | null, plan: {name, index, night, fading} | null}, which is also status.home. The Home Assistant device also gets the buttons Sleep timer, Snooze wake-up and Stop wake-up (tempolight/action/set with sleep, wake_snooze, wake_stop).

Devices and room

POST /api/devices bodies:

Hue devices show hue: {lights, names, fast, area, areas: [{id, name}], fastKey}; Nanoleaf devices nanoleaf: {panels}. The Hue user name and client key and the Nanoleaf token never leave the server.

A shape: {type: "line"|"pole"|"free"|"circle"|"rect"|"hex"|"tri"|"matrix"|"points", name, dev: "<device id>", count (1-8192), from: <first LED or null for "after the previous shape">, rev, rot, start, zone} plus pts: [[x, y], ...] for lines (and for points: one LED exactly at each point, used by camera mapping, Nanoleaf, bulbs and DMX), or cx, cy, size (and w, h for rectangles, cols, rows, w, h for matrices). Positions are on a 16 x 9 wall view, y = 0 at the top. All fields: internals/data-model.md.

DMX

DMX settings are in PATCH /api/settings {dmx: {...}} (Settings).

Music

Live audio from a browser goes over the WebSocket; from the server's sound card, turn on PATCH /api/settings {capture: {enabled: true, source: "auto"|<id>, command?}}.

Hearing the music

How Tempolight hears the music (the guided panel on the Music page; guide: hearing-music.md).

The status has hearing: {via, sound, level, capture, output, problem, method} and offsetMs (the light timing in use). PATCH /api/settings {syncOffsetMs} sets the timing of the output playing now; add output for a given output, or syncOffsets: {"<key>": null} to forget one.

Now playing

On a PC or Mac (not in the online demo), Tempolight reads which track the music apps on that computer play, with no account: Spotify and Music on macOS (osascript; macOS asks once to allow it under Privacy & Security → Automation), any MPRIS player on Linux (playerctl, or dbus-send), and anything in the Windows media controls (PowerShell, Windows 10 1809+). It is read about once a second. When the track is a remembered song (same title, and artist when the file name has one, and a length within 3 s), the lights follow that song's beat map and show at the app's position (status.source is "nowplaying"); otherwise it is only shown, and live audio still drives the lights. A song played in the web app comes first.

With Spotify connected, Spotify playing on any of your devices is used when nothing plays on this computer. The tokens are kept in spotify-token.json next to the settings and never sent to browsers (not in backups either).

GET /api/status has nowPlaying: {source: "macos"|"mpris"|"windows"|"spotify", app, device, title, artist, album, dur, pos, playing, posKnown, remembered: {id, name} | null, following} or null.

Sync with Spotify

The lights follow the Spotify track that plays (here, or anywhere with your account connected) with its beat map, learned by listening the first time, shared by other installs (optional) or from Spotify's own analysis (older Spotify apps). Details, set-up and the shared beat-map service: spotify.md.

GET /api/status has spotify: {on, mode, modeName, via, track, map, learn, ...} or null (online demo).

Guest song requests

Guests open /request on their phone (QR code on the Music page). These calls are open to everyone, even when locked.

Turn requests off with PATCH /api/settings {requests: false}.

Settings

PATCH /api/settings (admin) takes any part of settings and answers the settings. Every key, its type and its default: internals/data-model.md.

node scripts/bench.js measures each part's CPU time (internals/testing.md).

Backup, reset, updates, quit

Wi-Fi (Raspberry Pi image)

Only where the Wi-Fi setup service runs (the Raspberry Pi image; Linux, TEMPOLIGHT_WIFI_SETUP set).

Lock

Status

GET /api/status and the WebSocket's status messages (4 a second; 2 in low-power mode):

How these are worked out: internals/runtime-and-outputs.md.

WebSocket

Live data (status, LED previews, audio, low-delay pads) goes over one WebSocket: see WebSocket API.

Home Assistant

The easy way is MQTT discovery. In Settings → Home Assistant, turn it on and enter your broker (for example the Mosquitto add-on: mqtt://homeassistant.local:1883, with a user name and password). Or with the API: PATCH /api/settings {mqtt: {enabled: true, url, username, password, prefix?: "homeassistant", base?: "tempolight"}}. The password is never sent back (hasPassword says one is saved). Or with environment variables, applied at every start and winning over the saved settings (the Home Assistant add-on uses these with the Mosquitto add-on's login): TEMPOLIGHT_MQTT_URL (turns it on), TEMPOLIGHT_MQTT_USER, TEMPOLIGHT_MQTT_PASS, TEMPOLIGHT_MQTT_PREFIX, TEMPOLIGHT_MQTT_BASE, and TEMPOLIGHT_MQTT_ENABLED=0 to keep it off.

Tempolight then appears in Home Assistant as one device with:

Voice control through Home Assistant (Google Assistant, Alexa): see voice.md.

tempolight/availability is online or offline (also set by the broker if Tempolight stops suddenly). GET /api/status has mqtt: {state, error}.

Home Assistant without MQTT

rest_command:
  tempolight_scene:
    url: "http://tempolight.local:8080/api/scenes/{{ scene }}/apply"
    method: POST
  tempolight_power:
    url: "http://tempolight.local:8080/api/power"
    method: POST
    payload: '{"on": {{ on }}}'
    content_type: "application/json"

Apple Home (HomeKit)

Tempolight can be a HomeKit bridge (HAP over IP, written into Tempolight: no Homebridge needed). Turn it on in Settings → Apple Home, then in the Home app tap + → Add Accessory and scan the QR code or type the setup code. The Home app warns that Tempolight isn't certified; choose Add Anyway. The iPhone must be on the same network (mDNS, UDP 5353), and the computer's firewall must let it reach the bridge's TCP port (port below).

Changes made anywhere in Tempolight are pushed to the Home app as they happen. New, renamed and deleted scenes show up by themselves (the bridge's configuration number goes up); a scene keeps its accessory, so rooms and automations stay.

The bridge's identity, setup code and pairings are in homekit.json in the data folder, not in tempolight.json, so backups never carry them.

Integrations (OBS, games, Twitch, Discord, Stream Deck)

Node server only (not the online demo). Everything here except the game-state posts and the plugin download is admin-only: with a PIN lock it needs x-tempolight-token. Passwords, the Twitch sign-in and the Discord webhook are kept in the settings file under integrations and never sent back (/api/state doesn't include them). See integrations.md and streamdeck.md.

The OBS browser source is the page /obs (?preview=0, ?np=0, ?corner=tl|tr|bl|br, ?scale=1.5, ?bg=1). A target is all, off, zone:<zone id> or dev:<device id>.