hyperion.ng: the open source ambilight stack for LED strips and video grabbers

What hyperion.ng actually does, and who it is for

Hyperion is an open source implementation of bias or ambient lighting, the effect TV manufacturers sell as Ambilight. The README describes it plainly: it "supports many LED devices and video grabbers." The repository is the successor to the original Hyperion, which is why the project directory is named hyperion.ng and the releases are labelled Hyperion 2.x.

The audience is narrower than the feature list suggests. The README's first selling point is low CPU load, which it says makes the software "perfect for SoCs like Raspberry Pi." That sentence tells you who the maintainers are building for: people running a small always-on board next to a TV, not people running it on a desktop for occasional use. The topics list confirms the hardware focus, naming adalight, apa102, sk6812, ws281x, wled, cololight, nanoleaf, yeelight, h801 and Hue alongside raspberry and rpi.

If you want a desktop app that grabs your monitor and paints a light strip, the same daemon does the job, but the design assumptions still point at an embedded deployment: a service that starts at boot, holds a capture pipeline open, and exposes an API for everything else. The practical consequence is that provisioning matters more than it does for a desktop tool. You are setting up a machine that will sit behind a TV for years, so the storage, the network address and the boot behaviour are part of the design rather than incidental details. A Raspberry Pi that reboots into a broken configuration is a device you have to reach physically, which is why the web interface and the JSON API matter as recovery paths, not just as conveniences.

The priority channel model, which is the interesting design decision

The README singles out one architectural choice worth understanding before you install anything: "Priority channels are not coupled to a specific led data provider which means that a provider can post led data and leave without the need to maintain a connection to Hyperion."

That is a real design commitment. A source (a grabber, a script, a remote app) pushes a frame of LED data tagged with a priority, and then it can disconnect. Hyperion keeps the highest-priority stream live and falls back to lower ones when it stops receiving. The README gives the motivation directly: this model is "ideal for a remote application (like our former Android app, which is no longer available)."

The consequence is that sources are stateless with respect to the daemon. A shell script, a Python effect, or another machine on the LAN can all feed the same LED output without negotiating ownership. The cost is that the daemon, not the source, decides what is displayed at any moment, so debugging a black screen usually means checking which priority channel is currently winning rather than checking whether your sender is connected. That inversion is easy to miss. Most capture pipelines are pull-based: the display layer asks the source for pixels. Here the source pushes and the daemon arbitrates, which means a sender that exits cleanly is not an error condition and a sender that hangs can hold a channel open indefinitely.

Supporting pieces sit around that core: a black border detector and processor, a scriptable Python effect engine with 39 built-in effects, and a multi language web interface for configuration and remote control. The black border detector is worth calling out separately, because letterboxed video is the most common reason a bias lighting setup looks wrong: the strip lights up for the black bars instead of the picture. Handling that in the daemon rather than in each source means every source benefits from it.

Installing hyperion.ng and pushing a first frame

The README does not contain installation commands. It links to a Getting Started and Installation page on docs.hyperion-project.org, and the badge row points at a separate package repository at releases.hyperion-project.org. The supported platforms and configuration sets live in doc/development/SupportedPlatforms.md in the repository. So the honest first step is to open the documentation site and pick the page for your platform rather than copy a command from here.

What the README does document is the interface you use once it is running: a JSON interface "which allows easy integration into scripts," and "a command line utility for testing and integration in automated environment." Those two are what you will actually touch after install.

The JSON API is documented separately at api.hyperion-project.org, and the README does not reproduce request shapes. Treat the following as the shape of the workflow, not as a verified request body: you send a JSON command to the daemon's API endpoint, and the priority field in that command is what places your data in the channel stack described above. Because the README is silent on the exact payload, check the API reference before writing a sender.

For the command line utility, the README states its purpose without listing flags, so the syntax has to come from the documentation. The practical order of operations is: install via the platform page, open the web interface to configure your LED device and grabber, confirm the built-in effects render, and only then wire up scripts against the JSON API. If effects do not render, the problem is in the device or grabber configuration, not in your sender. That ordering saves time because it separates the two failure domains: the LED device and the capture path on one side, your own code on the other.

One more thing the README makes clear without stating it as a caution: the project spans a lot of hardware families, from addressable strips like apa102 and sk6812 through network devices like wled and Yeelight to Philips Hue. Each of those has its own configuration surface in the web interface, and the documentation link for the hardware overview is where the per-device details live. Reading that page for your specific controller before you start will tell you whether you need a level shifter, a separate power supply, or a particular wiring order.

Where hyperion.ng is the wrong tool

The README is candid about one gap: the Android app it cites as the motivating example for the priority model "is no longer available." Anyone planning a phone-based control surface is starting from scratch against the JSON API, with no maintained first-party client to copy. If the appeal of bias lighting for you is a phone app that changes colours on demand, that path is not provided here.

Two other constraints follow from the README. First, hardware support is not universal. The README sends you to a supported hardware list on the documentation site and to doc/development/SupportedPlatforms.md for platforms, which means the maintainers treat device and platform coverage as a moving list rather than something the README can state. If your LED controller is not on that list, the project is not for you regardless of how well the rest fits.

