Metadata-Version: 2.4
Name: ledgrab
Version: 0.4.1
Summary: Ambient lighting system that captures screen content and drives LED strips in real time
Author-email: Alexei Dolgolyov <dolgolyov.alexei@gmail.com>
License: MIT
Project-URL: Homepage, https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab
Project-URL: Repository, https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab
Project-URL: Documentation, https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/src/branch/master/INSTALLATION.md
Project-URL: Issues, https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/issues
Keywords: wled,ambient-lighting,screen-capture,home-automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: mss>=9.0.2
Requires-Dist: numpy>=2.1.3
Requires-Dist: pydantic>=2.9.2
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: structlog>=24.4.0
Requires-Dist: python-json-logger>=3.1.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: jinja2>=3.1.0
Requires-Dist: zeroconf>=0.131.0
Requires-Dist: pyserial>=3.5
Requires-Dist: psutil>=5.9.0
Requires-Dist: nvidia-ml-py>=12.0.0
Requires-Dist: PyAudioWPatch>=0.2.12; sys_platform == "win32"
Requires-Dist: sounddevice>=0.5
Requires-Dist: aiomqtt>=2.0.0
Requires-Dist: openrgb-python>=0.2.15
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: websockets>=13.0
Requires-Dist: just-playback>=0.1.7
Requires-Dist: pystray>=0.19.0; sys_platform == "win32"
Requires-Dist: Pillow>=10.4.0; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=8.3.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: respx>=0.21.1; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "dev"
Requires-Dist: Pillow>=10.4.0; extra == "dev"
Provides-Extra: camera
Provides-Extra: scrcpy
Requires-Dist: scrcpy-client>=0.5.0; extra == "scrcpy"
Provides-Extra: notifications
Requires-Dist: winrt-Windows.UI.Notifications>=3.0.0; sys_platform == "win32" and extra == "notifications"
Requires-Dist: winrt-Windows.UI.Notifications.Management>=3.0.0; sys_platform == "win32" and extra == "notifications"
Requires-Dist: winrt-Windows.Foundation>=3.0.0; sys_platform == "win32" and extra == "notifications"
Requires-Dist: winrt-Windows.Foundation.Collections>=3.0.0; sys_platform == "win32" and extra == "notifications"
Requires-Dist: winrt-Windows.ApplicationModel>=3.0.0; sys_platform == "win32" and extra == "notifications"
Requires-Dist: dbus-next>=0.2.3; sys_platform == "linux" and extra == "notifications"
Provides-Extra: perf
Requires-Dist: dxcam>=0.0.5; sys_platform == "win32" and extra == "perf"
Requires-Dist: bettercam>=1.0.0; sys_platform == "win32" and extra == "perf"
Requires-Dist: windows-capture>=1.5.0; sys_platform == "win32" and extra == "perf"
Provides-Extra: ble
Requires-Dist: bleak>=0.22; extra == "ble"

# LedGrab - Server

High-performance FastAPI server that captures screen content and controls WLED devices for ambient lighting.

## Overview

The server component provides:
- 🎯 **Real-time Screen Capture** - Multi-monitor support with configurable FPS
- 🎨 **Advanced Processing** - Border pixel extraction with color correction
- 🔧 **Flexible Calibration** - Map screen edges to any LED layout
- 🌐 **REST API** - Complete control via 25+ REST endpoints
- 💾 **Persistent Storage** - JSON-based device and configuration management
- 📊 **Metrics & Monitoring** - Real-time FPS, status, and performance data

## Quick Start

### Option 1: Docker (Recommended)

```bash
# Start server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop server
docker-compose down
```

Server runs on: **http://localhost:8080**

### Option 2: Python

```bash
# Create virtual environment
python -m venv venv

# Activate
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate      # Windows

# Install dependencies
pip install .

# Set PYTHONPATH
export PYTHONPATH=$(pwd)/src  # Linux/Mac
set PYTHONPATH=%CD%\src       # Windows

# Run server
uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
```

## Installation

### Requirements
- **Python 3.11+** (for Python installation)
- **Docker & Docker Compose** (for Docker installation)
- **WLED device** on your network

See [../INSTALLATION.md](../INSTALLATION.md) for comprehensive installation guide.

## Configuration

### Configuration File

Edit `config/default_config.yaml`:

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

processing:
  default_fps: 30        # Target frames per second
  max_fps: 60           # Maximum allowed FPS
  border_width: 10      # Pixels to sample from edge

wled:
  timeout: 5            # Connection timeout (seconds)
  retry_attempts: 3     # Number of retries

storage:
  devices_file: "data/devices.json"

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

### Environment Variables

```bash
# Server configuration
export LEDGRAB_SERVER__HOST="0.0.0.0"
export LEDGRAB_SERVER__PORT=8080
export LEDGRAB_SERVER__LOG_LEVEL="INFO"

# Processing configuration
export LEDGRAB_PROCESSING__DEFAULT_FPS=30
export LEDGRAB_PROCESSING__BORDER_WIDTH=10

# WLED configuration
export WLED_WLED__TIMEOUT=5
```

## Usage

### WLED Device Setup

**Important**: Configure your WLED device using the official WLED web interface before connecting it to this controller:

1. **Access WLED Interface**: Open `http://[wled-ip]` in your browser
2. **Configure Device Settings**:
   - Set LED count and type
   - Configure brightness, color order, and power limits
   - Set up segments if needed
   - Configure effects and presets

**This controller only sends pixel color data** - it does not manage WLED settings like brightness, effects, or segments. All WLED device configuration should be done through the official WLED interface.

### API Documentation

- **Web UI**: http://localhost:8080 (recommended for device management)
- **Swagger UI**: http://localhost:8080/docs
- **ReDoc**: http://localhost:8080/redoc

### Quick Example

```bash
# 1. Add device
curl -X POST http://localhost:8080/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{"name":"Living Room","url":"http://192.168.1.100","led_count":150}'

# 2. Start processing
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start

# 3. Check status
curl http://localhost:8080/api/v1/devices/{device_id}/state
```

## Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=ledgrab --cov-report=html

# Run specific test
pytest tests/test_screen_capture.py -v
```

## Development

### Project Structure

```
src/ledgrab/
├── main.py              # FastAPI application
├── config.py            # Configuration
├── api/                 # API routes
├── core/                # Core functionality
│   ├── screen_capture.py
│   ├── wled_client.py
│   ├── calibration.py
│   └── processor_manager.py
├── storage/             # Data persistence
└── utils/               # Utilities
```

### Code Quality

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/
```

## License

MIT - see [../LICENSE](../LICENSE)

## Support

- 📖 [Full Documentation](../docs/)
- 🐛 [Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/issues)
