{"id":50146808,"url":"https://github.com/shaffer-softworks/hyperhdr-ha","last_synced_at":"2026-05-24T05:08:52.874Z","repository":{"id":44136310,"uuid":"435940948","full_name":"Shaffer-Softworks/hyperhdr-ha","owner":"Shaffer-Softworks","description":"HyperHDR custom component for Home Assistant","archived":false,"fork":false,"pushed_at":"2026-05-21T03:26:50.000Z","size":473,"stargazers_count":93,"open_issues_count":0,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-05-21T06:59:46.022Z","etag":null,"topics":["backlight","bias-lighting","custom-component","home-assistant","hyperhdr"],"latest_commit_sha":null,"homepage":"https://github.com/awawa-dev/HyperHDR","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shaffer-Softworks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-12-07T15:53:35.000Z","updated_at":"2026-05-21T03:26:49.000Z","dependencies_parsed_at":"2026-02-14T08:01:29.320Z","dependency_job_id":null,"html_url":"https://github.com/Shaffer-Softworks/hyperhdr-ha","commit_stats":null,"previous_names":["shaffer-softworks/hyperhdr-ha"],"tags_count":24,"template":false,"template_full_name":"ludeeus/integration_blueprint","purl":"pkg:github/Shaffer-Softworks/hyperhdr-ha","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shaffer-Softworks%2Fhyperhdr-ha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shaffer-Softworks%2Fhyperhdr-ha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shaffer-Softworks%2Fhyperhdr-ha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shaffer-Softworks%2Fhyperhdr-ha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shaffer-Softworks","download_url":"https://codeload.github.com/Shaffer-Softworks/hyperhdr-ha/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shaffer-Softworks%2Fhyperhdr-ha/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33422108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backlight","bias-lighting","custom-component","home-assistant","hyperhdr"],"created_at":"2026-05-24T05:08:29.080Z","updated_at":"2026-05-24T05:08:52.860Z","avatar_url":"https://github.com/Shaffer-Softworks.png","language":"Python","funding_links":["https://www.buymeacoffee.com/ludeeus"],"categories":[],"sub_categories":[],"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)\n[![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)\n[![HACS Default](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/default)\n\n# HyperHDR custom component for Home Assistant\n\nHyperHDR is an open source bias lighting implementation which runs on many platforms.\n\n**This component will set up the following platforms.**\n\n| Platform | Description |\n|----------|-------------|\n| `button` | Clear the configured HyperHDR priority slot (releases solid/effect control). |\n| `camera` | Live LED Colors and LED Gradient camera streams via WebSocket. |\n| `light` | Control HyperHDR lighting with color, brightness, and effects. |\n| `sensor` | Monitor visible priority and average color information. |\n| `switch` | Toggle HyperHDR components (smoothing, HDR tone mapping, blackborder detection, etc.). |\n| `number` | Adjust HDR tone mapping intensity. Smoothing parameters (time, decay, update frequency) are available when the server exposes smoothing data. |\n| `select` | Choose smoothing type (linear, exponential, inertia, hybrid, yuv) when the server exposes smoothing data. |\n\n### Key Features\n\n- **LED Colors Camera**: Live WebSocket stream of the HyperHDR imagestream output — ideal for PicCap instances or visualizing exact LED output.\n- **LED Gradient Camera**: Real-time per-LED gradient visualization rendered as a JPEG image from raw RGB data.\n- **Average Color Sensor**: Real-time average color display with hex value and RGB attributes (computed from LED stream data with throttled updates).\n- **HDR Tone Mapping**: Adjust HDR tone mapping intensity with a dedicated number entity. Supports both legacy `hdrToneMappingMode` and the newer `videomodehdr` command paths.\n- **Smoothing Controls** *(conditional)*: Number entities for time, decay, and update frequency — only created when the connected HyperHDR server exposes smoothing data.\n- **Smoothing Type Selection** *(conditional)*: Choose from multiple smoothing interpolation algorithms — only created when smoothing data is available.\n- **Component Switches**: Enable/disable HyperHDR components (advanced users).\n- **Automatic Entity Cleanup**: Stale entities from removed features (old camera, color engine, unsupported smoothing) are automatically pruned from the entity registry on integration load.\n- **SSDP Auto-Discovery**: HyperHDR instances on your network are automatically discovered via SSDP/UPnP — no manual IP entry required.\n\n![hyperhdr-logo](https://github.com/Shaffer-Softworks/hyperhdr-ha/blob/master/hyperhdr-logo.png)\n\n## Installation\n\n### Using HACS\n\nThis integration is made available through the Home Assistant Community Store default feed. Simply search for **HyperHDR** and install it directly from HACS.\n\nPlease see the [official HACS documentation](https://hacs.xyz/docs/) for information on how to install and use HACS.\n\nRestart Home Assistant after installation. For setup and troubleshooting, see the [project wiki](https://github.com/Shaffer-Softworks/hyperhdr-ha/wiki).\n\n### Manually (not recommended)\n\n- 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.\n- Restart Home Assistant to load the integration.\n\n**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.\n\n## Configuration\n\n### Automatic Discovery (SSDP)\n\nHyperHDR 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.\n\n### Manual Setup\n\n1. In Home Assistant navigate to `Configuration` -\u003e `Devices \u0026 Services` -\u003e `Integrations`.\n1. Click the `+ Add Integration` button.\n1. Search for `HyperHDR`.\n1. 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.\n1. Enter the IP address of your HyperHDR instance.\n1. *(Optional)* Enter the **WebSocket Port** (defaults to `8090`) if your HyperHDR UI/WebSocket runs on a non-standard port.\n1. *(Optional)* Enter your **Admin Password** if your HyperHDR instance has Local API Authentication enabled.\n1. Click the `Submit` button.\n\n### Admin Password\n\nIf 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:\n\n- **During initial setup** — enter it in the optional \"Admin Password\" field on the connection form.\n- **After setup** — go to the integration's **Options** (gear icon) and add or change the admin password there.\n\nWhen 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.\n\n### Options Flow\n\nAfter the integration is set up, you can adjust the following via **Options** (gear icon on the integration card):\n\n| Option | Description |\n|--------|-------------|\n| **Priority** | Default priority level for light commands (0–255). |\n| **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. |\n| **Effect Show List** | Select which effects to expose in Home Assistant. |\n| **WebSocket Port** | Port for LED camera streams (default `8090`). |\n| **Admin Password** | Password for LED stream authentication. |\n\n## Advanced Features\n\n### Entity Discovery\n\nEntities are created automatically for each running HyperHDR instance:\n\n- **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.\n- **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.\n- **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.\n\n### Automatic Stale Entity Cleanup\n\nWhen upgrading from older versions, the integration automatically removes stale entities from the Home Assistant entity registry:\n\n- **Permanently removed**: The old JSON-API camera entity and the Color Engine select entity are always cleaned up.\n- **Conditionally removed**: Smoothing entities (time, decay, update frequency, type) are removed for any instance whose server does not expose smoothing data.\n\nNo manual intervention is required — the cleanup runs on every integration load.\n\n### LED Colors Camera\n\nThe **LED Colors** camera entity streams the HyperHDR imagestream over a dedicated WebSocket connection.\n\n- **Purpose**: Designed for **PicCap** instances where the standard MJPEG stream may not work, or for visualizing the exact LED output.\n- **Disabled by Default**: This entity is **disabled by default**. You must enable it in Home Assistant settings.\n- **Stream Type**: Uses `HyperHDRLedColorsStream` from `hyperhdr.stream` with automatic reconnection and admin password authentication.\n- **Authentication**: Requires admin password for instances with Local API Authentication enabled (token-only auth is insufficient for imagestream).\n\n### LED Gradient Camera\n\nThe **LED Gradient** camera entity visualizes the raw per-LED color data as a gradient image.\n\n- **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.\n- **Disabled by Default**: This entity is **disabled by default**. Enable it in Home Assistant settings if desired.\n- **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.\n- **Image Format**: Raw binary LED data (RGB bytes) is converted into a 1-pixel-tall JPEG image scaled to 20px height for visibility.\n- **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).\n\n### Camera Troubleshooting\n\nIf the camera entities are not streaming:\n\n1. **Verify authentication**: Ensure the admin password is configured correctly (check integration Options).\n2. **Enable debug logging**:\n   ```yaml\n   logger:\n     logs:\n       custom_components.hyperhdr.camera: debug\n       hyperhdr.stream: debug\n   ```\n3. **Check HyperHDR is streaming**: Confirm your HyperHDR instance has an active video source (USB Capture, Video Grabber, etc.).\n4. **Check the WebSocket port**: The default is `8090` — make sure it matches your HyperHDR configuration.\n\n**Viewing options in Home Assistant:**\n- **Lovelace** — Add a camera card to your dashboard for live preview.\n- **Developer Tools** — Use the Camera entity to view the current snapshot.\n- **Mobile App** — View the live stream in the Home Assistant mobile application.\n- **MJPEG Stream** — Access the raw stream at `/api/camera_proxy_stream/camera.\u003centity_id\u003e`.\n\n\u003c!-- ***\n\n[integration_blueprint]: https://github.com/custom-components/integration_blueprint\n[buymecoffee]: https://www.buymeacoffee.com/ludeeus\n[buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?style=for-the-badge\n[commits-shield]: https://img.shields.io/github/commit-activity/y/custom-components/integration_blueprint.svg?style=for-the-badge\n[commits]: https://github.com/custom-components/integration_blueprint/commits/master\n[hacs]: https://hacs.xyz\n[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge\n[discord]: https://discord.gg/Qa5fW2R\n[discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge\n[exampleimg]: example.png\n[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge\n[forum]: https://community.home-assistant.io/\n[license]: https://github.com/custom-components/integration_blueprint/blob/main/LICENSE\n[license-shield]: https://img.shields.io/github/license/custom-components/integration_blueprint.svg?style=for-the-badge\n[maintenance-shield]: https://img.shields.io/badge/maintainer-Joakim%20Sørensen%20%40ludeeus-blue.svg?style=for-the-badge\n[releases-shield]: https://img.shields.io/github/release/custom-components/integration_blueprint.svg?style=for-the-badge\n[releases]: https://github.com/custom-components/integration_blueprint/releases\n[user_profile]: https://github.com/ludeeus --\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaffer-softworks%2Fhyperhdr-ha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshaffer-softworks%2Fhyperhdr-ha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaffer-softworks%2Fhyperhdr-ha/lists"}