🌈 signalrgb-python

A powerful Python client library and CLI for controlling SignalRGB Pro

Features • Installation • Usage • API Reference • Development • Contributing • License

✨ Features

• 📋 List available lighting effects and presets
• 🔍 Get detailed information about specific effects
• 🎨 Apply effects and presets to your devices with ease
• 🖼️ Manage and switch between different layouts
• 🔆 Control brightness levels
• 🔌 Enable or disable the canvas
• 🖥️ User-friendly command-line interface with intuitive subcommands
• 🐍 Python client library for seamless integration into your projects
• 🔐 Error handling and connection management
• 🔄 Automatic effect caching for improved performance
• ⚡ Native asyncio support for async applications and integrations

💻 Installation

You can install signalrgb-python using pip:

pip install signalrgb

Or if you prefer to use uv:

uv add signalrgb

Prerequisites

• Python 3.11 or higher
• SignalRGB Pro (required for API access)

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

🚀 Usage

Command-line Interface

signalrgb-python comes with an intuitive command-line interface for easy interaction with your SignalRGB setup. The CLI now uses a subcommand structure for better organization and extensibility.

# List all available effects
signalrgb effect list

# Get details of a specific effect
signalrgb effect "Psychedelic Dream"

# Apply an effect
signalrgb effect apply "Rave Visualizer"

# List presets for the current effect
signalrgb preset list

# Apply a preset to the current effect
signalrgb preset apply "My Fancy Preset"

# List available layouts
signalrgb layout list

# Set the current layout
signalrgb layout set "My Gaming Layout"

# Get the current effect
signalrgb effect

# Set brightness level (0-100)
signalrgb canvas brightness 75

# Get current brightness level
signalrgb canvas brightness

# Enable the canvas
signalrgb canvas enable

# Disable the canvas
signalrgb canvas disable

You can also specify a custom host and port:

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

For a full list of available commands and options, use:

signalrgb --help

Python Library

Synchronous API

Integrate signalrgb-python into your own Python projects with ease:

from signalrgb import SignalRGBClient

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

# List all effects
effects = client.get_effects()
for effect in effects:
    print(f"Effect: {effect.attributes.name}")

# Apply an effect
client.apply_effect_by_name("Rain")

# List presets for the current effect
current_effect = client.get_current_effect()
presets = client.get_effect_presets(current_effect.id)
for preset in presets:
    print(f"Preset: {preset.id}")

# Apply a preset
client.apply_effect_preset(current_effect.id, "Cool Preset")

# Get available layouts
layouts = client.get_layouts()
for layout in layouts:
    print(f"Layout: {layout.id}")

# Set the current layout
client.current_layout = "Gaming Setup"

# Control brightness
client.brightness = 50
print(f"Current brightness: {client.brightness}")

# Enable/disable the canvas
client.enabled = True
print(f"Canvas enabled: {client.enabled}")

Asynchronous API ⚡

For async applications like Home Assistant integrations, use the async API:

import asyncio
from signalrgb import AsyncSignalRGBClient

async def main():
    # Initialize the client with context manager for auto-cleanup
    async with AsyncSignalRGBClient(host="hyperia.home", port=16038) as client:
        # List all effects
        effects = await client.get_effects()
        for effect in effects:
            print(f"Effect: {effect.attributes.name}")

        # Apply an effect
        await client.apply_effect_by_name("Rain")

        # Get and update brightness
        brightness = await client.get_brightness()
        print(f"Current brightness: {brightness}")
        await client.set_brightness(75)

        # Enable/disable the canvas
        is_enabled = await client.get_enabled()
        print(f"Canvas enabled: {is_enabled}")
        await client.set_enabled(True)

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

# Run the async function
asyncio.run(main())

For more details on the async API, see docs/async_usage.md.

Error Handling

The client provides custom exceptions for different types of errors:

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 occurred: {e}")

The same error handling pattern works for the async client too.

📘 API Reference

For detailed information about the available methods and classes, please refer to our API Documentation.

🛠️ Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/hyperb1iss/signalrgb-python.git
   cd signalrgb-python

2. Install uv if you haven't already
3. Install dependencies: uv sync
4. Activate a virtual environment if needed: uv venv .venv && . .venv/bin/activate

To run tests:

pytest

Check out our Development Guide for more information!

👥 Contributing

Have a fix or new feature that you want to add? That's amazing! You're amazing!

1. Fork the repository
2. Create a new branch: git checkout -b feature-branch-name
3. Make your changes and commit them: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature-branch-name
5. Submit a pull request

Please make sure to update tests as appropriate and adhere to the project's coding standards.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

📚 Documentation • 🐛 Report Bug • 💡 Request Feature

🙏 Acknowledgements

This project is not officially associated with SignalRGB. It's an independent client library created by the community for the community. Please do not report issues related to this client to the SignalRGB team.

---

Created by Stefanie Jane 🌠

If you find this project useful, consider buying me a Monster Ultra Violet!! ⚡️