hyperhdr-py-sickkick 0.2.0

HyperHDR Ambient Lighting Python Package

hyperhdr-py

A Python library for controlling HyperHDR ambient lighting systems.

This library is a modified version of Dermot Duffy's excellent hyperion-py.

Features

• Full async support with asyncio
• Connect to HyperHDR JSON API
• Control colors, effects, components, and more
• Subscribe to real-time state updates
• Support for HyperHDR v19 through v22+
• Websocket LED color/gradient streaming (optional; requires aiohttp)

New in v0.1.0 (HyperHDR v20-v22 support)

• Average color calculation - Get the average color of current LED output
• Smoothing control - Dynamically adjust smoothing parameters including new v22 interpolators
• HDR tone mapping - Control HDR tone mapping mode including automatic detection (v21+)
• Service discovery - Discover HyperHDR services on the network
• Current LED colors - Get the current colors being sent to LEDs
• Performance benchmarking - Run performance benchmarks
• Config management - Save/load configuration database

Installation

pip install hyperhdr-py-sickkick

Quick Start

import asyncio
from hyperhdr import client, const

async def main():
    async with client.HyperHDRClient("hyperhdr.local") as hc:
        if hc:
            # Get brightness
            adjustment = hc.adjustment
            if adjustment:
                print(f"Brightness: {adjustment[0][const.KEY_BRIGHTNESS]}%")

            # Set a color
            await hc.async_set_color(color=[255, 0, 0], priority=50)

            # Set an effect
            await hc.async_set_effect(effect={"name": "Rainbow swirl"}, priority=50)

asyncio.run(main())

LED Streaming (WebSocket)

Install dependencies before using the stream helpers:

pip install aiohttp

If you enable convert_to_jpeg=True, install Pillow as well:

pip install Pillow

Or install the optional extras:

pip install "hyperhdr-py-sickkick[stream]"

pip install "hyperhdr-py-sickkick[stream-jpeg]"

import asyncio
from hyperhdr.stream import HyperHDRLedColorsStream, HyperHDRLedGradientStream

async def main():
    led_colors = HyperHDRLedColorsStream("hyperhdr.local", token="YOUR_TOKEN")
    await led_colors.start()
    frame = await led_colors.wait_for_frame()
    if frame and frame.raw:
        print("LED bytes:", len(frame.raw))
    await led_colors.stop()

    led_gradient = HyperHDRLedGradientStream("hyperhdr.local")
    async for frame in led_gradient.frames():
        print("Gradient update:", frame.source)
        break
    await led_gradient.stop()

asyncio.run(main())

See examples/stream_leds.py for a standalone script.

Thank you dermotduffy!

This library would not exist without the excellent work on hyperion-py.

Feel free to open an issue if you run into any problems!