https://github.com/hyperb1iss/hypercolor
Open-source RGB lighting orchestration engine for Linux, Windows, and Mac
https://github.com/hyperb1iss/hypercolor
ableton-push corsair full-rgb hid led leptos lighting lightscript linux linux-first macos razer rgb rgb-lighting rust servo usb wasm webgl
Last synced: 1 day ago
JSON representation
Open-source RGB lighting orchestration engine for Linux, Windows, and Mac
- Host: GitHub
- URL: https://github.com/hyperb1iss/hypercolor
- Owner: hyperb1iss
- License: apache-2.0
- Created: 2026-03-03T05:06:36.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T03:59:35.000Z (2 days ago)
- Last Synced: 2026-07-03T05:32:36.833Z (2 days ago)
- Topics: ableton-push, corsair, full-rgb, hid, led, leptos, lighting, lightscript, linux, linux-first, macos, razer, rgb, rgb-lighting, rust, servo, usb, wasm, webgl
- Language: Rust
- Homepage: https://hypercolor.lighting
- Size: 54.9 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Notice: NOTICE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Hypercolor
Linux-first open-source RGB lighting engine
✦ Your world is a canvas: paint every pixel. ✦
Vision •
How It Works •
Features •
The UI •
The TUI •
Get Started •
Effect SDK •
Architecture •
Status •
Security •
Contributing
---
## 🔮 The Vision
RGB lighting is a mess. Single-vendor tools that don't talk to each other, half-working daemons,
and effects that look like they were designed in 2012. The one great effects engine is proprietary,
Windows-only, and behind a subscription.
**Hypercolor is the fix.**
One daemon. Every RGB device you own. Motherboards, keyboards, mice, LED strips, smart lights,
case fans, all driven by the same engine at 60fps. Effects aren't hardcoded routines. They're
web pages, rendered by an embedded Servo browser and sampled onto your physical LED layout
every frame.
Your world is a canvas. Paint every pixel.
## ⚡ How It Works
```mermaid
graph LR
subgraph Input
A[Audio FFT]
B[Screen Capture]
C[Keyboard / MIDI]
end
subgraph Engine
D[Effect Renderer
Servo · wgpu · Canvas]
E[Canvas
640 × 480 default]
SF[SparkleFlinger
compositor]
F[Spatial Sampler]
end
subgraph Hardware
G[Razer · Corsair · ASUS
USB / HID / I2C]
H[WLED · Hue · Nanoleaf
UDP / REST / mDNS]
I[QMK · Push 2
USB HID · USB MIDI]
end
A & B & C --> D
D --> E --> SF --> F
F --> G & H & I
```
Effects render to a virtual RGBA canvas, 640×480 by default and tunable in the daemon's rendering
settings. **SparkleFlinger**, the render-thread compositor, latches the newest surface from each
producer at the frame boundary and blends them into one canonical frame every tick. The spatial
engine samples that frame at each LED's physical position. Effects use normalized `[0.0, 1.0]`
coordinates, so they stay resolution-independent across canvas sizes. Audio, screen capture, and
keyboard input feed the render every frame. One effect paints the whole room. Your keyboard,
your LED strip, your case fans, all drawing from the same source.
## 🌈 Features
### 🔌 Supported Hardware
Hypercolor tracks **414 devices** across **32 vendors** in `data/drivers/vendors/`. **179** ship with a working driver today across **12 driver families**. **233 more** are researched or known, awaiting implementation or hardware to test.
| Vendor | Supported | In progress | Researched | Blocked | Drivers |
|---|--:|--:|--:|--:|---|
| [Ableton](docs/content/hardware/compatibility.md#ableton) | 1 | — | — | — | `push2` |
| [Alienware](docs/content/hardware/compatibility.md#alienware) | — | — | 3 | — | — |
| [Aqua Computer](docs/content/hardware/compatibility.md#aquacomputer) | — | — | 4 | — | — |
| [ASRock](docs/content/hardware/compatibility.md#asrock) | — | — | 4 | — | — |
| [ASUS](docs/content/hardware/compatibility.md#asus) | 10 | — | 10 | — | `asus` |
| [Cooler Master](docs/content/hardware/compatibility.md#coolermaster) | — | — | 20 | — | — |
| [Corsair](docs/content/hardware/compatibility.md#corsair) | 49 | — | 34 | — | `corsair` |
| [Dygma](docs/content/hardware/compatibility.md#dygma) | — | — | — | 2 | `dygma` |
| [EVGA](docs/content/hardware/compatibility.md#evga) | — | — | 7 | — | — |
| [Fnatic](docs/content/hardware/compatibility.md#fnatic) | — | — | 3 | — | — |
| [Gigabyte](docs/content/hardware/compatibility.md#gigabyte) | — | — | 8 | — | — |
| [Glorious](docs/content/hardware/compatibility.md#glorious) | 1 | — | 4 | — | `qmk` |
| [Govee](docs/content/hardware/compatibility.md#govee) | 4 | — | — | — | `govee` |
| [HyperX](docs/content/hardware/compatibility.md#hyperx) | — | — | 16 | — | — |
| [HYTE](docs/content/hardware/compatibility.md#hyte) | — | — | 2 | — | — |
| [Lian Li](docs/content/hardware/compatibility.md#lianli) | 9 | — | 2 | — | `lianli` |
| [Logitech](docs/content/hardware/compatibility.md#logitech) | — | — | 9 | — | — |
| [Mountain](docs/content/hardware/compatibility.md#mountain) | — | — | 4 | — | — |
| [MSI](docs/content/hardware/compatibility.md#msi) | — | — | 11 | — | — |
| [Nanoleaf](docs/content/hardware/compatibility.md#nanoleaf) | 1 | — | — | — | `nanoleaf` |
| [Nollie](docs/content/hardware/compatibility.md#nollie) | 19 | — | — | — | `nollie` |
| [NZXT](docs/content/hardware/compatibility.md#nzxt) | — | — | 17 | — | — |
| [Philips](docs/content/hardware/compatibility.md#philips) | 1 | — | — | — | `hue` |
| [PrismRGB](docs/content/hardware/compatibility.md#prismrgb) | 3 | — | — | — | `nollie`, `prismrgb` |
| [QMK](docs/content/hardware/compatibility.md#qmk) | 10 | — | — | — | `qmk` |
| [Razer](docs/content/hardware/compatibility.md#razer) | 70 | — | 38 | — | `razer` |
| [Roccat](docs/content/hardware/compatibility.md#roccat) | — | — | 14 | — | — |
| [Sony](docs/content/hardware/compatibility.md#sony) | — | — | 3 | — | — |
| [SteelSeries](docs/content/hardware/compatibility.md#steelseries) | — | — | 6 | — | — |
| [Thermaltake](docs/content/hardware/compatibility.md#thermaltake) | — | — | 10 | — | — |
| [WLED](docs/content/hardware/compatibility.md#wled) | 1 | — | — | — | `wled` |
| [Wooting](docs/content/hardware/compatibility.md#wooting) | — | — | 4 | — | — |
New drivers land often. Full matrix: [docs/content/hardware/compatibility.md](docs/content/hardware/compatibility.md). If you own hardware Hypercolor doesn't support yet, see [CONTRIBUTING.md](CONTRIBUTING.md).
### 🖥️ Dual Render Path
- **Servo:** an embedded browser rendering HTML Canvas, WebGL, and GLSL shaders headless at
60fps. Existing community effects work unmodified.
- **wgpu:** native GPU shaders compiled to Vulkan, OpenGL, or Metal for maximum performance.
### 🎨 44 Built-In Effects
Hypercolor ships 44 built-in effects spanning ambient, audio-reactive, shader, and generative
styles. Ambient backgrounds, shader-heavy showpieces, and beat-synced visualizers. Every one is
open source and built to be forked.
| | | | |
| ------------- | ----------------- | ------------- | ------------- |
| Borealis | Neon City | Hyperspace | Cymatics |
| Synth Horizon | Fractalux | Iris | Arc Storm |
| Voidweaver | Lava Lamp | Ink Tide | Wormhole |
| Nebula Drift | Frequency Cascade | Spectral Fire | Cyber Descent |
| Bubble Garden | Nyan Dash | Deep Current | Breakthrough |
### 🗺️ Spatial Layout Engine
Map your physical desk in the UI. Drag devices onto a 2D canvas, define LED topologies (strips,
matrices, rings), and the spatial sampler resolves pixels to LEDs. Pick nearest, bilinear, area
average, or Gaussian sampling at every position.
### 🎧 Audio-Reactive Pipeline
FFT with beat detection, mel-band analysis, chromagram, and spectral features. Effects react
to bass hits, BPM, spectral centroid, or the full 200-bin spectrum. Lock-free buffering keeps
the render loop from ever blocking on audio.
### 🌊 And More
- **Scene engine** with priority stacking, Oklab cross-fades, and automation rules
- **REST API + WebSocket** for full programmatic control
- **MCP server** for AI assistant integration (Claude Code, Cursor, and friends)
- **CLI tool** (`hypercolor`) with table/JSON output and shell completions
- **Hot-reload** on effect changes, no restart required
- **Screen capture** input for ambient backlighting
- **Linux session integration** (logind, screensaver) via D-Bus
## 💎 The UI
A web UI served directly by the daemon. Browse effects, tweak controls live, manage devices,
and design spatial layouts from any browser.
Effects browser with live preview
Control panel with canvas preview
Drag-and-drop spatial layout editor
Device management
- **Effects browser:** search, filter by category, favorites, audio-reactive tags
- **Live canvas preview:** the active effect streams in the sidebar and control panel
- **Auto-generated controls:** sliders, dropdowns, color pickers, and toggles derived from
effect metadata
- **Spatial layout editor:** drag-and-drop device placement on a 2D canvas
- **Ambient reactivity:** the UI tints its edges to match the active effect
- **Command palette** (⌘K) for keyboard-driven navigation
## 🖥️ The TUI
A terminal UI with true-color LED preview, audio visualization, and fullscreen effect rendering.
Runs wherever you have a terminal.
Dashboard with live preview and device table
Effects browser with control sliders
Bubble Garden fullscreen
Cymatics fullscreen
- **Live effect preview** rendered in true-color half-block characters
- **Fullscreen mode** (F11) fills the entire terminal with the active effect
- **Audio spectrum** with level meter and beat indicators
- **Quick actions:** number keys for instant effect switching
## 🎯 Get Started
Hypercolor is Linux-first. macOS release builds and Windows source builds exist, but Linux is
the supported launch path for hardware permissions, services, and full runtime verification.
### Install on Linux
```bash
git clone https://github.com/hyperb1iss/hypercolor.git
cd hypercolor
cargo install just
just setup
just install
```
Setup installs the Rust toolchain, system packages, Bun, Trunk, cargo-deny, and frontend
dependencies. The installer then builds the daemon, CLI, TUI, web UI, and bundled effects,
installs a systemd user service, sets up udev rules for USB device access, and persists
`i2c-dev` so SMBus RGB devices survive reboot.
### Install on Windows
Download the installer from the
[GitHub releases page](https://github.com/hyperb1iss/hypercolor/releases) and run it.
Per-user install (no UAC unless you opt into motherboard/RAM RGB hardware support, which
installs the [PawnIO](https://github.com/namazso/PawnIO) kernel driver via a one-click
flow). Tested on Windows 10 22H2 and Windows 11 23H2/24H2, x64.
Hue, WLED, Nanoleaf, Govee, and USB-HID lighting (Razer, Corsair, Lian Li, etc.) work out
of the box. Motherboard / DRAM SMBus lighting (ASUS Aura, MSI, Gigabyte) requires the
optional PawnIO install — Hypercolor prompts you only if compatible hardware is detected.
### Install on macOS
Download `Hypercolor--arm64.dmg` (Apple Silicon) or `-x86_64.dmg` (Intel)
from the [GitHub releases page](https://github.com/hyperb1iss/hypercolor/releases),
drag the app into `/Applications`, and launch. Minimum macOS 11 (Big Sur).
Or via Homebrew Cask once the tap is published:
```bash
brew install --cask hyperb1iss/tap/hypercolor-app
```
> While we're finishing the Developer ID + notarization rollout, current builds are
> unsigned. Gatekeeper will block them on first launch — right-click the app and choose
> **Open** to confirm. Signed + notarized builds land with the next release.
Hue, WLED, Nanoleaf, Govee, and USB-HID lighting (Razer, Corsair, Lian Li, etc.) work
out of the box. On first run, Hypercolor will prompt for Microphone and Screen Recording
permissions only if you enable audio- or screen-reactive effects.
### Run
```bash
# Start the daemon (serves UI at http://localhost:9420)
hypercolor-daemon
# Control from the command line
hypercolor effects list
hypercolor effects activate "Neon City"
hypercolor devices list
# Or drop into the interactive terminal dashboard (auto-starts a local daemon)
hypercolor tui
```
### Development
Hacking on Hypercolor itself? We use [just](https://github.com/casey/just) for development
workflows.
```bash
just daemon # Run daemon locally
just tui # Run the TUI
just ui-dev # Leptos UI dev server on :9430
just sdk-dev # SDK dev server with HMR
just verify # fmt + lint + test
```
`just verify` covers the Rust workspace. Use the focused gates for surfaces outside
that workspace: `just ui-test && just ui-build` for the Leptos UI, `just sdk-lint
&& just sdk-check && just sdk-build` for the TypeScript SDK, `just python-verify`
for the Python client, `just compat-check` for device data, and `just docs-build`
for documentation.
## ✦ The Effect SDK
Effects are TypeScript, Canvas, or pure GLSL. The SDK compiles them to self-contained HTML
files that the engine renders at 60fps. Audio data, control values, and canvas context are
all injected automatically.
```typescript
import { effect } from "@hypercolor/sdk";
import shader from "./fragment.glsl";
export default effect(
"Borealis",
shader,
{
speed: [1, 10, 5], // → slider
intensity: [0, 100, 82], // → slider
palette: ["Northern Lights", "SilkCircuit", "Cyberpunk"], // → dropdown
},
{
description: "Aurora borealis, layered curtains of light",
},
);
```
Four tiers, pick the one that fits: **GLSL** (single file, zero JS), **`effect()`** (one-liner
shader binding), **`canvas()`** (Canvas 2D draw functions), and **full OOP** (class-based with
lifecycle hooks).
See the [Effect SDK Guide](docs/content/effects/_index.md) for the full API reference.
## 🏗️ Architecture
```mermaid
graph TD
subgraph types [hypercolor-types]
T[Shared vocabulary
zero deps]
end
subgraph hal [hypercolor-hal]
H[USB/HID Drivers
Razer · Corsair · ASUS · Nollie · QMK · ...]
end
subgraph platform [Platform Interop]
LGI[linux-gpu-interop
GL→wgpu texture import]
WPI[windows-pawnio
SMBus via PawnIO]
end
subgraph core [hypercolor-core]
C[Engine
render loop · spatial · audio · effects]
end
subgraph drivers [Network Drivers]
API[driver-api]
DB[driver-builtin
compile-time bundle]
API --> HUE[Hue]
API --> NL[Nanoleaf]
API --> WL[WLED]
API --> GV[Govee]
HUE & NL & WL & GV --> DB
end
subgraph daemon [hypercolor-daemon]
D[REST API · WebSocket · MCP
Axum on :9420]
end
subgraph clients [Clients]
CLI[CLI
hypercolor]
TUI[TUI
Ratatui]
UI[Web UI
Leptos WASM]
DT[Desktop
Tauri]
TR[Tray
System applet]
APP[app
unified shell]
end
T --> H & C & LGI & WPI
H --> C
LGI & WPI --> C
C --> API
H --> DB
C & H & DB --> D
D --> CLI & TUI & UI
APP --> DT & TR & D
```
It's Rust all the way down. The daemon, CLI, TUI, tray applet, and HAL drivers are
all Rust. The web UI is Rust compiled to WASM via Leptos. Even the embedded browser
is Servo (Rust). The only non-Rust code is the TypeScript effect SDK and the GLSL
shaders it compiles.
The render thread runs on a dedicated OS thread with adaptive FPS (10 to 60, auto-shifting
across 5 tiers based on measured budget). Each tick, SparkleFlinger composes frame producers
into one canonical surface, with a zero-copy bypass fast path when a single full-opacity
layer is active. The event bus uses lock-free `tokio::sync::watch` channels for high-frequency
frame data and `broadcast` for discrete events. `zerocopy` structs handle wire-format encoding
at zero allocation cost per frame. The spatial engine caches LED positions and samples the
composed frame with configurable interpolation (nearest, bilinear, area average, Gaussian).
Workspace lints forbid `unsafe` in application, driver, and domain crates. The explicit
exceptions are audited platform interop crates:
[`hypercolor-linux-gpu-interop`](crates/hypercolor-linux-gpu-interop) for Linux GPU
surface import and [`hypercolor-windows-pawnio`](crates/hypercolor-windows-pawnio)
for Windows service/process boundaries. Both deny undocumented unsafe blocks. Edition
2024. Rust 1.94+.
## 📡 Status
Hypercolor is in active development (v0.1.0). The core engine, effect SDK, web UI, TUI, and
11 shipping driver families all work today on Linux. macOS arm64 release artifacts and
Windows source builds are experimental until their installer and runtime gates match Linux.
Every screenshot in this README was captured from a live instance running on real hardware.
Known launch limitations:
- Linux is the only fully supported install and runtime path for v0.1.0.
- SDK packages are pre-release and use local checkout or `file:` dependencies until npm publish.
- The Python client is source-only for launch and is not published to PyPI yet.
- Windows hardware service setup remains experimental.
**Coming soon:** effect marketplace, Wasmtime plugin system for community backends, Wooting
analog keyboards, and driver families for Cooler Master, NZXT, and Logitech. See the
[full compatibility matrix](docs/content/hardware/compatibility.md) for researched hardware
waiting on implementation.
## Security And Conduct
Please report vulnerabilities through the process in [`SECURITY.md`](SECURITY.md). Community
participation follows the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
## 💜 Contributing
Hypercolor grows on contributions. Drivers, effects, UI polish, docs, all of it lands here.
**Writing effects** is the fastest way in. The SDK compiles TypeScript, Canvas, or GLSL
straight to HTML, and the engine picks them up on save. **Device drivers** are where the
leverage is highest. If you own hardware that isn't on the supported list, you're the person
to add it.
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines.
## 📄 License
Apache-2.0. See [LICENSE](LICENSE).
---
If Hypercolor lights up your desk, give us a ⭐ or support the project
✦ Built with obsession by Hyperbliss ✦