From 858a8e3ac280f10e42bae80b7b93ae7ee424f12f Mon Sep 17 00:00:00 2001 From: "alexei.dolgolyov" Date: Tue, 24 Feb 2026 19:22:34 +0300 Subject: [PATCH] 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 --- README.md | 305 +++++++++++++++++++++++++++++------------------------- 1 file changed, 165 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 76219af..a102965 100644 --- a/README.md +++ b/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 -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