openrgb-hue

Turn Philips Hue scene palettes into gradients and animations on your OpenRGB-controlled lights — motherboards, GPUs, LED strips, keyboards, and anything else OpenRGB can see.

Features

• 103 bundled Philips Hue scenes, each turned into a smooth, cyclic gradient (RGB or HSV interpolation).
• Six mapping modes for how the gradient lands on your actual LEDs: sequence, per-device, per-zone, matrix (with directional variants for keyboards and other grid devices), mirror, shuffle.
• Five animation modes: static, scroll, pingpong, pulse, wave.
• A polished terminal UI (via Typer + Rich) with true-color gradient/scene swatch previews.
• --dry-run on apply/animate renders a full preview against a synthetic LED layout — no OpenRGB connection required.
• Works fully offline; refresh the bundled scene dataset on demand with openrgb-hue scenes update.

Prerequisites

• Python 3.10+
• OpenRGB installed and running, with its SDK Server started (Settings → SDK Server → Start Server). Default: 127.0.0.1:6742.

Installation

pip install openrgb-hue

From source, for development:

git clone <this-repo>
cd openrgb-hue
pip install -e ".[dev]"

Quickstart

# See what OpenRGB can see.
openrgb-hue devices

# Browse the bundled Hue scenes.
openrgb-hue scenes list
openrgb-hue scenes show "Tropical twilight"

# Apply a scene as a static gradient across every connected LED.
openrgb-hue apply "Tropical twilight"

# ...or animate it, scrolling across your lights until you press Ctrl+C.
openrgb-hue animate "Tropical twilight" --mode scroll

Concepts

From scene to gradient

Each bundled Hue scene is a small discrete color palette (usually 2-6 distinct colors) recorded across up to 10 lights. openrgb-hue turns that into a gradient by:

1. Reading each light's color in its recorded order.
2. Optionally scaling each color by that light's recorded brightness (--brightness/--no-brightness, on by default).
3. Collapsing consecutive duplicate colors into one gradient stop (--dedupe/--no-dedupe, on by default) so flat repeated segments don't waste gradient space.
4. Spacing the resulting colors evenly across [0, 1] and interpolating between them — in RGB or HSV space (--interpolation rgb|hsv, HSV by default, since it avoids muddy grey midpoints between distant hues).

The gradient is always cyclic: the last stop blends back into the first. This is what makes scroll and pingpong animation seamless.

Preview exactly what a scene's gradient looks like with:

openrgb-hue scenes show "Blossom" --interpolation rgb --no-dedupe

Mapping modes

Mapping decides where on the gradient each physical LED sits.

Mode	Description
sequence (default)	All targeted LEDs, in order, span the gradient once.
per-device	Every device shows the full gradient independently (e.g. each LED strip gets its own rainbow).
per-zone	Like per-device, but per zone — useful for multi-zone devices (e.g. a case with front/top fans).
matrix	2D directional mapping for grid devices (keyboards, LED matrices), using --direction.
mirror	The gradient plays forward then backward across the target set (a spatial ping-pong layout).
shuffle	The gradient's colors are assigned to LEDs in a randomized (but seed-deterministic) order.

matrix mode supports four --direction values:

• left-right — gradient flows across columns.
• top-bottom — gradient flows across rows.
• diagonal — gradient flows from the top-left corner to the bottom-right.
• radial — gradient flows outward from the grid's center.

openrgb-hue apply "Savanna sunset" --mapping per-device
openrgb-hue apply "Savanna sunset" --device-type keyboard --mapping matrix --direction radial

Animation modes

Animation decides how the mapped gradient changes over time. Any animation mode works with any mapping mode: mapping only ever produces a static per-LED gradient position, and animation only ever shifts that position and/or brightness over time.

Mode	Description	Key flags
static	No motion (used internally by apply; useful with animate --duration to just hold a look).	—
scroll (default for animate)	The gradient continuously translates, wrapping seamlessly.	--speed (cycles/sec)
pingpong	Like scroll, but reverses direction at the ends instead of wrapping.	--speed
pulse	The whole gradient's brightness breathes sinusoidally.	--speed (Hz), --min-brightness
wave	A brightness sine wave travels spatially across the LEDs.	--speed, --min-brightness, --wavelength

openrgb-hue animate "Tropical twilight" --mode wave --speed 0.3 --wavelength 3 --fps 60
openrgb-hue animate "Relax" --mode pulse --min-brightness 0.1 --duration 30

Full command reference

openrgb-hue [--host HOST] [--port PORT] [--version] COMMAND [ARGS]...

  devices [--leds]                    List connected OpenRGB devices (and optionally zones/LEDs).

  scenes list [--filter TEXT]         List bundled Hue scenes with a gradient preview.
  scenes show NAME [...]              Show a scene's raw light data and derived gradient.
  scenes update [--url] [--timeout]   Refresh the bundled scene dataset from the source gist.

  apply SCENE [OPTIONS]               Apply a scene as a static gradient.
  animate SCENE [OPTIONS]             Apply a scene as an animated gradient.

  off [--device] [--device-type] [--zone]   Turn off targeted (or all) LEDs.
  clear                                     Turn off every LED on every device.

Run openrgb-hue COMMAND --help for the full, up-to-date flag list of any command — every flag mentioned in this README (mapping/animation options, targeting filters, dry-run flags, etc.) is documented there too.

Targeting devices and zones

apply, animate, and off all accept repeatable filters:

• --device NAME — match devices with this exact name (case-insensitive).
• --device-type TYPE — match devices of this type, e.g. gpu, motherboard, ledstrip, keyboard (case-insensitive).
• --zone NAME — match zones with this exact name (case-insensitive).

Filters within the same category are OR'd together; different categories are AND'd. No filters means "every LED on every device". Run openrgb-hue devices --leds to see exact device, zone, and LED names.

openrgb-hue apply "Bright" --device-type gpu --device-type motherboard
openrgb-hue apply "Bright" --zone "Front Fans"

Dry-run / preview without hardware

Both apply and animate accept --dry-run, which runs the full targets → mapping → gradient (→ animation) pipeline against a small synthetic LED layout and prints the result as terminal swatches — no OpenRGB connection needed. Useful for previewing a look before touching real hardware, or for trying out mapping/animation combinations when OpenRGB isn't running.

openrgb-hue apply "Blossom" --dry-run --mapping matrix --direction diagonal
openrgb-hue animate "Blossom" --dry-run --mode wave --dry-run-frames 8

--dry-run-leds N synthesizes N flat LEDs instead of the default mixed layout (two linear strips plus a 4x4 matrix zone). --dry-run-frames N (on animate) controls how many evenly-spaced sample frames are printed.

Troubleshooting

"Could not connect to the OpenRGB SDK server" — make sure the OpenRGB app is running and its SDK Server has been started (Settings → SDK Server → Start Server). If it's running on a different host/port, pass --host/--port (or set the OPENRGB_HOST/OPENRGB_PORT environment variables).

Data attribution

The bundled scene data (src/openrgb_hue/data/philips-hue-scenes.csv) is sourced from a public gist compiled by GitHub user labmonkey, capturing the default Philips Hue app scenes and their per-light colors via the Home Assistant API. No explicit license is stated by the source gist; it's used here, with attribution, as a factual color dataset. Run openrgb-hue scenes update to refresh from the source at any time. See src/openrgb_hue/data/ATTRIBUTION.txt for the full note.

License

The code in this repository is licensed under the MIT License. The bundled scene dataset's licensing follows the source gist (see above).

Contributing

Issues and pull requests are welcome. Run the test suite with:

pip install -e ".[dev]"
pytest