ledgrab/README.md

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

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

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

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:

• 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

Activity Log

The Activity tab is a persistent, queryable audit log of everything LedGrab has done — entity changes, auth events, device connections, and system actions.

• Filter by category (auth, device, entity, capture, system), severity, actor, entity type, date range, or free text
• Live-append of new events as they happen
• Export as CSV or JSON (authentication required)
• Entity crosslinks navigate directly to the relevant card
• Retention settings (Settings → Activity Log): configure max age, max entry count, and toggle recording on/off
• Clear log (Settings → Activity Log, requires authentication) — audited: a system entry records who cleared the log and when

Note: The Activity Log is distinct from the debug Log Viewer (Settings → General → Open Log Viewer). The Log Viewer is an ephemeral real-time tail of the server's Python log stream (WARNING/ERROR lines, resets on disconnect). The Activity Log is a structured, persistent SQLite-backed record of semantic application events.

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)	Camera2 (on-demand, while capture is running)
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	Foreground-app condition (UsageStatsManager)

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:

• 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)

Docker (recommended for servers)

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+.

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.

See 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:

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

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 and 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 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 for a step-by-step guide.

Home Assistant

For Home Assistant integration, see the separate ledgrab-haos-integration repository.

Development

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:

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.

License

MIT — see LICENSE. Free and open source.