Second, the capture side depends on video grabbers. On a Raspberry Pi with an HDMI splitter this is a well-trodden path, but the README does not promise that a given internal capture device, virtual display, or Wayland session will work. Related search terms include hyperion ng wayland, which suggests people do hit display server questions. The README does not answer them; the documentation and the forum do. That matters because on Linux the capture path is the part most likely to break after a distribution upgrade, and a session protocol change is not something the daemon can paper over.

Finally, if you want bias lighting as a closed appliance with a vendor support contract, a self-hosted daemon that you configure through a web UI and debug through a JSON API is more work than you are asking for. The support channel here is a forum and a Discord server, which is fine for a hobbyist and a poor fit for someone who needs a response time commitment.

HyperHDR and the other Hyperion: what changes

The search data around this project is dominated by comparisons: hyperion ng vs hyperhdr, hyperhdr hyperion ng, hyperion ng vs hyperion, and hyperion ng alternatives. The last two are answerable from the repository itself. hyperion.ng is the successor to the original Hyperion, so the version comparison is a migration question rather than a fork question, and the releases carry 2.x numbers (2.2.0, 2.2.1, plus nightly builds).

HyperHDR is a different matter. It is a separate project, and the README here does not mention it, so no claim about how the two differ in code or capture pipeline can be sourced from the README. What can be said is what hyperion.ng itself offers: a C++ daemon, an MIT licence, a JSON API, a command line utility, a Python effect engine, a black border detector, and a web UI, with LED support spanning the adalight, apa102, sk6812, ws281x, wled, cololight, nanoleaf, yeelight, h801 and Hue families.

If you are choosing between them, the deciding evidence is not in this repository. Compare the supported hardware lists and the capture paths each project documents, because those are the two places where a bias lighting setup actually succeeds or fails. A comparison that only weighs feature bullets will not tell you whether your specific grabber works on your specific kernel.

The same caution applies to the broader alternatives question. The README names no competing project at all, so any list of alternatives comes from outside this repository. The repository does tell you what to compare on: the hardware overview page and SupportedPlatforms.md, plus the effect engine if you care about writing your own animations in Python rather than accepting whatever ships.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-21, the same day as the nightly build 20260921. Stable releases are less frequent: 2.2.0 landed on 2026-02-03 and 2.2.1 on 2026-04-06. That pattern, nightly builds tracking master plus occasional tagged releases, is worth knowing before you pin a version. If you want stability, track the 2.2.x tags. If you want a fix that only exists on master, you are running nightlies, and you are accepting that a build can change under you.

The licence is MIT, stated in the repository root as LICENSE, with a separate 3RD_PARTY_LICENSES file. MIT is permissive, so redistribution and modification are broadly allowed, but the third-party file exists because the project bundles or links dependencies whose terms are not MIT. If you ship hyperion.ng inside a product, read 3RD_PARTY_LICENSES rather than assuming the top-level licence covers everything. This is not legal advice; it is a pointer to the file that answers the question.

Upgrade cost is mostly configuration. The repository keeps settings in a top-level settings/ directory and ships a web UI for configuration, and the README does not document rollback or a config migration path. That silence matters: before upgrading a working setup, back up your configuration, because the README gives no procedure for reverting a daemon whose config format changed. The repository also carries a CHANGELOG.md, which is where a release's actual changes are recorded, and that file is the thing to read before moving a working installation from one tagged version to the next.

What the README does not tell you

Several things a new user would reasonably want are absent. There are no install commands, only links to docs.hyperion-project.org and releases.hyperion-project.org. There is no list of supported hardware in the README, only a pointer to the documentation. The JSON API is described as existing and as easy to integrate, but the request format lives at api.hyperion-project.org. The command line utility is described by purpose, not by flags.

None of that is unusual for a project with a documentation site and a forum, and the README links both, along with a Discord server and a POEditor project for translations. But it does mean the README alone is not enough to evaluate a purchase. The two pages that decide whether hyperion.ng works for you are the supported hardware list and doc/development/SupportedPlatforms.md. Everything else in this article is downstream of those two answers.

The repository layout backs that up. There is a dependencies/ directory, a libsrc/ directory, a src/ directory, a test/ directory and an effects/ directory at the top level, plus CMakeLists.txt and CMakePresets.json for the build. That structure says the project is built from source as a C++ application with its own dependency handling, and that effects are first-class content rather than an afterthought. It does not say anything about how easy the build is on your machine, and the README does not attempt to.

Editorial conclusion

Adopt hyperion.ng if you already own a Raspberry Pi, a supported LED device and a capture path, and you want a JSON API you can script against. Do not adopt it if you need a signed desktop installer or a documented rollback path, because the README points at the documentation site for installation rather than describing it here. Before committing, check the supported hardware list and the supported platforms document against your exact LED controller and OS, since those two pages decide whether the rest of the setup is possible at all.

Frequently asked questions

Official sources

1. hyperion-project/hyperion.ng on GitHub
2. License: MIT
3. Project website
4. README
5. Releases