openrgb-hue/README.md

# openrgb-hue

Turn Philips Hue scene palettes into gradients and animations on your
[OpenRGB](https://openrgb.org/)-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](https://typer.tiangolo.com/) +
  [Rich](https://rich.readthedocs.io/)) 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](https://openrgb.org/) installed and running, with its **SDK
  Server started** (Settings → SDK Server → Start Server). Default:
  `127.0.0.1:6742`.

## Installation

```bash
pip install openrgb-hue
```

From source, for development:

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

## Quickstart

```bash
# 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:

```bash
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.

```bash
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` |

```bash
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.

```bash
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.

```bash
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](https://gist.github.com/labmonkey/a641f6b339ed9a71bdced64b9af91ee8),
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](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:

```bash
pip install -e ".[dev]"
pytest
```