Rework root README to reflect current project state
Rewritten from scratch as "LED Grab" with organized feature sections, full architecture tree, actual config examples, and comprehensive API listing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
289
README.md
289
README.md
@@ -1,194 +1,219 @@
|
|||||||
# WLED Screen Controller
|
# LED Grab
|
||||||
|
|
||||||
Ambient lighting controller that synchronizes WLED devices with your screen content for an immersive viewing experience.
|
Ambient lighting system that captures screen content and drives LED strips in real time. Supports WLED, Adalight, AmbileD, and DDP devices with audio-reactive effects, pattern generation, and automated profile switching.
|
||||||
|
|
||||||
## Overview
|
## What It Does
|
||||||
|
|
||||||
This project consists of two components:
|
The server captures pixels from a screen (or Android device via ADB), extracts border colors, applies post-processing filters, and streams the result to LED strips at up to 60 fps. A built-in web dashboard provides device management, calibration, live LED preview, and real-time metrics — no external UI required.
|
||||||
|
|
||||||
1. **Python Server** - Captures screen border pixels and sends color data to WLED devices via REST API
|
A Home Assistant integration exposes devices as entities for smart home automation.
|
||||||
2. **Home Assistant Integration** - Controls and monitors the server from Home Assistant OS
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- 🖥️ **Multi-Monitor Support** - Select which display to capture
|
### Screen Capture
|
||||||
- ⚡ **Configurable FPS** - Adjust update rate (1-60 FPS)
|
|
||||||
- 🎨 **Smart Calibration** - Map screen edges to LED positions
|
- Multi-monitor support with per-target display selection
|
||||||
- 🔌 **REST API** - Full control via HTTP endpoints
|
- 5 capture engine backends — MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows), Scrcpy (Android via ADB)
|
||||||
- 🏠 **Home Assistant Integration** - Native HAOS support with entities
|
- Configurable capture regions, FPS, and border width
|
||||||
- 🐳 **Docker Support** - Easy deployment with Docker Compose
|
- Capture templates for reusable configurations
|
||||||
- 📊 **Real-time Metrics** - Monitor FPS, status, and performance
|
|
||||||
|
### LED Device Support
|
||||||
|
|
||||||
|
- WLED (HTTP/UDP) with mDNS auto-discovery
|
||||||
|
- Adalight (serial) — Arduino-compatible LED controllers
|
||||||
|
- AmbileD (serial)
|
||||||
|
- DDP (Distributed Display Protocol, UDP)
|
||||||
|
- Serial port auto-detection and baud rate configuration
|
||||||
|
|
||||||
|
### Color Processing
|
||||||
|
|
||||||
|
- Post-processing filter pipeline: brightness, gamma, saturation, color correction, auto-crop, frame interpolation, pixelation, flip
|
||||||
|
- Reusable post-processing templates
|
||||||
|
- Color strip sources: audio-reactive, pattern generator, composite layering, audio-to-color mapping
|
||||||
|
- Pattern templates with customizable effects
|
||||||
|
|
||||||
|
### Audio Integration (Windows)
|
||||||
|
|
||||||
|
- Multichannel audio capture from any system device (input or loopback)
|
||||||
|
- Per-channel mono extraction
|
||||||
|
- Audio-reactive color strip sources driven by frequency analysis
|
||||||
|
|
||||||
|
### Automation
|
||||||
|
|
||||||
|
- Profile engine with condition-based switching (time of day, active window, etc.)
|
||||||
|
- Dynamic brightness value sources (schedule-based, scene-aware)
|
||||||
|
- Key Colors (KC) targets with live WebSocket color streaming
|
||||||
|
|
||||||
|
### Dashboard
|
||||||
|
|
||||||
|
- Web UI at `http://localhost:8080` — no installation needed on the client side
|
||||||
|
- Device management with auto-discovery wizard
|
||||||
|
- Visual calibration editor with overlay preview
|
||||||
|
- Live LED strip preview via WebSocket
|
||||||
|
- Real-time FPS, latency, and uptime charts
|
||||||
|
- Localized in English and Russian
|
||||||
|
|
||||||
|
### Home Assistant Integration
|
||||||
|
|
||||||
|
- HACS-compatible custom component
|
||||||
|
- Light, switch, sensor, and number entities per device
|
||||||
|
- Real-time metrics via data coordinator
|
||||||
|
- WebSocket-based live LED preview in HA
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
### Server
|
- Python 3.11+ (or Docker)
|
||||||
- Python 3.11 or higher
|
- A supported LED device on the local network or connected via USB
|
||||||
- Windows, Linux, or macOS
|
- Windows for GPU-accelerated capture engines and audio capture; Linux/macOS supported via MSS
|
||||||
- WLED device on the same network
|
|
||||||
|
|
||||||
### Home Assistant Integration
|
|
||||||
- Home Assistant OS 2023.1 or higher
|
|
||||||
- Running WLED Screen Controller server
|
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Server Installation
|
|
||||||
|
|
||||||
1. **Clone the repository**
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/yourusername/wled-screen-controller.git
|
git clone https://github.com/yourusername/wled-screen-controller.git
|
||||||
cd wled-screen-controller/server
|
cd wled-screen-controller/server
|
||||||
```
|
|
||||||
|
|
||||||
2. **Install dependencies**
|
# Option A: Docker (recommended)
|
||||||
```bash
|
docker-compose up -d
|
||||||
|
|
||||||
|
# Option B: Python
|
||||||
|
python -m venv venv
|
||||||
|
source venv/bin/activate # Linux/Mac
|
||||||
|
# venv\Scripts\activate # Windows
|
||||||
pip install .
|
pip install .
|
||||||
```
|
export PYTHONPATH=$(pwd)/src # Linux/Mac
|
||||||
|
# set PYTHONPATH=%CD%\src # Windows
|
||||||
3. **Run the server**
|
|
||||||
```bash
|
|
||||||
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
|
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Access the API**
|
Open `http://localhost:8080` to access the dashboard. The default API key for development is `development-key-change-in-production`.
|
||||||
- API: http://localhost:8080
|
|
||||||
- Interactive docs: http://localhost:8080/docs
|
|
||||||
|
|
||||||
### Docker Installation
|
See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including Docker manual builds and Home Assistant setup.
|
||||||
|
|
||||||
```bash
|
## Architecture
|
||||||
cd server
|
|
||||||
docker-compose up -d
|
```text
|
||||||
|
wled-screen-controller/
|
||||||
|
├── server/ # Python FastAPI backend
|
||||||
|
│ ├── src/wled_controller/
|
||||||
|
│ │ ├── main.py # Application entry point
|
||||||
|
│ │ ├── config.py # YAML + env var configuration
|
||||||
|
│ │ ├── api/
|
||||||
|
│ │ │ ├── routes/ # REST + WebSocket endpoints
|
||||||
|
│ │ │ └── schemas/ # Pydantic request/response models
|
||||||
|
│ │ ├── core/
|
||||||
|
│ │ │ ├── capture/ # Screen capture, calibration, pixel processing
|
||||||
|
│ │ │ ├── capture_engines/ # MSS, DXCam, BetterCam, WGC, Scrcpy backends
|
||||||
|
│ │ │ ├── devices/ # WLED, Adalight, AmbileD, DDP clients
|
||||||
|
│ │ │ ├── audio/ # Audio capture (Windows)
|
||||||
|
│ │ │ ├── filters/ # Post-processing filter pipeline
|
||||||
|
│ │ │ ├── processing/ # Stream orchestration and target processors
|
||||||
|
│ │ │ └── profiles/ # Condition-based profile automation
|
||||||
|
│ │ ├── storage/ # JSON-based persistence layer
|
||||||
|
│ │ ├── static/ # Web dashboard (vanilla JS, CSS, HTML)
|
||||||
|
│ │ │ ├── js/core/ # API client, state, i18n, modals, events
|
||||||
|
│ │ │ ├── js/features/ # Feature modules (devices, streams, targets, etc.)
|
||||||
|
│ │ │ ├── css/ # Stylesheets
|
||||||
|
│ │ │ └── locales/ # en.json, ru.json
|
||||||
|
│ │ └── utils/ # Logging, monitor detection
|
||||||
|
│ ├── config/ # default_config.yaml
|
||||||
|
│ ├── tests/ # pytest suite
|
||||||
|
│ ├── Dockerfile
|
||||||
|
│ └── docker-compose.yml
|
||||||
|
├── custom_components/ # Home Assistant integration (HACS)
|
||||||
|
│ └── wled_screen_controller/
|
||||||
|
├── docs/
|
||||||
|
│ ├── API.md # REST API reference
|
||||||
|
│ └── CALIBRATION.md # LED calibration guide
|
||||||
|
├── INSTALLATION.md
|
||||||
|
└── LICENSE # MIT
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
Edit `server/config/default_config.yaml`:
|
Edit `server/config/default_config.yaml` or use environment variables with the `LED_GRAB_` prefix:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
server:
|
server:
|
||||||
host: "0.0.0.0"
|
host: "0.0.0.0"
|
||||||
port: 8080
|
port: 8080
|
||||||
|
log_level: "INFO"
|
||||||
|
|
||||||
processing:
|
auth:
|
||||||
default_fps: 30
|
api_keys:
|
||||||
border_width: 10
|
dev: "development-key-change-in-production"
|
||||||
|
|
||||||
wled:
|
storage:
|
||||||
timeout: 5
|
devices_file: "data/devices.json"
|
||||||
retry_attempts: 3
|
templates_file: "data/capture_templates.json"
|
||||||
|
|
||||||
|
logging:
|
||||||
|
format: "json"
|
||||||
|
file: "logs/wled_controller.log"
|
||||||
|
max_size_mb: 100
|
||||||
```
|
```
|
||||||
|
|
||||||
## API Usage
|
Environment variable override example: `LED_GRAB_SERVER__PORT=9090`.
|
||||||
|
|
||||||
### Attach a WLED Device
|
## API
|
||||||
|
|
||||||
```bash
|
The server exposes a REST API (with Swagger docs at `/docs`) covering:
|
||||||
curl -X POST http://localhost:8080/api/v1/devices \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"name": "Living Room TV",
|
|
||||||
"url": "http://192.168.1.100",
|
|
||||||
"led_count": 150
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Start Processing
|
- **Devices** — CRUD, discovery, validation, state, metrics
|
||||||
|
- **Capture Templates** — Screen capture configurations
|
||||||
|
- **Picture Sources** — Screen capture stream definitions
|
||||||
|
- **Picture Targets** — LED target management, start/stop processing
|
||||||
|
- **Post-Processing Templates** — Filter pipeline configurations
|
||||||
|
- **Color Strip Sources** — Audio, pattern, composite, mapped sources
|
||||||
|
- **Audio Sources** — Multichannel and mono audio device configuration
|
||||||
|
- **Pattern Templates** — Effect pattern definitions
|
||||||
|
- **Value Sources** — Dynamic brightness/value providers
|
||||||
|
- **Key Colors Targets** — KC targets with WebSocket live color stream
|
||||||
|
- **Profiles** — Condition-based automation profiles
|
||||||
|
|
||||||
```bash
|
All endpoints require API key authentication via `X-API-Key` header or `?token=` query parameter.
|
||||||
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
|
|
||||||
```
|
|
||||||
|
|
||||||
### Get Status
|
See [docs/API.md](docs/API.md) for the full reference.
|
||||||
|
|
||||||
```bash
|
|
||||||
curl http://localhost:8080/api/v1/devices/{device_id}/state
|
|
||||||
```
|
|
||||||
|
|
||||||
See [API Documentation](docs/API.md) for complete API reference.
|
|
||||||
|
|
||||||
## Calibration
|
## Calibration
|
||||||
|
|
||||||
The calibration system maps screen border pixels to LED positions. See [Calibration Guide](docs/CALIBRATION.md) for details.
|
The calibration system maps screen border pixels to physical LED positions. Configure layout direction, start position, and per-edge segments through the web dashboard or API.
|
||||||
|
|
||||||
Example calibration:
|
See [docs/CALIBRATION.md](docs/CALIBRATION.md) for a step-by-step guide.
|
||||||
```json
|
|
||||||
{
|
|
||||||
"layout": "clockwise",
|
|
||||||
"start_position": "bottom_left",
|
|
||||||
"segments": [
|
|
||||||
{"edge": "bottom", "led_start": 0, "led_count": 40},
|
|
||||||
{"edge": "right", "led_start": 40, "led_count": 30},
|
|
||||||
{"edge": "top", "led_start": 70, "led_count": 40},
|
|
||||||
{"edge": "left", "led_start": 110, "led_count": 40}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Home Assistant Integration
|
## Home Assistant
|
||||||
|
|
||||||
1. Copy `homeassistant/custom_components/wled_screen_controller` to your Home Assistant `custom_components` folder
|
Install via HACS (add as a custom repository) or manually copy `custom_components/wled_screen_controller/` into your HA config directory. The integration creates light, switch, sensor, and number entities for each configured device.
|
||||||
2. Restart Home Assistant
|
|
||||||
3. Go to Settings → Integrations → Add Integration
|
See [INSTALLATION.md](INSTALLATION.md) for detailed setup instructions.
|
||||||
4. Search for "WLED Screen Controller"
|
|
||||||
5. Enter your server URL
|
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
### Running Tests
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd server
|
cd server
|
||||||
pytest tests/ -v
|
|
||||||
|
# Install with dev dependencies
|
||||||
|
pip install -e ".[dev]"
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
pytest
|
||||||
|
|
||||||
|
# Format and lint
|
||||||
|
black src/ tests/
|
||||||
|
ruff check src/ tests/
|
||||||
```
|
```
|
||||||
|
|
||||||
### Project Structure
|
Optional high-performance capture engines (Windows only):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -e ".[perf]"
|
||||||
```
|
```
|
||||||
wled-screen-controller/
|
|
||||||
├── server/ # Python FastAPI server
|
|
||||||
│ ├── src/wled_controller/ # Main application code
|
|
||||||
│ ├── tests/ # Unit and integration tests
|
|
||||||
│ ├── config/ # Configuration files
|
|
||||||
│ └── pyproject.toml # Python dependencies & project config
|
|
||||||
├── homeassistant/ # Home Assistant integration
|
|
||||||
│ └── custom_components/
|
|
||||||
└── docs/ # Documentation
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Screen capture fails
|
|
||||||
- **Windows**: Ensure Python has screen capture permissions
|
|
||||||
- **Linux**: Install X11 dependencies: `apt-get install libxcb1 libxcb-randr0`
|
|
||||||
- **macOS**: Grant screen recording permission in System Preferences
|
|
||||||
|
|
||||||
### WLED not responding
|
|
||||||
- Verify WLED device is on the same network
|
|
||||||
- Check firewall settings
|
|
||||||
- Test connection: `curl http://YOUR_WLED_IP/json/info`
|
|
||||||
|
|
||||||
### Low FPS
|
|
||||||
- Reduce `border_width` in configuration
|
|
||||||
- Lower target FPS
|
|
||||||
- Check network latency to WLED device
|
|
||||||
- Reduce LED count
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License - see [LICENSE](LICENSE) file
|
MIT — see [LICENSE](LICENSE).
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
Contributions welcome! Please open an issue or pull request.
|
|
||||||
|
|
||||||
## Acknowledgments
|
## Acknowledgments
|
||||||
|
|
||||||
- [WLED](https://github.com/Aircoookie/WLED) - Amazing LED control software
|
- [WLED](https://github.com/Aircoookie/WLED) — LED control firmware
|
||||||
- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework
|
- [FastAPI](https://fastapi.tiangolo.com/) — Python web framework
|
||||||
- [mss](https://python-mss.readthedocs.io/) - Fast screen capture library
|
- [MSS](https://python-mss.readthedocs.io/) — Cross-platform screen capture
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
- GitHub Issues: [Report a bug](https://github.com/yourusername/wled-screen-controller/issues)
|
|
||||||
- Discussions: [Ask a question](https://github.com/yourusername/wled-screen-controller/discussions)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user