Initial commit: WLED Screen Controller with FastAPI server and Home Assistant integration

This is a complete WLED ambient lighting controller that captures screen border pixels and sends them to WLED devices for immersive ambient lighting effects. ## Server Features: - FastAPI-based REST API with 17+ endpoints - Real-time screen capture with multi-monitor support - Advanced LED calibration system with visual GUI - API key authentication with labeled tokens - Per-device brightness control (0-100%) - Configurable FPS (1-60), border width, and color correction - Persistent device storage (JSON-based) - Comprehensive Web UI with dark/light themes - Docker support with docker-compose - Windows monitor name detection via WMI (shows "LG ULTRAWIDE" etc.) ## Web UI Features: - Device management (add, configure, remove WLED devices) - Real-time status monitoring with FPS metrics - Settings modal for device configuration - Visual calibration GUI with edge testing - Brightness slider per device - Display selection with friendly monitor names - Token-based authentication with login/logout - Responsive button layout ## Calibration System: - Support for any LED strip layout (clockwise/counterclockwise) - 4 starting position options (corners) - Per-edge LED count configuration - Visual preview with starting position indicator - Test buttons to light up individual edges - Smart LED ordering based on start position and direction ## Home Assistant Integration: - Custom HACS integration - Switch entities for processing control - Sensor entities for status and FPS - Select entities for display selection - Config flow for easy setup - Auto-discovery of devices from server ## Technical Stack: - Python 3.11+ - FastAPI + uvicorn - mss (screen capture) - httpx (async WLED client) - Pydantic (validation) - WMI (Windows monitor detection) - Structlog (logging) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-06 16:38:27 +03:00
commit d471a40234
57 changed files with 9726 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,194 @@
+# WLED Screen Controller
+
+Ambient lighting controller that synchronizes WLED devices with your screen content for an immersive viewing experience.
+
+## Overview
+
+This project consists of two components:
+
+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
+
+## 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
+
+## 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
+
+## 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 -r requirements.txt
+   ```
+
+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
+docker-compose up -d
+```
+
+## Configuration
+
+Edit `server/config/default_config.yaml`:
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+processing:
+  default_fps: 30
+  border_width: 10
+
+wled:
+  timeout: 5
+  retry_attempts: 3
+```
+
+## API Usage
+
+### Attach a WLED Device
+
+```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
+  }'
+```
+
+### Start Processing
+
+```bash
+curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
+```
+
+### Get Status
+
+```bash
+curl http://localhost:8080/api/v1/devices/{device_id}/state
+```
+
+See [API Documentation](docs/API.md) for complete API reference.
+
+## Calibration
+
+The calibration system maps screen border pixels to LED positions. See [Calibration Guide](docs/CALIBRATION.md) for details.
+
+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}
+  ]
+}
+```
+
+## Home Assistant Integration
+
+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
+
+## Development
+
+### Running Tests
+
+```bash
+cd server
+pytest tests/ -v
+```
+
+### Project Structure
+
+```
+wled-screen-controller/
+├── server/                   # Python FastAPI server
+│   ├── src/wled_controller/ # Main application code
+│   ├── tests/               # Unit and integration tests
+│   ├── config/              # Configuration files
+│   └── requirements.txt     # Python dependencies
+├── 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.
+
+## 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)