What it does
Mirror the Mac to the TV over AirPlay or HDMI, then run ambilight.py run. Three lights follow three parts of the picture:
- A LIFX bulb follows the top-left of the screen.
- A second LIFX bulb follows the bottom-left.
- A Govee light follows the right quarter.
discover finds the lights on the network, and setup flashes each bulb red in turn and asks which one is which. Ctrl-C stops it and restores every light’s original state.
How it works
Every update, 5 times a second:
- Capture the main display with
mss(18.6 ms per grab, averaged over 10 frames), then shrink it to roughly 190 pixels wide. That’s plenty for picking colors and keeps the math cheap. - Crop black bars, so letterboxed movies don’t push the regions off the actual picture.
- Pick each region’s dominant color (more below).
- Smooth it with an exponential moving average so the lights don’t flicker, unless the color jumps by a lot. Then it’s a scene cut, and the light snaps most of the way at once.
- Send it straight to the lights over UDP: a hand-built binary packet for LIFX, with a fade time so the bulb blends between frames itself, and a small JSON message for Govee.
I talk to the lights directly over the local network instead of through either brand’s cloud API. That means no accounts, no internet dependency, and much lower latency. The LIFX client is about 100 lines of struct packing written against the published LAN protocol, rather than a library.
I chose to capture the Mac’s screen instead of buying an HDMI capture card. The trade-off: the menu bar and Dock count as part of the picture.
A few other choices:
- One color on the Govee light, not a top-to-bottom gradient. Setting each segment separately needs an unofficial command; a single color uses the documented one, which I trust to keep working.
- 5 updates a second, set by the hardware. I started at 12, but the Govee light can only process about 5 commands a second (see What broke). Anything faster just queues up and makes the light lag. 5 is that hardware ceiling, and running every light at the same rate keeps them in step. The bulbs’ fades and the smoothing fill the gaps between updates, so it still looks fluid.
- The bulbs fade themselves. Each LIFX command carries a fade time of 1.5× the update interval, so the bulb blends between frames instead of stepping.
Picking the right color
Averaging a region’s pixels gives mud: a red scene with some blue in it averages to purple. So the tool picks the majority color instead. It sorts colorful pixels into 24 hue buckets, weighted by how saturated and bright they are, merges neighboring buckets, and takes the winner. Mostly grey regions fall back to white, which LIFX shows as a proper color temperature instead of a washed-out tint.


What broke
Smaller ones: grey areas of the screen came out olive, because the “mostly grey” fallback averaged in the few colorful pixels too and the saturation boost exaggerated that tint, so now it averages only the neutral ones. Discovery also found no LIFX bulbs at all. I ruled out the network step by step before realizing the bulbs were switched off. And without macOS’s Screen Recording permission, captured frames come back black and the lights sit at their minimum brightness. The README calls this out. There’s also a brightness floor so the lights never go fully dark on black frames.
What I’d do next
The Govee fixes have only been checked against a simulated light so far, where updates came at most every 246 ms, so the next step is a proper run on the real one. I also haven’t measured end-to-end latency (screen to light), and that’s the number that matters most for how it feels. After that: automated tests, starting with the synthetic-frame check I used during development, and more screen regions with a light for each.