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 draft Install LumaSync on macOS, Windows, or Linux. Binaries are signed with minisign and verified automatically before updates.
- First setup draft Start LumaSync, find the tray, pair a Hue bridge, connect a USB controller, and pick your first mode.
- Hardware checklist draft Parts list for an ambilight-ready setup, with minimum specs and caveats for both the USB LED path and the Philips Hue path.
Philips Hue
- Pair your Hue bridge draft 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 draft What a Hue Entertainment Area is, why LumaSync requires one, and how to create or edit one in the Hue app.
- Hue troubleshooting draft Common Philips Hue failure modes and how to fix them — discovery, pairing, streaming latency, credentials expiry, bulbs not responding.
USB LEDs
- USB controllers draft The two USB-to-serial chipsets LumaSync recognises out of the box, how to identify what you have, and what kits ship with them.
- Serial protocol draft The LumaSync v1 serial frame format LumaSync sends over USB to drive WS2812B strips — 0xAA 0x55 header, LE LED count, gamma-corrected RGB, XOR checksum, 115200 baud.
- LED calibration draft 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 draft Common USB LED failure modes — port missing, health check fails, LEDs flicker, colours wrong, strip partially lit — and the fix for each.
Ambilight
- Screen capture draft How LumaSync reads your screen, the OS permissions each platform asks for, and why the macOS prompt arrives on first launch.
- Performance draft Read the Δ/Σ telemetry pill, know what "good" looks like on each platform, and where to look when something is off.
- Ambilight tuning draft Saturation, smoothing, brightness cap, and update rate — the four knobs that shape the ambilight feel once the pipeline is running.
Advanced
- Scenes draft The five built-in SOLID-mode scene tiles — movie, game, music, chill, read — with their exact RGB and brightness values.
- Auto-updater draft How LumaSync checks for new releases, verifies them with minisign, and replaces the binary without you thinking about it.
- Working with multiple displays draft Which display LumaSync captures from, how to change it, and the one-capture-source constraint that shapes everything else.
Reference
- Keyboard shortcuts draft 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 draft Where LumaSync stores its state, what shape the file has, which fields are safe to edit by hand, and how to reset to defaults.
- Telemetry draft What LumaSync measures locally — capture FPS, send FPS, queue health — where the numbers live on disk, and why none of them leave your machine.