# LED Grab

Ambient lighting system that captures screen content and drives LED strips and smart lights in real time. Supports a wide range of devices — WLED, DDP, Adalight, smart bulbs, PC peripherals, Bluetooth strips, and more — with audio-reactive effects, pattern generation, and condition-based automation.

**Free and open source.** LedGrab is released under the [MIT license](LICENSE) — free to use, modify, and self-host, with no accounts, telemetry, or cloud dependency. Everything runs locally on your own machine and network.

## What It Does

The server captures pixels from a screen (or from a connected Android phone via ADB), extracts border colors, applies a post-processing filter pipeline, and streams the result to your LED devices at up to 60 fps. A built-in web dashboard provides device management, calibration, a visual wiring editor, live LED preview, and real-time metrics — no external UI required.

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

## Screenshots

![LedGrab dashboard](docs/screenshots/dashboard.PNG)

*Dashboard — live system performance, integrations, automations, and scene presets at a glance.*

![Channels view](docs/screenshots/dashboard-targets.PNG)

*Channels — start, stop, and monitor each source-to-device pipeline with live FPS.*

![Live capture preview](docs/screenshots/test-preview-capture.PNG)

*Live preview — inspect the processed capture output in real time before it reaches the LEDs.*

## Features

### Screen Capture

- Multi-monitor support with per-target display selection
- Capture engine backends: MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows only), and Camera/Webcam (OpenCV)
- Capture from a connected Android phone's screen via scrcpy (ADB) — the device is a *source*; LedGrab itself runs on your desktop
- Configurable capture regions, FPS, and border width
- Reusable capture templates

### LED Device Support

LedGrab speaks many protocols, so a single setup can drive everything from a DIY strip to off-the-shelf smart bulbs:

![Device type picker](docs/screenshots/devices.PNG)

- **Network LED controllers** — WLED (HTTP/UDP, with mDNS auto-discovery), DDP (Pixelblaze, ESPixelStick, Falcon), Open Pixel Control (OPC), Art-Net / sACN (E1.31), ESP-NOW, and generic WebSocket streaming
- **Serial / direct hardware** — Adalight (Arduino-compatible), AmbiLED, SPI-attached strips (e.g. WS2812B), and USB HID controllers
- **Smart bulbs & panels** — Philips Hue (Entertainment API), Nanoleaf, Yeelight, WiZ, LIFX, and Govee (Wi-Fi LAN)
- **Bluetooth LE strips** — SP110E, Triones / HappyLighting, Zengge, and Govee BLE
- **PC peripherals** — OpenRGB, Razer Chroma, and SteelSeries GameSense (keyboards, mice, RAM, fans, etc.)
- **Device groups** — combine multiple devices into one logical target
- 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, and more
- Reusable post-processing templates
- Color strip sources: audio-reactive, pattern generator, gradients, composite layering, and audio-to-color mapping
- Pattern templates with customizable effects

### Audio Integration

- Multichannel audio capture from any system device (input or loopback)
- WASAPI engine on Windows, Sounddevice (PortAudio) engine on Linux/macOS
- Per-channel mono extraction
- Audio filter / processing pipeline feeding audio-reactive color sources driven by frequency analysis

### Automation

- Automations engine with condition-based rules — switch targets, scenes, or brightness by time of day, active window/process, MQTT, webhooks, or game events
- Scene presets for one-click lighting changes
- Dynamic value sources for brightness and other parameters (schedule-based, weather-based, scene-aware)
- Weather sources, clock sync, webhooks, and inbound/outbound HTTP endpoints
- Game integration adapters (e.g. League of Legends)

### Dashboard

- Web UI at `http://localhost:8080` — nothing to install on the client side
- Visual node-graph editor for wiring sources → processing → targets
- Progressive Web App (PWA) — installable on phones and tablets with offline caching
- Responsive mobile layout with bottom tab navigation
- 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 (separate repository)
- Light, switch, sensor, and number entities per device
- Real-time metrics via a data coordinator
- WebSocket-based live LED preview in HA

## Platforms

LedGrab runs as a desktop / server application:

| Platform | Status | Notes |
| -------- | ------ | ----- |
| Windows | ✅ Supported | Installer (`.exe`) and portable ZIP; all capture/audio backends |
| Linux | ✅ Supported | Tarball and Docker image; X11 capture (Wayland in-container capture not supported) |
| macOS | ✅ Supported | Runs from source / Docker; MSS capture |
| Docker | ✅ Supported | Multi-arch container image |
| Android (TV) | ⚠️ Experimental | An on-device Android-TV build exists (APK attached to releases) but is emulator-verified only and **not officially supported** |

> **There is no production Android app.** Android phones are only supported as a *capture source* (via scrcpy/ADB) from a desktop host. The on-device Android-TV build is experimental.

### Feature support by OS

