wled-screen-controller-mixed/README.md

# WLED Screen Controller

Ambient lighting controller that synchronizes WLED devices with your screen content for an immersive viewing experience.

## Overview

This project consists of two components:

1. **Python Server** - Captures screen border pixels and sends color data to WLED devices via REST API
2. **Home Assistant Integration** - Controls and monitors the server from Home Assistant OS

## Features

- 🖥️ **Multi-Monitor Support** - Select which display to capture
- ⚡ **Configurable FPS** - Adjust update rate (1-60 FPS)
- 🎨 **Smart Calibration** - Map screen edges to LED positions
- 🔌 **REST API** - Full control via HTTP endpoints
- 🏠 **Home Assistant Integration** - Native HAOS support with entities
- 🐳 **Docker Support** - Easy deployment with Docker Compose
- 📊 **Real-time Metrics** - Monitor FPS, status, and performance

## Requirements

### Server
- Python 3.11 or higher
- Windows, Linux, or macOS
- WLED device on the same network

### Home Assistant Integration
- Home Assistant OS 2023.1 or higher
- Running WLED Screen Controller server

## Quick Start

### Server Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the server**
   ```bash
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   ```

4. **Access the API**
   - API: http://localhost:8080
   - Interactive docs: http://localhost:8080/docs

### Docker Installation

```bash
cd server
docker-compose up -d
```

## Configuration

Edit `server/config/default_config.yaml`:

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

processing:
  default_fps: 30
  border_width: 10

wled:
  timeout: 5
  retry_attempts: 3
```

## API Usage

### Attach a WLED Device

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

### Start Processing

```bash
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
```

### Get Status

```bash
curl http://localhost:8080/api/v1/devices/{device_id}/state
```

See [API Documentation](docs/API.md) for complete API reference.

## Calibration

The calibration system maps screen border pixels to LED positions. See [Calibration Guide](docs/CALIBRATION.md) for details.

Example calibration:
```json
{
  "layout": "clockwise",
  "start_position": "bottom_left",
  "segments": [
    {"edge": "bottom", "led_start": 0, "led_count": 40},
    {"edge": "right", "led_start": 40, "led_count": 30},
    {"edge": "top", "led_start": 70, "led_count": 40},
    {"edge": "left", "led_start": 110, "led_count": 40}
  ]
}
```

## Home Assistant Integration

1. Copy `homeassistant/custom_components/wled_screen_controller` to your Home Assistant `custom_components` folder
2. Restart Home Assistant
3. Go to Settings → Integrations → Add Integration
4. Search for "WLED Screen Controller"
5. Enter your server URL

## Development

### Running Tests

```bash
cd server
pytest tests/ -v
```

### Project Structure

```
wled-screen-controller/
├── server/                   # Python FastAPI server
│   ├── src/wled_controller/ # Main application code
│   ├── tests/               # Unit and integration tests
│   ├── config/              # Configuration files
│   └── requirements.txt     # Python dependencies
├── homeassistant/           # Home Assistant integration
│   └── custom_components/
└── docs/                    # Documentation
```

## Troubleshooting

### Screen capture fails
- **Windows**: Ensure Python has screen capture permissions
- **Linux**: Install X11 dependencies: `apt-get install libxcb1 libxcb-randr0`
- **macOS**: Grant screen recording permission in System Preferences

### WLED not responding
- Verify WLED device is on the same network
- Check firewall settings
- Test connection: `curl http://YOUR_WLED_IP/json/info`

### Low FPS
- Reduce `border_width` in configuration
- Lower target FPS
- Check network latency to WLED device
- Reduce LED count

## License

MIT License - see [LICENSE](LICENSE) file

## Contributing

Contributions welcome! Please open an issue or pull request.

## Acknowledgments

- [WLED](https://github.com/Aircoookie/WLED) - Amazing LED control software
- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework
- [mss](https://python-mss.readthedocs.io/) - Fast screen capture library

## Support

- GitHub Issues: [Report a bug](https://github.com/yourusername/wled-screen-controller/issues)
- Discussions: [Ask a question](https://github.com/yourusername/wled-screen-controller/discussions)