Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/shaffer-softworks/hyperhdr-ha

HyperHDR custom component for Home Assistant
https://github.com/shaffer-softworks/hyperhdr-ha

backlight bias-lighting custom-component home-assistant hyperhdr

Last synced: about 1 month ago
JSON representation

HyperHDR custom component for Home Assistant

Awesome Lists containing this project

README 

          
[![CodeQL](https://github.com/Shaffer-Softworks/hyperhdr-ha/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/Shaffer-Softworks/hyperhdr-ha/actions/workflows/github-code-scanning/codeql)

[![Validate](https://github.com/Shaffer-Softworks/hyperhdr-ha/actions/workflows/validate.yaml/badge.svg)](https://github.com/Shaffer-Softworks/hyperhdr-ha/actions/workflows/validate.yaml)

[![HACS Default](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/default)



# HyperHDR custom component for Home Assistant



HyperHDR is an open source bias lighting implementation which runs on many platforms.



**This component will set up the following platforms.**



| Platform | Description |

|----------|-------------|

| `button` | Clear the configured HyperHDR priority slot (releases solid/effect control). |

| `camera` | Live LED Colors and LED Gradient camera streams via WebSocket. |

| `light` | Control HyperHDR lighting with color, brightness, and effects. |

| `sensor` | Monitor visible priority and average color information. |

| `switch` | Toggle HyperHDR components (smoothing, HDR tone mapping, blackborder detection, etc.). |

| `number` | Adjust HDR tone mapping intensity. Smoothing parameters (time, decay, update frequency) are available when the server exposes smoothing data. |

| `select` | Choose smoothing type (linear, exponential, inertia, hybrid, yuv) when the server exposes smoothing data. |



### Key Features



- **LED Colors Camera**: Live WebSocket stream of the HyperHDR imagestream output — ideal for PicCap instances or visualizing exact LED output.

- **LED Gradient Camera**: Real-time per-LED gradient visualization rendered as a JPEG image from raw RGB data.

- **Average Color Sensor**: Real-time average color display with hex value and RGB attributes (computed from LED stream data with throttled updates).

- **HDR Tone Mapping**: Adjust HDR tone mapping intensity with a dedicated number entity. Supports both legacy `hdrToneMappingMode` and the newer `videomodehdr` command paths.

- **Smoothing Controls** *(conditional)*: Number entities for time, decay, and update frequency — only created when the connected HyperHDR server exposes smoothing data.

- **Smoothing Type Selection** *(conditional)*: Choose from multiple smoothing interpolation algorithms — only created when smoothing data is available.

- **Component Switches**: Enable/disable HyperHDR components (advanced users).

- **Automatic Entity Cleanup**: Stale entities from removed features (old camera, color engine, unsupported smoothing) are automatically pruned from the entity registry on integration load.

- **SSDP Auto-Discovery**: HyperHDR instances on your network are automatically discovered via SSDP/UPnP — no manual IP entry required.



![hyperhdr-logo](https://github.com/Shaffer-Softworks/hyperhdr-ha/blob/master/hyperhdr-logo.png)



## Installation



### Using HACS



This integration is made available through the Home Assistant Community Store default feed. Simply search for **HyperHDR** and install it directly from HACS.



Please see the [official HACS documentation](https://hacs.xyz/docs/) for information on how to install and use HACS.



Restart Home Assistant after installation. For setup and troubleshooting, see the [project wiki](https://github.com/Shaffer-Softworks/hyperhdr-ha/wiki).



### Manually (not recommended)



- Download the [latest release](https://github.com/Shaffer-Softworks/hyperhdr-ha/releases) as a **zip file** then extract it and move the `hyperhdr` folder into the `custom_components` folder in your Home Assistant installation.

- Restart Home Assistant to load the integration.



**Dependencies**: This integration requires `hyperhdr-py-sickkick==0.2.1`. When installing via HACS, the package is installed automatically. For manual installation, ensure your Home Assistant environment has this package available.



## Configuration



### Automatic Discovery (SSDP)



HyperHDR instances on your local network are automatically discovered via **SSDP** (Simple Service Discovery Protocol). When a new instance is found, a notification appears in Home Assistant's Integrations page — just click **Configure** and confirm to set it up. The host, JSON API port, and WebSocket port are all populated automatically from the discovery data.



### Manual Setup



1. In Home Assistant navigate to `Configuration` -> `Devices & Services` -> `Integrations`.

1. Click the `+ Add Integration` button.

1. Search for `HyperHDR`.

1. If you cannot find `HyperHDR` in the list then be sure to clear your browser cache and/or perform a hard-refresh of the page.

1. Enter the IP address of your HyperHDR instance.

1. *(Optional)* Enter the **WebSocket Port** (defaults to `8090`) if your HyperHDR UI/WebSocket runs on a non-standard port.

1. *(Optional)* Enter your **Admin Password** if your HyperHDR instance has Local API Authentication enabled.

1. Click the `Submit` button.



### Admin Password



If your HyperHDR instance has **Local API Authentication** enabled, the LED camera streams require authentication to receive frames. You can provide the admin password in two places:



- **During initial setup** — enter it in the optional "Admin Password" field on the connection form.

- **After setup** — go to the integration's **Options** (gear icon) and add or change the admin password there.



When configured, the LED Colors and LED Gradient camera streams authenticate using the admin password over the WebSocket connection. If a token is also configured, the admin password takes priority for stream authentication (tokens do not grant the admin privileges required by `imagestream-start`). If your HyperHDR instance does not require authentication, you can leave this field blank.



### Options Flow



After the integration is set up, you can adjust the following via **Options** (gear icon on the integration card):



| Option | Description |

|--------|-------------|

| **Priority** | Default priority level for light commands (0–255). |

| **Clear priority when main light turns off** | When enabled, turning off the main HyperHDR Light sends HyperHDR's `clear` command at the configured priority so USB grabber and other lower-priority sources can take over again. Disabled by default; use the **Clear Priority** button or enable this option if you want automatic clearing. |

| **Effect Show List** | Select which effects to expose in Home Assistant. |

| **WebSocket Port** | Port for LED camera streams (default `8090`). |

| **Admin Password** | Password for LED stream authentication. |



## Advanced Features



### Entity Discovery



Entities are created automatically for each running HyperHDR instance:



- **Always created**: Light, Priority Light, Clear Priority button, Component Switches, HDR Tone Mapping, Visible Priority Sensor, Average Color Sensor, LED Colors Camera, LED Gradient Camera.

- **Conditionally created**: Smoothing Time, Smoothing Decay, Smoothing Update Frequency, and Smoothing Type entities are only created when the connected HyperHDR server exposes smoothing data in its `serverinfo` response. If the server does not expose this data, these entities are not created at all.

- **Disabled by default**: Camera entities and most number/select entities are disabled by default to avoid unnecessary overhead. Enable them in Home Assistant's entity settings if needed.



### Automatic Stale Entity Cleanup



When upgrading from older versions, the integration automatically removes stale entities from the Home Assistant entity registry:



- **Permanently removed**: The old JSON-API camera entity and the Color Engine select entity are always cleaned up.

- **Conditionally removed**: Smoothing entities (time, decay, update frequency, type) are removed for any instance whose server does not expose smoothing data.



No manual intervention is required — the cleanup runs on every integration load.



### LED Colors Camera



The **LED Colors** camera entity streams the HyperHDR imagestream over a dedicated WebSocket connection.



- **Purpose**: Designed for **PicCap** instances where the standard MJPEG stream may not work, or for visualizing the exact LED output.

- **Disabled by Default**: This entity is **disabled by default**. You must enable it in Home Assistant settings.

- **Stream Type**: Uses `HyperHDRLedColorsStream` from `hyperhdr.stream` with automatic reconnection and admin password authentication.

- **Authentication**: Requires admin password for instances with Local API Authentication enabled (token-only auth is insufficient for imagestream).



### LED Gradient Camera



The **LED Gradient** camera entity visualizes the raw per-LED color data as a gradient image.



- **Purpose**: Displays a JPEG image representing the current color of each LED, stretched to a visible height. Useful for monitoring individual LED output in real time.

- **Disabled by Default**: This entity is **disabled by default**. Enable it in Home Assistant settings if desired.

- **Stream Type**: Uses `HyperHDRLedGradientStream` from `hyperhdr.stream` with built-in RGB-to-JPEG conversion (via Pillow), automatic reconnection, and the same authentication support as the LED Colors camera.

- **Image Format**: Raw binary LED data (RGB bytes) is converted into a 1-pixel-tall JPEG image scaled to 20px height for visibility.

- **Average Color Dispatch**: This camera computes the average RGB color from each frame and dispatches it to the Average Color sensor (throttled to every 2 seconds to avoid flooding the event bus).



### Camera Troubleshooting



If the camera entities are not streaming:



1. **Verify authentication**: Ensure the admin password is configured correctly (check integration Options).

2. **Enable debug logging**:

   ```yaml

   logger:

     logs:

       custom_components.hyperhdr.camera: debug

       hyperhdr.stream: debug

   ```

3. **Check HyperHDR is streaming**: Confirm your HyperHDR instance has an active video source (USB Capture, Video Grabber, etc.).

4. **Check the WebSocket port**: The default is `8090` — make sure it matches your HyperHDR configuration.



**Viewing options in Home Assistant:**

- **Lovelace** — Add a camera card to your dashboard for live preview.

- **Developer Tools** — Use the Camera entity to view the current snapshot.

- **Mobile App** — View the live stream in the Home Assistant mobile application.

- **MJPEG Stream** — Access the raw stream at `/api/camera_proxy_stream/camera.`.