| Feature | Windows | Linux / macOS | Android TV (experimental) |
| ------- | ------- | ------------- | ------------------------- |
| Screen capture | DXCam, BetterCam, WGC, MSS | MSS | MediaProjection; root `screenrecord` (rooted devices) |
| Webcam capture | OpenCV (DirectShow) | OpenCV (V4L2) | — (no OpenCV wheel) |
| Audio capture | WASAPI, Sounddevice | Sounddevice (PulseAudio/PipeWire) | AudioPlaybackCapture (API 29+) |
| GPU monitoring | NVIDIA (nvidia-ml-py) | NVIDIA (nvidia-ml-py) | — (CPU/RAM/battery/thermal via `/proc`) |
| Capture from Android phone | scrcpy (ADB) | scrcpy (ADB) | — (captures its own screen instead) |
| Notification capture | WinRT | dbus (Linux) | NotificationListenerService |
| Monitor names | Friendly names (WMI) | Generic ("Display 0") | Single built-in display |
| LED transports | Network, USB-serial, BLE | Network, USB-serial, BLE | Network, USB-serial (Android driver), BLE (Android bridge) |
| Automation: window/process conditions | Supported | Partial | — |

## Requirements

- Python 3.11+ (or Docker)
- A supported LED device on the local network, connected via USB/serial, or reachable over Bluetooth
- Windows, Linux, or macOS

## Quick Start

### Prebuilt downloads

Grab a ready-to-run build from the [Releases page](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/releases):

- **Windows** — `LedGrab-<version>-setup.exe` (installer, no admin required) or `LedGrab-<version>-win-x64.zip` (portable)
- **Linux** — `LedGrab-<version>-linux-x64.tar.gz`
- **Docker** — see below
- **Android TV** — `.apk` (experimental, see [Platforms](#platforms))

### Docker (recommended for servers)

```bash
git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
cd ledgrab/server
docker compose up -d
```

### Manual

Requires Python 3.11+ and Node.js 18+.

```bash
git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
cd ledgrab/server

# Build the frontend bundle
npm ci && npm run build

# Create a virtual environment and install
python -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows
pip install .

# Start the server
export PYTHONPATH=$(pwd)/src    # Linux/Mac
# set PYTHONPATH=%CD%\src       # Windows
uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
```

Open <http://localhost:8080> to access the dashboard.

> **Network access:** By default, LedGrab allows anonymous access only from `localhost`. Any request from another machine on your LAN is rejected unless you configure an API key (`auth.api_keys`). Set a key before exposing the server on your network — see [INSTALLATION.md](INSTALLATION.md).

See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and CORS setup.

## Demo Mode

Demo mode runs the server with virtual devices, sample data, and isolated storage — useful for exploring the UI without real hardware.

Set the `LEDGRAB_DEMO` environment variable to `true`, `1`, or `yes`:

```bash
# Docker
docker compose run -e LEDGRAB_DEMO=true server

# Python
LEDGRAB_DEMO=true uvicorn ledgrab.main:app --host 0.0.0.0 --port 8081
```

Demo mode uses port **8081**, config file `config/demo_config.yaml`, and stores data under `data/demo/` (separate from production data). It can run alongside the main server.

## Configuration

Edit `server/config/default_config.yaml` or use environment variables with the `LEDGRAB_` prefix:

```yaml
server:
  host: "0.0.0.0"
  port: 8080
  log_level: "INFO"
  cors_origins:
    - "http://localhost:8080"

auth:
  # Empty (default) → loopback-only anonymous access; LAN requests are rejected.
  # Add a key to enable LAN/remote access (generate one with: openssl rand -hex 32).
  api_keys: {}
  # api_keys:
  #   dev: "your-secret-key-here"

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

- Application data is stored in a SQLite database (`data/ledgrab.db` by default). Set `LEDGRAB_DATA_DIR` to relocate the data root (database + assets).
- Environment variable override example: `LEDGRAB_SERVER__PORT=9090`.

See [INSTALLATION.md](INSTALLATION.md) and [`server/.env.example`](server/.env.example) for the full configuration reference.

## API

The server exposes a REST API (with interactive Swagger docs at `/docs`) plus WebSocket endpoints. Resources include:

- **Devices** — CRUD, discovery, validation, state, metrics
- **Capture Templates** & **Picture Sources** — screen capture configuration and stream definitions
- **Output Targets** — LED target management, start/stop processing, live color stream
- **Post-Processing Templates** — filter pipeline configurations
- **Color Strip Sources**, **Pattern Templates**, **Gradients** — color generation
- **Audio Sources / Templates / Filters** — audio capture and reactive processing
- **Value Sources**, **Weather Sources**, **Scene Presets** — dynamic parameters and presets
- **Automations**, **Webhooks**, **HTTP Endpoints**, **Game Integration** — triggers and rules
- **MQTT** & **Home Assistant** — broker sources and HA integration

Authentication uses a Bearer token (`Authorization: Bearer <api-key>`) when API keys are configured; loopback requests are anonymous by default. WebSocket connections authenticate via a first-message handshake.

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

For Home Assistant integration, see the separate [ledgrab-haos-integration](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration) repository.

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

```bash
pip install -e ".[perf]"            # High-performance capture engines (Windows: DXCam, BetterCam, WGC)
pip install -e ".[notifications]"   # OS notification capture (WinRT / dbus)
pip install -e ".[scrcpy]"          # Capture from an Android phone via scrcpy
pip install -e ".[ble]"             # Bluetooth LE LED controllers (desktop only)
```

## Contributing

Contributions are welcome. LedGrab is MIT-licensed, so you're free to fork, modify, and self-host. Please open an issue or pull request on the [repository](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab).

## License

MIT — see [LICENSE](LICENSE). Free and open source.