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
- Install Install LumaSync on macOS, Windows, or Linux. Binaries are signed with minisign and verified automatically before updates.
- First setup Start LumaSync, find the tray, pair a Hue bridge, connect a USB controller, and pick your first mode.
- Hardware checklist Parts 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 bridge Discover 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 Area What 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 troubleshooting Common Philips Hue failure modes and how to fix them — discovery, pairing, streaming latency, credentials expiry, bulbs not responding.
USB LEDs
- USB controllers The 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 protocol The 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 calibration Tell 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 troubleshooting Common USB LED failure modes — port missing, health check fails, LEDs flicker, colours wrong, strip partially lit — and the fix for each.
- WLED bridge Drive 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 capture How LumaSync reads your screen, the OS permissions each platform asks for, and why the macOS prompt arrives on first launch.
- Performance Read the Δ/Σ telemetry pill, know what "good" looks like on each platform, and where to look when something is off.
- Ambilight tuning Saturation, smoothing, brightness cap, and update rate — the four knobs that shape the ambilight feel once the pipeline is running.
Advanced
- Scenes The five built-in SOLID-mode scene tiles — movie, game, music, chill, read — with their exact RGB and brightness values.
- Auto-updater How 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 displays Which display LumaSync captures from, how to change it, and the one-capture-source constraint that shapes everything else.
Reference
- Keyboard shortcuts Keyboard shortcuts for LumaSync — global commands, mode switcher, room map editor 50-step undo/redo and object tools, plus the tray context menu entries.
- Config file Where 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.
- Telemetry What LumaSync measures locally — capture FPS, send FPS, queue health — where the numbers live on disk, and why none of them leave your machine.
- Platform notifications How LumaSync emits OS-level notifications for connection, stream, and update events — the one-time permission banner, and the open_log_dir command.
- Error handling How LumaSync recovers from render faults — the global ErrorBoundary, the fallback card, the actions available from it, and the macOS lifecycle shutdown path.