BeatBoard 0.1.0.post5

Dynamic keyboard RGB lighting based on Spotify album art

BeatBoard 🎵💡

BeatBoard is a CLI tool for Linux that dynamically changes your keyboard's RGB lighting based on the colors extracted from the album art of the currently playing Spotify Desktop song. It uses playerctl to fetch metadata and applies vibrant colors to create an immersive music experience.

✨ Features

• 🎨 Automatic color extraction from album art of currently playing tracks
• 🌈 Vibrant color analysis to find dominant and complementary colors
• ⌨️ Real-time RGB keyboard control with smooth transitions
• 🔄 Continuous following mode for live color updates as songs change
• 🎵 Spotify Desktop integration through playerctl for seamless music control
• 🎯 Hardware-agnostic design for easy expansion to new devices

📋 Requirements

System Requirements

• Linux operating system (tested on Ubuntu, Fedora, Arch)
• Python 3.11 or higher
• playerctl for media player integration

Media Players

• Spotify Desktop (required)

Supported Hardware

• Logitech G213 Prodigy (single region supported)
• Additional RGB devices (planned support)

🚀 Installation

Quick Install

# Clone with submodules
git clone --recurse-submodules https://github.com/abdellatif-temsamani/BeatBoard
cd BeatBoard

# Set up virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

Verify Installation

# Test basic functionality
beatboard --help

🎮 Usage

Single Color Change

Extract colors from the current song and apply once:

beatboard

Continuous Mode

Follow the playing song and update colors in real-time:

beatboard --follow

Press Ctrl+C to stop following.

Advanced Options

# Specify hardware
beatboard --hardware g213

# Debug mode
beatboard --debug

# Show version
beatboard --version

🖥️ Supported Hardware

Currently Supported

• Logitech G213 Prodigy - single region supported
• Razer keyboards - via razer-cli

Planned Support

• Corsair RGB keyboards
• Generic HID RGB devices

Want to add support for your device? See our Contributing Guide!

🤝 Contributing

We welcome contributions of all kinds! Here's how you can help:

Code Contributions

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Hardware Support

Help us expand hardware compatibility by:

• Adding device drivers
• Testing on new hardware
• Documentation improvements

See our Contributing Guide for detailed guidelines.

🐛 Troubleshooting

Common Issues

• "playerctl not found": Install with sudo apt install playerctl (Ubuntu/Debian)
• "Permission denied": Add user to input group: sudo usermod -a -G input $USER
• "No album art": Ensure current Spotify Desktop song has album art available

Getting Help

• See our Support Guide for help channels
• Open an issue
• Join our discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• The playerctl team for media player integration
• Logitech for the G213 hardware specifications
• Contributors and beta testers

📊 Project Status

---

Made with ❤️ by the BeatBoard team