alexei.dolgolyov/wled-screen-controller-mixed
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rework root README to reflect current project state

Browse Source 
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:
Admin
2026-02-24 19:22:34 +03:00
parent e4c4301a7b
commit 858a8e3ac2
1 changed files with 165 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
README.md
View File

@@ -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
2. **Home Assistant Integration** - Controls and monitors the server from Home Assistant OS
A Home Assistant integration exposes devices as entities for smart home automation.
## Features
- 🖥️ **Multi-Monitor Support** - Select which display to capture
- ⚡ **Configurable FPS** - Adjust update rate (1-60 FPS)
- 🎨 **Smart Calibration** - Map screen edges to LED positions
- 🔌 **REST API** - Full control via HTTP endpoints
- 🏠 **Home Assistant Integration** - Native HAOS support with entities
- 🐳 **Docker Support** - Easy deployment with Docker Compose
- 📊 **Real-time Metrics** - Monitor FPS, status, and performance
### Screen Capture
- Multi-monitor support with per-target display selection
- 5 capture engine backends — MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows), Scrcpy (Android via ADB)
- Configurable capture regions, FPS, and border width
- Capture templates for reusable configurations
### 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
### Server
- Python 3.11 or higher
- Windows, Linux, or macOS
- WLED device on the same network
### Home Assistant Integration
- Home Assistant OS 2023.1 or higher
- Running WLED Screen Controller server
- Python 3.11+ (or Docker)
- A supported LED device on the local network or connected via USB
- Windows for GPU-accelerated capture engines and audio capture; Linux/macOS supported via MSS
## Quick Start
### Server Installation
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/wled-screen-controller.git
cd wled-screen-controller/server
```
2. **Install dependencies**
```bash
pip install .
```
3. **Run the server**
```bash
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
```
4. **Access the API**
- API: http://localhost:8080
- Interactive docs: http://localhost:8080/docs
### Docker Installation
```bash
cd server
git clone https://github.com/yourusername/wled-screen-controller.git
cd wled-screen-controller/server
# Option A: Docker (recommended)
docker-compose up -d
# Option B: Python
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
pip install .
export PYTHONPATH=$(pwd)/src # Linux/Mac
# set PYTHONPATH=%CD%\src # Windows
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
```
Open `http://localhost:8080` to access the dashboard. The default API key for development is `development-key-change-in-production`.
See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including Docker manual builds and Home Assistant setup.
## Architecture
```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
Edit `server/config/default_config.yaml`:
Edit `server/config/default_config.yaml` or use environment variables with the `LED_GRAB_` prefix:
```yaml
server:
host: "0.0.0.0"
port: 8080
log_level: "INFO"
processing:
default_fps: 30
border_width: 10
auth:
api_keys:
dev: "development-key-change-in-production"
wled:
timeout: 5
retry_attempts: 3
storage:
devices_file: "data/devices.json"
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
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
}'
```
The server exposes a REST API (with Swagger docs at `/docs`) covering:
### 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
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
```
All endpoints require API key authentication via `X-API-Key` header or `?token=` query parameter.
### Get Status
```bash
curl http://localhost:8080/api/v1/devices/{device_id}/state
```
See [API Documentation](docs/API.md) for complete API reference.
See [docs/API.md](docs/API.md) for the full reference.
## 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:
```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}
]
}
```
See [docs/CALIBRATION.md](docs/CALIBRATION.md) for a step-by-step guide.
## Home Assistant Integration
## Home Assistant
1. Copy `homeassistant/custom_components/wled_screen_controller` to your Home Assistant `custom_components` folder
2. Restart Home Assistant
3. Go to Settings → Integrations → Add Integration
4. Search for "WLED Screen Controller"
5. Enter your server URL
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.
See [INSTALLATION.md](INSTALLATION.md) for detailed setup instructions.
## Development
### Running Tests
```bash
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
MIT License - see [LICENSE](LICENSE) file
## Contributing
Contributions welcome! Please open an issue or pull request.
MIT — see [LICENSE](LICENSE).
## Acknowledgments
- [WLED](https://github.com/Aircoookie/WLED) - Amazing LED control software
- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework
- [mss](https://python-mss.readthedocs.io/) - Fast screen capture library
## 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)
- [WLED](https://github.com/Aircoookie/WLED) — LED control firmware
- [FastAPI](https://fastapi.tiangolo.com/) — Python web framework
- [MSS](https://python-mss.readthedocs.io/) — Cross-platform screen capture