🌈 signalrgb-python

🌟 Features

• List available lighting effects, presets, and layouts
• Apply effects, presets, and layouts to your devices
• Control canvas brightness and enabled state
• Synchronous client for scripts and tools
• Asynchronous client (httpx) for asyncio apps and Home Assistant integrations
• Rich-powered CLI with intuitive subcommands (effect, preset, layout, canvas)
• Effect caching and robust exception types for connection, API, and not-found errors

💎 Installation

# with uv (recommended)
uv add signalrgb

# or with pip
pip install signalrgb

Prerequisites

• Python 3.13+
• SignalRGB Pro — required for API access

This library uses the SignalRGB REST API, which is only available in SignalRGB Pro.

🎯 Usage

Command-line interface

The CLI is a Rich + Typer app with category subcommands for effects, presets, layouts, and canvas control.

# Effects
signalrgb effect list
signalrgb effect "Psychedelic Dream"
signalrgb effect apply "Rave Visualizer"
signalrgb effect random
signalrgb effect search "ocean"

# Presets
signalrgb preset list
signalrgb preset apply "My Fancy Preset"

# Layouts
signalrgb layout list
signalrgb layout set "My Gaming Layout"

# Canvas
signalrgb canvas                     # show state + brightness
signalrgb canvas brightness 75       # set brightness
signalrgb canvas brightness          # read brightness
signalrgb canvas enable
signalrgb canvas disable
signalrgb canvas toggle

Point at a remote SignalRGB instance:

signalrgb --host hyperia.home --port 16038 effect list

Full help:

signalrgb --help

Synchronous client

from signalrgb import SignalRGBClient

client = SignalRGBClient(host="hyperia.home", port=16038)

# List effects
for effect in client.get_effects():
    print(effect.attributes.name)

# Apply an effect and a preset
client.apply_effect_by_name("Rain")
current = client.get_current_effect()
client.apply_effect_preset(current.id, "Cool Preset")

# Canvas control
client.brightness = 50
client.enabled = True

Asynchronous client

For async apps and Home Assistant integrations, use AsyncSignalRGBClient as an async context manager:

import asyncio
from signalrgb import AsyncSignalRGBClient

async def main() -> None:
    async with AsyncSignalRGBClient(host="hyperia.home", port=16038) as client:
        for effect in await client.get_effects():
            print(effect.attributes.name)

        await client.apply_effect_by_name("Rain")
        await client.set_brightness(75)
        await client.set_enabled(True)

        current = await client.get_current_effect()
        print(f"Current effect: {current.attributes.name}")

asyncio.run(main())

See the Async Client reference for the full async guide.

Error handling

from signalrgb import SignalRGBClient, ConnectionError, APIError, NotFoundError

client = SignalRGBClient()

try:
    client.apply_effect_by_name("Non-existent Effect")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except NotFoundError as e:
    print(f"Effect not found: {e}")
except APIError as e:
    print(f"API error: {e}")

The same pattern works with the async client.

🔮 API Reference

Full API docs are published at https://hyperb1iss.github.io/signalrgb-python/.

🧪 Development

The project uses the Astral stack: uv for packaging, ruff for lint + format, ty for type checking, and pytest for tests. All common tasks are wired up in the justfile.

# Clone and set up
git clone https://github.com/hyperb1iss/signalrgb-python.git
cd signalrgb-python

# Install everything (runtime + dev + docs)
just install

# Run the full check suite (lint, format, typecheck, tests)
just verify

# Or the fast loop (auto-fix then test)
just check

# Other common tasks
just test              # pytest with coverage
just lint-fix          # ruff check --fix
just fmt               # ruff format
just typecheck         # ty check
just docs-serve        # mkdocs on :8000
just run effect list   # run the CLI
just --list            # see everything

See the Development Guide for the full workflow.

🦋 Contributing

Contributions are welcome. Fork, branch, and open a PR:

1. Fork the repository
2. Create a branch: git checkout -b my-feature
3. just verify should pass before you push
4. Open a pull request

Please include tests for new functionality and follow the existing code style (ruff + ty will tell you if anything's off).

📄 License

Apache License 2.0 — see LICENSE.

💜 Acknowledgements

This project is not officially associated with SignalRGB. It is an independent community client — please do not report client issues to the SignalRGB team.