# LED Grab

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.

## What It Does

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.

A Home Assistant integration exposes devices as entities for smart home automation.

## Features

### 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, Russian, and Chinese

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

- 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

```bash
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, zh.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` or use environment variables with the `LED_GRAB_` prefix:

```yaml
server:
  host: "0.0.0.0"
  port: 8080
  log_level: "INFO"

auth:
  api_keys:
    dev: "development-key-change-in-production"

storage:
  devices_file: "data/devices.json"
  templates_file: "data/capture_templates.json"

logging:
  format: "json"
  file: "logs/wled_controller.log"
  max_size_mb: 100
```

Environment variable override example: `LED_GRAB_SERVER__PORT=9090`.

## API

The server exposes a REST API (with Swagger docs at `/docs`) covering:

- **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

All endpoints require API key authentication via `X-API-Key` header or `?token=` query parameter.

See [docs/API.md](docs/API.md) for the full reference.

## Calibration

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.

See [docs/CALIBRATION.md](docs/CALIBRATION.md) for a step-by-step guide.

## Home Assistant

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

```bash
cd server

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format and lint
black src/ tests/
ruff check src/ tests/
```

Optional high-performance capture engines (Windows only):

```bash
pip install -e ".[perf]"
```

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgments

- [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