Docs Getting Started
Hardware checklist
Parts list for an ambilight-ready setup, with minimum specs and caveats for the USB LED, WLED, and Philips Hue paths.
LumaSync is a controller, not a store. You bring the lights; we drive them. This page lists what actually works with v1.5.2 — the checklist is short on purpose. Three sink paths: USB LEDs, WLED over Wi-Fi, or Philips Hue. Pick any one, or run several at once.
USB LED path — addressable strips over serial
1 · Addressable strip
- Protocol: WS2812B (3-channel RGB) or SK6812 RGBW (4-channel — host-side encoder derives the white channel as
W = min(R, G, B)). Non-addressable RGB strips will not work; LumaSync needs per-pixel control. - Density: 30 LEDs/m works for most TV behind-screen setups. 60 LEDs/m looks smoother but draws ~twice the current and costs more.
- Length: measure your screen perimeter plus ~10 cm slack at each corner. A 55” TV is roughly 3.8 m; a 65” is roughly 4.6 m.
The chip type is selectable in Settings → Device per controller, so a WS2812B strip on one port and an SK6812 RGBW strip on another both work simultaneously.
2 · USB-to-serial controller
Any of the supported chipsets:
| Chip | USB VID:PID | Notes |
|---|---|---|
| CH340 | 1A86:7523 | Cheap and ubiquitous. Most Arduino-clone ambilight kits use this. |
| CH341 | 1A86:5523 | CH340’s sibling, frequently labelled the same on cheap modules. |
| FTDI FT232R | 0403:6001 | More expensive, fewer driver headaches on macOS. |
| FTDI FT232H | 0403:6014 | High-speed FTDI variant; identical to FT232R from LumaSync’s perspective at 115200 baud. |
| Prolific PL2303 | 067B:2303 | Common on legacy Arduino-clone boards. |
| Silicon Labs CP2104 | 10C4:EA60 | Compact, low-power. Frequently shipped on ESP32 dev kits when the ESP isn’t routing serial directly. |
Non-USB endpoints (Bluetooth, PCI, Unknown) are rejected up-front with PORT_UNSUPPORTED so you can’t accidentally pair against /dev/cu.Bluetooth-Incoming-Port or similar.
The controller must run LumaSync v1 firmware at 115200 baud — see the Serial protocol page for the wire spec. Most “ambilight USB kit” marketplace products ship pre-flashed with Adalight firmware. From v1.4, LumaSync includes an opt-in Adalight encoder profile — either enable it in Settings → Device, or reflash the controller with LumaSync v1 firmware. Leave the baud rate at 115200 either way.
3 · 5 V power supply
Budget 0.3 A per 60 LEDs at moderate brightness, or LEDs × 60 mA at full white. A 4 m × 30 LED/m strip (120 LEDs) needs ~2.5 A at max brightness; a 5 V 5 A supply gives headroom. Don’t power via USB only — the PC can’t deliver enough current. SK6812 RGBW draws an extra ~25 % at full white because of the dedicated white channel.
WLED path — ESP32 / ESP8266 over Wi-Fi
1 · ESP-class board running WLED firmware
Any board the WLED project supports — ESP32 (preferred), ESP8266, ESP32-S2, ESP32-C3 — flashed with current WLED firmware and joined to the same Wi-Fi network as the host. WLED’s own web UI handles the strip / channel layout; LumaSync streams frames into the configured outputs over DDP (Distributed Display Protocol) on UDP.
2 · Network reachability
LumaSync auto-discovers WLED boards on the LAN over mDNS (_wled._tcp.local.). Manual IP entry is also supported, but loopback (127.0.0.0/8), unspecified (0.0.0.0), multicast (224.0.0.0/4), and broadcast (255.255.255.255) addresses are rejected up-front with WLED_INVALID_IP. Wired boards work fine; Wi-Fi 5 GHz / wired uplinks reduce jitter on busier networks.
See the WLED bridge page for the full setup walkthrough.
Philips Hue path
1 · Hue Bridge (gen 2 or newer)
The square bridge, not the old round one. Gen 2+ supports the Entertainment streaming API that LumaSync uses. Firmware should be current (the Hue app auto-updates).
2 · At least one Entertainment Area
LumaSync streams to an Entertainment Area, not individual bulbs. Create one in the Hue app: Settings → Entertainment areas → Create new. Add the bulbs you want driven and position them on the room layout.
Why: LumaSync needs to know each bulb’s physical position to pick the right screen region to sample. The Hue app stores those coordinates; we read them back through the CLIP v2 API.
3 · Hue-compatible bulbs, Play bars, or Lightstrip
Any bulb or lightstrip that appears in the Hue app’s Entertainment Area picker will work. Performance note: the bridge caps streaming at 20 Hz — that’s the real Hue-side limit, not a LumaSync throttle. Don’t expect gaming-rig latency from Hue.
Optional
- Surge-protected power strip for the 5 V supply. Cheap insurance.
- Diffusion channel behind the TV if you can see the dots through the back panel.
- IR remote bridging (e.g. via Home Assistant) if you want to toggle modes from the couch without touching a keyboard.
Not needed
- A dedicated HDMI capture box — LumaSync samples the screen via the OS screen-capture APIs. No extra hardware in the video signal path.
- A Hue Sync Box — that’s a different architecture (HDMI passthrough, console/Apple TV focused). See the Hue Sync comparison for how the two differ.
- An always-on server — the app runs on whatever machine does the screen capture. No Pi or NUC required.
Order-of-priority shopping
If you’re starting from zero and have budget in mind:
- Start with just the Hue bridge path if you already own any Hue bulbs. Zero soldering, one app dialog, you’re ambilighting the room corners.
- Add a USB + WS2812B kit behind the TV for the edge-of-screen effect. This is the higher-impact visual but also more setup.
- Scale up density (30 → 60 LEDs/m) or add a secondary strip only after you’re happy with the basic setup.