wled-screen-controller-mixed/INSTALLATION.md

Installation Guide

Complete installation guide for LED Grab (WLED Screen Controller) server and Home Assistant integration.

Table of Contents

1. Docker Installation (recommended)
2. Manual Installation
3. First-Time Setup
4. Home Assistant Integration
5. Configuration Reference
6. Troubleshooting

---

Docker Installation

The fastest way to get running. Requires Docker with Compose.

1. Clone and start:

   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   docker compose up -d
   

2. Verify:

   curl http://localhost:8080/health
   # → {"status":"healthy", ...}
   

3. Open the dashboard: http://localhost:8080

4. View logs:

   docker compose logs -f
   

5. Stop / restart:

   docker compose down          # stop
   docker compose up -d         # start again (data is persisted)
   

Docker manual build (without Compose)

cd server
docker build -t ledgrab .

docker run -d \
  --name wled-screen-controller \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/config:/app/config:ro \
  ledgrab

Linux screen capture in Docker

Screen capture from inside a container requires X11 access. Uncomment network_mode: host in docker-compose.yml and ensure the DISPLAY variable is set. Wayland is not currently supported for in-container capture.

---

Manual Installation

Requirements

Dependency	Version	Purpose
Python	3.11+	Backend server
Node.js	18+	Frontend build (esbuild)
pip	latest	Python package installer
npm	latest	Node package manager

Steps

1. Clone the repository:

   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   

2. Build the frontend bundle:

   npm ci
   npm run build
   

   This compiles TypeScript and bundles JS/CSS into src/wled_controller/static/dist/.

3. Create a virtual environment:

   python -m venv venv
   
   # Linux / macOS
   source venv/bin/activate
   
   # Windows (cmd)
   venv\Scripts\activate
   
   # Windows (PowerShell)
   venv\Scripts\Activate.ps1
   

4. Install Python dependencies:

   pip install .
   

   Optional extras:

   pip install ".[camera]"          # Webcam capture via OpenCV
   pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
   pip install ".[notifications]"   # OS notification capture
   pip install ".[dev]"             # pytest, black, ruff (development)
   

5. Set PYTHONPATH and start the server:

   # Linux / macOS
   export PYTHONPATH=$(pwd)/src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   
   # Windows (cmd)
   set PYTHONPATH=%CD%\src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   

6. Verify: open http://localhost:8080 in your browser.

---

First-Time Setup

Change the default API key

The server ships with a development API key (development-key-change-in-production). Change it before exposing the server on your network.

Option A -- edit the config file:

# server/config/default_config.yaml
auth:
  api_keys:
    main: "your-secure-key-here"   # replace the dev key

Option B -- set an environment variable:

export WLED_AUTH__API_KEYS__main="your-secure-key-here"

Generate a random key:

openssl rand -hex 32

Configure CORS for LAN access

By default the server only allows requests from http://localhost:8080. To access the dashboard from another machine on your LAN, add its origin:

# server/config/default_config.yaml
server:
  cors_origins:
    - "http://localhost:8080"
    - "http://192.168.1.100:8080"   # your server's LAN IP

Or via environment variable:

WLED_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'

Discover devices

Open the dashboard and go to the Devices tab. Click Discover to find WLED devices on your network via mDNS. You can also add devices manually by IP address.

---

Home Assistant Integration

Option 1: HACS (recommended)

1. Install HACS if you have not already.
2. Open HACS in Home Assistant.
3. Click the three-dot menu, then Custom repositories.
4. Add URL: https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed
5. Set category to Integration and click Add.
6. Search for "WLED Screen Controller" in HACS and click Download.
7. Restart Home Assistant.
8. Go to Settings > Devices & Services > Add Integration and search for "WLED Screen Controller".
9. Enter your server URL (e.g., http://192.168.1.100:8080) and API key.

Option 2: Manual

Copy the custom_components/wled_screen_controller/ folder from this repository into your Home Assistant config/custom_components/ directory, then restart Home Assistant and add the integration as above.

Automation example

automation:
  - alias: "Start ambient lighting when TV turns on"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "on"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.living_room_tv_processing

  - alias: "Stop ambient lighting when TV turns off"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
        to: "off"
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.living_room_tv_processing

---

Configuration Reference

The server reads configuration from three sources (in order of priority):

1. Environment variables -- prefix WLED_, double underscore as nesting delimiter (e.g., WLED_SERVER__PORT=9090)
2. YAML config file -- server/config/default_config.yaml (or set WLED_CONFIG_PATH to override)
3. Built-in defaults

See server/.env.example for every available variable with descriptions.

Key settings

Variable	Default	Description
WLED_SERVER__PORT	8080	HTTP listen port
WLED_SERVER__LOG_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR
WLED_SERVER__CORS_ORIGINS	["http://localhost:8080"]	Allowed CORS origins (JSON array)
WLED_AUTH__API_KEYS	{"dev":"development-key..."}	API keys (JSON object)
WLED_MQTT__ENABLED	false	Enable MQTT for HA auto-discovery
WLED_MQTT__BROKER_HOST	localhost	MQTT broker address
WLED_DEMO	false	Enable demo mode (sandbox with virtual devices)

---

Troubleshooting

Server will not start

Check Python version:

python --version  # must be 3.11+

Check the frontend bundle exists:

ls server/src/wled_controller/static/dist/app.bundle.js

If missing, run cd server && npm ci && npm run build.

Check logs:

# Docker
docker compose logs -f

# Manual install
tail -f logs/wled_controller.log

Cannot access the dashboard from another machine

1. Verify the server is reachable: curl http://SERVER_IP:8080/health
2. Check your firewall allows inbound traffic on port 8080.
3. Add your server's LAN IP to cors_origins (see Configure CORS above).

Home Assistant integration not appearing

1. Verify HACS installed the component: check that config/custom_components/wled_screen_controller/ exists.
2. Clear your browser cache.
3. Restart Home Assistant.
4. Check logs at Settings > System > Logs and search for wled_screen_controller.

WLED device not responding

1. Confirm the device is powered on and connected to Wi-Fi.
2. Test it directly: curl http://DEVICE_IP/json/info
3. Check that the server and the device are on the same subnet.
4. Try restarting the WLED device.

Low FPS or high latency

1. Lower the target FPS in the stream settings.
2. Reduce border_width to decrease the number of sampled pixels.
3. Check CPU usage on the server (htop or Task Manager).
4. On Windows, install the perf extra for GPU-accelerated capture: pip install ".[perf]"

---

Next Steps

• API Documentation
• Calibration Guide
• Repository Issues