Documentation
LumaSync Docs
Everything needed to go from fresh install to a calibrated ambilight setup. Start with Install, then work through the group that matches your hardware.
Getting Started
- InstallInstall LumaSync on macOS, Windows, or Linux. Binaries are signed with minisign and verified automatically before updates.
- First setupStart LumaSync, find the tray, pair a Hue bridge, connect a USB controller, and pick your first mode.
- Hardware checklistParts list for an ambilight-ready setup, with minimum specs and caveats for the USB LED, WLED, and Philips Hue paths.
Philips Hue
- Pair your Hue bridgeDiscover a bridge, press the link button, pick an Entertainment Area, and start streaming. The full four-step onboarding flow with failure modes for each stage.
- Entertainment AreaWhat a Hue Entertainment Area is, why LumaSync requires one, and how to create or edit one in the Hue app — plus Hue Zones, AR-locked sizing, and per-bulb gamut clipping.
- Hue troubleshootingCommon Philips Hue failure modes and how to fix them — discovery, pairing, streaming latency, credentials expiry, bulbs not responding.
USB LEDs
- USB controllersThe USB-to-serial chipsets LumaSync recognises out of the box, supported strip chip types (WS2812B / SK6812 RGBW), how to identify what you have, and what kits ship with them.
- Serial protocolThe LumaSync v1 serial frame format sent over USB to drive WS2812B and SK6812 RGBW strips — 0xAA 0x55 header, LE LED count, gamma-corrected RGB(W), XOR checksum, 115200 baud.
- LED calibrationTell LumaSync how many LEDs are on each edge of your TV, where they start, and which direction they run — the layout editor and room map walkthrough.
- USB troubleshootingCommon USB LED failure modes — port missing, health check fails, LEDs flicker, colours wrong, strip partially lit — and the fix for each.
- WLED bridgeDrive ESP32 / ESP8266 boards running WLED firmware over Wi-Fi via the DDP protocol. Auto-discovery over mDNS, manual IP fallback, IP guard, and led_count validation.
Ambilight
- Screen captureHow LumaSync reads your screen, the OS permissions each platform asks for, and why the macOS prompt arrives on first launch.
- PerformanceRead the Δ/Σ telemetry pill, know what "good" looks like on each platform, and where to look when something is off.
- Ambilight tuningSaturation, smoothing, brightness cap, and update rate — the four knobs that shape the ambilight feel once the pipeline is running.
Advanced
- ScenesThe five built-in SOLID-mode scene tiles — movie, game, music, chill, read — with their exact RGB and brightness values.
- Auto-updaterHow LumaSync checks for new releases, verifies them with minisign, and replaces the binary without you thinking about it. Stable and beta channels.
- Working with multiple displaysWhich display LumaSync captures from, how to change it, and the one-capture-source constraint that shapes everything else.
Reference
- Keyboard shortcutsKeyboard shortcuts for LumaSync — global commands, mode switcher, room map editor 50-step undo/redo and object tools, plus the tray context menu entries.
- Config fileWhere LumaSync stores its state, what shape the file has, which fields are safe to edit by hand, and how to reset to defaults. Hue credentials live in the OS keychain, not this file.
- TelemetryWhat LumaSync measures locally — capture FPS, send FPS, queue health — where the numbers live on disk, and why none of them leave your machine.
- Platform notificationsHow LumaSync emits OS-level notifications for connection, stream, and update events — the one-time permission banner, and the open_log_dir command.
- Error handlingHow LumaSync recovers from render faults — the global ErrorBoundary, the fallback card, the actions available from it, and the macOS lifecycle shutdown path.