Hyperion

Last reviewed Sep 13, 2026 · 890 words

Budget two evenings for Hyperion and expect to spend one of them holding a screwdriver. The software installs in minutes, runs happily in 128 MB of RAM, and has a web UI that makes colour calibration pleasant. What decides whether the project succeeds is everything around it: how you get a copy of the picture into Hyperion, which LED controller you point it at, and whether the strip is powered properly. Get those three right in advance and the software part is an afternoon; guess at them and you will be ordering a second batch of parts.

Capture is the whole problem

Hyperion needs a video signal to analyse. Which route works depends on what you watch on.

That last row is the one to read twice. If your Netflix runs inside the TV's own app, nothing external can see the frames, and the answer is to move playback to a box you control. For HDMI capture, the cheap USB 2.0 capture sticks (about 15 to 20 dollars) deliver 1080p at 30 frames, which is more than Hyperion needs since it samples a low-resolution copy anyway. Pass the device into the container with --device /dev/video0 and set the grabber to V4L2 in the UI. Protected 4K HDR sources complicate things because the splitter needs to output a signal the capture stick understands, and that is where the extra spending and the forum threads live.

Pick the LED backend before buying the strip

Hyperion talks to dozens of controllers, but three cover almost everyone. WLED on an ESP32 over UDP is the one I recommend: WLED handles the strip, Hyperion streams colours to it over Wi-Fi, and the strip keeps working for ambient effects even when Hyperion is off. An Arduino running Adalight over USB serial is the classic route, wired and reliable, with no network dependency. Driving WS281x strips directly from a Raspberry Pi's GPIO works too and needs no extra board, but it wants Hyperion running as root for the SPI or PWM access and shares the Pi with the capture job. Philips Hue is supported as a backend as well, though the Hue bridge's update rate makes it a gentle glow rather than a screen-locked effect; the Philips Hue alternatives page is the better starting point if Hue is what you are trying to escape.

Install: HyperBian, Docker, or a package

The project publishes HyperBian, a Raspberry Pi OS image with Hyperion preinstalled, and for a dedicated Pi behind the TV that is the least-friction path. Debian and Ubuntu packages exist for a media PC. Docker works for a server that already runs everything else:

services:
  hyperion:
    image: hyperionproject/hyperion:latest
    network_mode: host
    devices:
      - /dev/video0:/dev/video0
    volumes:
      - ./hyperion-config:/root/.hyperion
    restart: unless-stopped

Host networking matters: the web UI lives on port 8090, the JSON API on 19444, and the flatbuffer and protobuf inputs on 19400 and 19445, and the Android grabber and Kodi add-on find the server by mDNS. The first-run wizard walks through LED count, strip layout around the screen, and colour order, and a wrong colour order (GRB versus RGB) is the number one "my strip is green" question.

Power and wiring, briefly

A 5 V strip of 150 LEDs can draw over 7 amps at full white. Inject power at both ends, use a supply rated 30 percent above the maximum, and never feed the strip from the Pi's USB. Hyperion's brightness limit setting is not a substitute for a proper supply. This paragraph is short because it is electrical advice, not software advice, but it is the failure that produces flickering, resets and in bad cases melted connectors.

Tying it into the house

Home Assistant has a native Hyperion integration that exposes the instance as a light with effects, so "movie mode" can turn on the TV backlight and dim the room in one automation. If the strip runs WLED, Home Assistant sees that too, and you can hand the strip back to WLED effects when the screen is off. Nothing in the home automation category does this job any better; Hyperion is the standard here rather than a niche pick.

What I'd do

Decide the capture path first and buy parts for that, not the other way around. Media PC or Android box: use the built-in or app grabber and skip capture hardware. Anything HDMI: splitter plus USB stick. Run WLED on an ESP32 for the strip, inject power at both ends, and run Hyperion on HyperBian on a Pi if it is dedicated or in Docker with host networking on the media server if not. Calibrate colour order and black level on the first evening, tune the smoothing and the screen-edge crop on the second, and leave it alone after that.