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

   git clone https://github.com/yourusername/wled-screen-controller.git
   cd wled-screen-controller/server
   

2. Install dependencies

   pip install .
   

3. Run the server

   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

cd server
docker-compose up -d

Configuration

Edit server/config/default_config.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

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

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

Get Status

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

See API Documentation for complete API reference.

Calibration

The calibration system maps screen border pixels to LED positions. See Calibration Guide for details.

Example calibration:

{
  "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

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
│   └── pyproject.toml       # Python dependencies & project config
├── 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 file

Contributing

Contributions welcome! Please open an issue or pull request.

Acknowledgments

• WLED - Amazing LED control software
• FastAPI - Modern Python web framework
• mss - Fast screen capture library

Support

• GitHub Issues: Report a bug
• Discussions: Ask a question