Metadata-Version: 2.4
Name: BeatBoard
Version: 0.1.0.post5
Summary: Dynamic keyboard RGB lighting based on Spotify album art
License-Expression: MIT
Project-URL: Homepage, https://github.com/abdellatif-temsamani/BeatBoard
Project-URL: Repository, https://github.com/abdellatif-temsamani/BeatBoard
Project-URL: Issues, https://github.com/abdellatif-temsamani/BeatBoard/issues
Project-URL: Changelog, https://github.com/abdellatif-temsamani/BeatBoard/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi==2025.10.5
Requires-Dist: charset-normalizer==3.4.4
Requires-Dist: colorthief==0.2.1
Requires-Dist: contourpy==1.3.3
Requires-Dist: cycler==0.12.1
Requires-Dist: fonttools==4.60.1
Requires-Dist: idna==3.11
Requires-Dist: kiwisolver==1.4.9
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: matplotlib==3.10.7
Requires-Dist: mdurl==0.1.2
Requires-Dist: numpy==2.3.4
Requires-Dist: packaging==25.0
Requires-Dist: pillow==12.0.0
Requires-Dist: Pygments==2.19.2
Requires-Dist: pyparsing==3.2.5
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pyusb==1.3.1
Requires-Dist: randomcolor==0.4.4.6
Requires-Dist: requests==2.32.5
Requires-Dist: rich==14.2.0
Requires-Dist: setuptools-scm==8.1.0
Requires-Dist: six==1.17.0
Requires-Dist: urllib3==2.6.1
Provides-Extra: dev
Requires-Dist: pytest==8.3.3; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: ruff==0.14.8; extra == "dev"
Requires-Dist: build==1.3.0; extra == "dev"
Dynamic: license-file

# BeatBoard 🎵💡

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Linux](https://img.shields.io/badge/platform-linux-lightgrey.svg)](https://www.linux.org/)

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

```bash
# 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

```bash
# Test basic functionality
beatboard --help
```

## 🎮 Usage

### Single Color Change

Extract colors from the current song and apply once:

```bash
beatboard
```

### Continuous Mode

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

```bash
beatboard --follow
```

Press `Ctrl+C` to stop following.

### Advanced Options

```bash
# 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)!_

## 🤝 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](.github/CONTRIBUTING.md) 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](SUPPORT.md) for help channels
- Open an [issue](https://github.com/abdellatif-temsamani/BeatBoard/issues)
- Join our discussions

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
for details.

## 🙏 Acknowledgments

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

## 📊 Project Status

![GitHub issues](https://img.shields.io/github/issues/abdellatif-temsamani/BeatBoard)
![GitHub pull requests](https://img.shields.io/github/issues-pr/abdellatif-temsamani/BeatBoard)

---

**Made with ❤️ by the BeatBoard team**
