alexei.dolgolyov
1c1bbe2551
Make the existing Application automation rule (foreground app -> activate scene) work on the Android-TV build. A Kotlin ForegroundAppBridge reads the foreground app via UsageStatsManager and lists launchable apps via LauncherApps; PlatformDetector bridges it in (ahead of the Windows-only ctypes guard) so the existing AutomationEngine / ApplicationRule / storage / deactivation modes are unchanged. New /system/installed-apps + /system/info endpoints feed an app picker that stores package names (vs process names on desktop); on Android the editor hides the match-type selector since the foreground app is the only obtainable signal. PACKAGE_USAGE_STATS is granted via an on-device button + a web-UI banner (no blanket prompt at capture start); detection degrades gracefully until granted. Zero new Python/Gradle deps (UsageStatsManager + LauncherApps are in-platform; matching only string-compares the package name, so no QUERY_ALL_PACKAGES). assembleDebug + 1897 pytest + ruff + tsc + npm build all green; independent final review (0 blockers) + security review (no critical issues).
280 lines
12 KiB
Markdown
280 lines
12 KiB
Markdown
# 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
|
|
|
|
|
|
|
|
*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
|
|
|
|
### 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](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.
|