Cyc

Cue-to-cue theatrical lighting control for Philips Hue. Built for Bug (ETX Fringe Theatre, Longview TX, October 2026) and any small-venue / non-traditional space where DMX is overkill.

What it does

• Programs lighting cues for a show: per-cue, per-light on/off, brightness, and color
• Plays cues in sequence with GO (or spacebar) — bridge does smooth fades locally
• BACK / GoTo cue / Blackout for live operation
• Survives bridge dropouts and app crashes (auto-reconnect, resume-from-last-cue)
• Show files export to JSON for backup / portability

What it deliberately does NOT do

• No Philips Hue Entertainment API. The v2 REST API with bridge-side fade interpolation (transitiontime) handles theatrical cue-to-cue work just fine and avoids DTLS, PSK setup, the 10-light Entertainment-Area limit, and the fragility of node-dtls-client. Entertainment API is for music/screen sync at 25–60 Hz; we don't need that here.
• No multi-bridge support, no MIDI/OSC/QLab integration, no cloud sync, no mobile build, no marketing site, no pricing tiers. Personal-use tool.

Stack

• Electron (desktop shell, Win/Mac/Linux capable; Win is the primary target)
• node-hue-api v5 (Hue v1 CLIP API client with transitiontime for fades)
• SQLite (sqlite3 package — local show database in app userData)
• electron-store (paired bridge credentials + crash-recovery session state)
• SortableJS (drag-reorder cue list)
• Vanilla JS / HTML / CSS in the renderer (no React, no build step)

Run from source

Requires Node.js 18+ (tested on 25.8).

npm install
npm start

First launch: click ⚙ Bridge → Search network → press the round link button on top of your Hue Bridge → Pair within 30 seconds. The app key is stored locally and auto-reconnects on every subsequent launch.

Build a Windows installer

npm run dist:win

Produces dist/Cyc Setup <version>.exe — an NSIS installer that lets you choose install location, creates Start Menu and desktop shortcuts. Per-user install (no admin required).

Daily usage (programming a show)

1. Create show → name it
2. Add Cue → set number, name, fade time
3. Set your Hue bulbs how you want them (via the official Hue app, voice, switches — whatever)
4. Click 📸 Capture from bridge in the cue editor — pulls the current physical state into the cue
5. Optionally fine-tune individual lights (color picker, brightness slider, ON/OFF toggle, include checkbox)
6. ▶ Preview live to audition the look before saving
7. Save — the cue is persisted with its light data
8. Repeat for the rest of the show

Daily usage (running a show)

• GO (or spacebar): advance to the next cue, fade over its set time
• ◀️ Back: re-fire the previous cue's state
• Click any cue in the sidebar: jump to that cue and fire it
• ⚫ Blackout: two-tap confirmation (button arms amber for 3 seconds, click again to fire) — kills all lights with a 0.3s fade. Designed to prevent fat-finger accidents during a live show.

Reliability features

• Auto-reconnect: if the bridge becomes unreachable, a red banner appears at the top. The app pings every 5 seconds and clears the banner on reconnect. Cues never auto-fire after reconnect — operator presses GO when ready.
• Crash recovery: position is saved after every GO/BACK/Jump. If the app crashes or quits unexpectedly mid-show, the next launch offers a yellow "Resume Show Name at Cue N?" banner. Resume restores the cursor without firing.
• Show export: 📤 Export writes a versioned .cyc.json file with all cues + per-cue light states. Export after every rehearsal, keep on a thumb drive. This is your backup path.

Known constraints

• Latency is consumer-grade — typically 100–300ms from GO to lights starting their fade. Acceptable for cueing; not DMX-quality.
• Color round-trip is approximate. Hue's color gamut is per-bulb and gamut-mapped; capturing then re-applying the "same" color may shift slightly.
• Brightness floor: lights set to "on" use minimum 1% brightness. Setting brightness to 0 in the editor is treated as "on at 1%" rather than "off"; use the explicit OFF toggle to actually turn a light off.
• Single bridge: the app talks to one bridge at a time. Bridge limit is ~50 lights.
• Single show open at a time — switch shows via the dropdown.

File locations

• Show database: %APPDATA%/cyc-app/cyc.db (Windows) — SQLite, all shows + cues + light states
• Paired bridge credentials: %APPDATA%/cyc-app/cyc-hue.json — bridge IP and app key
• Crash-recovery session: %APPDATA%/cyc-app/cyc-session.json — last show + cue index

Network setup for live performance

For show day, follow the practices from the original research doc:

• Use a dedicated router for the lighting network. Don't share with audience Wi-Fi or venue infrastructure
• Wire the bridge to the router via Ethernet (always); wire the control device too if possible
• The control device on 5 GHz Wi-Fi if you must go wireless — 2.4 GHz interferes with Hue's Zigbee
• Lock down the network (WPA2/3, strong password, no other devices)

The app cannot control the network, but a bad network will ruin your show no matter how good the software is.