alexei.dolgolyov/ledgrab
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity

docs: actualize README and API reference, embed screenshots

Browse Source 
README: add free & open-source (MIT) framing; add a Platforms table (Windows/Linux/macOS/Docker supported, Android-TV build marked experimental, scrcpy phone-capture retained); expand the LED device list to ~20 protocols; correct storage to SQLite, the auth model, and resource names (Output Targets, Automations); add a prebuilt-download section; remove the Architecture and Acknowledgments sections; embed dashboard, channels, live-preview, and device-picker screenshots.

docs/API.md: full rewrite from the live route modules — all 253 endpoints across 34 modules, grouped by resource with REST + WebSocket tables, accurate auth model and WS handshake, worked examples, and sensitive-endpoint markers. Replaces the stale v0.1.0 stub.

server/CLAUDE.md: storage is now SQLite (BaseSqliteStore / ledgrab.db / LEDGRAB_DATA_DIR / data_migrations.py); fix the auth description (loopback anonymous, LAN rejected with 401 — not all endpoints open); router registration happens in api/__init__.py.
This commit is contained in:
Admin
2026-05-29 14:35:45 +03:00
parent 498854f04d
commit 12b40e6071
7 changed files with 724 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+112 -102
View File
@@ -1,36 +1,58 @@
# 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.
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 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.
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 Home Assistant integration exposes devices as entities for smart home automation.
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
- 6 capture engine backends — MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows), Scrcpy (Android via ADB), Camera/Webcam (OpenCV)
- 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
- Capture templates for reusable configurations
- Reusable capture templates
### LED Device Support
- WLED (HTTP/UDP) with mDNS auto-discovery
- Adalight (serial) — Arduino-compatible LED controllers
- AmbileD (serial)
- DDP (Distributed Display Protocol, UDP)
- OpenRGB — PC peripherals (keyboard, mouse, RAM, fans, LED strips)
- Serial port auto-detection and baud rate configuration
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
- 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, composite layering, audio-to-color mapping
- Color strip sources: audio-reactive, pattern generator, gradients, composite layering, and audio-to-color mapping
- Pattern templates with customizable effects
### Audio Integration
@@ -38,17 +60,20 @@ A Home Assistant integration exposes devices as entities for smart home automati
- 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-reactive color strip sources driven by frequency analysis
- Audio filter / processing pipeline feeding audio-reactive color 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
- 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` — no installation needed on the client side
- 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
@@ -59,32 +84,56 @@ A Home Assistant integration exposes devices as entities for smart home automati
### Home Assistant Integration
- HACS-compatible custom component
- HACS-compatible custom component (separate repository)
- Light, switch, sensor, and number entities per device
- Real-time metrics via data coordinator
- Real-time metrics via a data coordinator
- WebSocket-based live LED preview in HA
## Requirements
## Platforms
- Python 3.11+ (or Docker)
- A supported LED device on the local network or connected via USB
- Windows, Linux, or macOS — all core features work cross-platform
LedGrab runs as a desktop / server application:
### Platform Notes
| 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 |
| ------- | ------- | ------------- |
| Screen capture | DXCam, BetterCam, WGC, MSS | MSS |
| Webcam capture | OpenCV (DirectShow) | OpenCV (V4L2) |
| Audio capture | WASAPI, Sounddevice | Sounddevice (PulseAudio/PipeWire) |
| GPU monitoring | NVIDIA (pynvml) | NVIDIA (pynvml) |
| Android capture | Scrcpy (ADB) | Scrcpy (ADB) |
| GPU monitoring | NVIDIA (nvidia-ml-py) | NVIDIA (nvidia-ml-py) |
| Capture from Android phone | scrcpy (ADB) | scrcpy (ADB) |
| Notification capture | WinRT | dbus (Linux) |
| Monitor names | Friendly names (WMI) | Generic ("Display 0") |
| Profile conditions | Process/window detection | Not yet implemented |
| 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
### Docker (recommended)
### 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
@@ -115,11 +164,11 @@ export PYTHONPATH=$(pwd)/src # Linux/Mac
uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
```
Open **http://localhost:8080** to access the dashboard.
Open <http://localhost:8080> to access the dashboard.
> **Important:** The default API key is `development-key-change-in-production`. Change it before exposing the server outside localhost. See [INSTALLATION.md](INSTALLATION.md) for details.
> **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 Home Assistant setup.
See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and CORS setup.
## Demo Mode
@@ -133,50 +182,9 @@ docker compose run -e LEDGRAB_DEMO=true server
# Python
LEDGRAB_DEMO=true uvicorn ledgrab.main:app --host 0.0.0.0 --port 8081
# Windows (installed app)
set LEDGRAB_DEMO=true
LedGrab.bat
```
Demo mode uses port **8081**, config file `config/demo_config.yaml`, and stores data in `data/demo/` (separate from production data). It can run alongside the main server.
## Architecture
```text
ledgrab/
├── server/ # Python FastAPI backend
│ ├── src/ledgrab/
│ │ ├── 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, Camera backends
│ │ │ ├── devices/ # WLED, Adalight, AmbileD, DDP, OpenRGB clients
│ │ │ ├── audio/ # Audio capture engines
│ │ │ ├── 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
├── docs/
│ ├── API.md # REST API reference
│ └── CALIBRATION.md # LED calibration guide
├── INSTALLATION.md
└── LICENSE # MIT
```
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
@@ -187,14 +195,15 @@ server:
host: "0.0.0.0"
port: 8080
log_level: "INFO"
cors_origins:
- "http://localhost:8080"
auth:
api_keys:
dev: "development-key-change-in-production"
storage:
devices_file: "data/devices.json"
templates_file: "data/capture_templates.json"
# 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"
@@ -202,25 +211,26 @@ logging:
max_size_mb: 100
```
Environment variable override example: `LEDGRAB_SERVER__PORT=9090`.
- 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 Swagger docs at `/docs`) covering:
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** — 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
- **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
All endpoints require API key authentication via `X-API-Key` header or `?token=` query parameter.
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.
@@ -253,16 +263,16 @@ ruff check src/ tests/
Optional extras:
```bash
pip install -e ".[perf]" # High-performance capture engines (Windows)
pip install -e ".[camera]" # Webcam capture via OpenCV
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).
## 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
MIT — see [LICENSE](LICENSE). Free and open source.