Quick start

By the end of this page you’ll have:

LumaSync running and visible in the tray
At least one sink connected — Philips Hue, USB strip, or WLED board (or any combination)
Your first mode selected (Ambilight, Hue scene, or Solid color)

Expect ~5 minutes if your hardware is already on the network and plugged in.

1 · Start LumaSync

Launch the app. On macOS it lives in the menu bar (top-right); on Windows and Linux in the system tray. The main window hides to the tray on close rather than quitting — this is intentional, and the first time you close the window LumaSync surfaces a one-shot OS notification confirming it’s still running. Right-click the tray icon to quit for real (or Cmd+Q / Ctrl+Q from anywhere).

First launch opens the main window automatically and walks through a three-step inline onboarding banner — pair, calibrate, light up — that disappears for good once you’ve completed the flow. Compact mode is 320×480 and meant for quick toggles; click the expand icon to switch to the full 900×620 window for configuration. Deep-links into non-Lights sections from compact mode auto-expand to full so the target panel is always visible.

2 · Connect something

You need at least one sink for the light pipeline to drive. Do any combination:

Pair a Philips Hue bridge

Settings → Hue → Pair bridge.

LumaSync auto-discovers bridges on the LAN over mDNS (_hue._tcp.local.), with the Philips cloud API as a fallback if mDNS is blocked on your network.
Select yours from the list — or enter the IP manually.
Press the physical link button on the bridge, then click Continue.
Pick an Entertainment Area from the dropdown. If none exist, create one in the Hue app first (Settings → Entertainment areas).

On success the bridge username and PSK land in your OS keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service); the rest of the configuration lives in ~/.config/lumasync/app.json. Nothing is uploaded. See Hue pairing for a deeper walkthrough or troubleshooting.

Connect a USB controller

Plug your USB-serial controller (CH340, CH341, FT232, PL2303, or CP2104) into a USB port. Settings → Device.

LumaSync auto-detects supported controllers and rejects non-USB serial endpoints (Bluetooth, PCI, Unknown) up-front with PORT_UNSUPPORTED. If your chip doesn’t appear, check the full list in USB controllers.
Pick the port from the dropdown, then pick the chip type — WS2812B (RGB) or SK6812 RGBW. The host-side encoder derives the white channel as W = min(R, G, B) for SK6812.
Click Health check — LumaSync sends a PING/PONG handshake at 115200 baud and confirms the strip is responsive. The result shows up next to the port entry within a couple of seconds.

Connect a WLED board

Settings → Device → WLED.

LumaSync auto-discovers WLED boards on the LAN over mDNS (_wled._tcp.local.). You can also paste a static IP — loopback / multicast / broadcast addresses are rejected up-front.
Click Connect, then Test to push a brief solid pattern. The round-trip is reported in milliseconds.
The board is driven over UDP via the DDP protocol once Ambilight is active.

See the dedicated WLED bridge page for the full reference.

3 · Pick a mode

Compact mode header has three tiles: Off · Ambilight · Solid. Click Ambilight to start real-time screen capture, or Solid to push a single RGB color and brightness to both targets.

For more structured scenes (colour presets, warm-white reading, movie-night cinema), use the scene picker below the mode tiles. Scenes trigger the same pipeline but pin the parameters.

4 · Calibrate (optional)

If you just plugged in a USB strip and nothing matches the edge of your TV, open Settings → Calibration:

Set edge counts (top, right, bottom, left)
Mark which corner owns the seam
Pick the start anchor and direction
Hit the test pattern toggle to confirm with a visible chase

See LED calibration for the full reference. Most strip kits work with the defaults.

5 · Keep it open forever

The Auto-start on login toggle (Settings → General) puts LumaSync in your OS login items so the app is always in the tray when you log in. Combined with “hide on close”, it means you pair your bridge once and forget the app exists.

What next?

Your ambilight looks laggy or dim → Performance tuning
USB device went red → USB troubleshooting
Want to map the room and project Hue channels onto it → Room map editor