Initial commit: WLED Screen Controller with FastAPI server and Home Assistant integration

This is a complete WLED ambient lighting controller that captures screen border pixels
and sends them to WLED devices for immersive ambient lighting effects.

## Server Features:
- FastAPI-based REST API with 17+ endpoints
- Real-time screen capture with multi-monitor support
- Advanced LED calibration system with visual GUI
- API key authentication with labeled tokens
- Per-device brightness control (0-100%)
- Configurable FPS (1-60), border width, and color correction
- Persistent device storage (JSON-based)
- Comprehensive Web UI with dark/light themes
- Docker support with docker-compose
- Windows monitor name detection via WMI (shows "LG ULTRAWIDE" etc.)

## Web UI Features:
- Device management (add, configure, remove WLED devices)
- Real-time status monitoring with FPS metrics
- Settings modal for device configuration
- Visual calibration GUI with edge testing
- Brightness slider per device
- Display selection with friendly monitor names
- Token-based authentication with login/logout
- Responsive button layout

## Calibration System:
- Support for any LED strip layout (clockwise/counterclockwise)
- 4 starting position options (corners)
- Per-edge LED count configuration
- Visual preview with starting position indicator
- Test buttons to light up individual edges
- Smart LED ordering based on start position and direction

## Home Assistant Integration:
- Custom HACS integration
- Switch entities for processing control
- Sensor entities for status and FPS
- Select entities for display selection
- Config flow for easy setup
- Auto-discovery of devices from server

## Technical Stack:
- Python 3.11+
- FastAPI + uvicorn
- mss (screen capture)
- httpx (async WLED client)
- Pydantic (validation)
- WMI (Windows monitor detection)
- Structlog (logging)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

server/src/wled_controller/api/schemas.py

@@ -0,0 +1,175 @@
+"""Pydantic schemas for API request and response models."""
+
+from datetime import datetime
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+# Health and Version Schemas
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: Literal["healthy", "unhealthy"] = Field(description="Service health status")
+    timestamp: datetime = Field(description="Current server time")
+    version: str = Field(description="Application version")
+
+
+class VersionResponse(BaseModel):
+    """Version information response."""
+
+    version: str = Field(description="Application version")
+    python_version: str = Field(description="Python version")
+    api_version: str = Field(description="API version")
+
+
+# Display Schemas
+
+class DisplayInfo(BaseModel):
+    """Display/monitor information."""
+
+    index: int = Field(description="Display index")
+    name: str = Field(description="Display name")
+    width: int = Field(description="Display width in pixels")
+    height: int = Field(description="Display height in pixels")
+    x: int = Field(description="Display X position")
+    y: int = Field(description="Display Y position")
+    is_primary: bool = Field(default=False, description="Whether this is the primary display")
+
+
+class DisplayListResponse(BaseModel):
+    """List of available displays."""
+
+    displays: List[DisplayInfo] = Field(description="Available displays")
+    count: int = Field(description="Number of displays")
+
+
+# Device Schemas
+
+class DeviceCreate(BaseModel):
+    """Request to create/attach a WLED device."""
+
+    name: str = Field(description="Device name", min_length=1, max_length=100)
+    url: str = Field(description="WLED device URL (e.g., http://192.168.1.100)")
+    led_count: int = Field(description="Total number of LEDs", gt=0, le=10000)
+
+
+class DeviceUpdate(BaseModel):
+    """Request to update device information."""
+
+    name: Optional[str] = Field(None, description="Device name", min_length=1, max_length=100)
+    url: Optional[str] = Field(None, description="WLED device URL")
+    led_count: Optional[int] = Field(None, description="Total number of LEDs", gt=0, le=10000)
+    enabled: Optional[bool] = Field(None, description="Whether device is enabled")
+
+
+class ColorCorrection(BaseModel):
+    """Color correction settings."""
+
+    gamma: float = Field(default=2.2, description="Gamma correction", ge=0.1, le=5.0)
+    saturation: float = Field(default=1.0, description="Saturation multiplier", ge=0.0, le=2.0)
+    brightness: float = Field(default=1.0, description="Brightness multiplier", ge=0.0, le=1.0)
+
+
+class ProcessingSettings(BaseModel):
+    """Processing settings for a device."""
+
+    display_index: int = Field(default=0, description="Display to capture", ge=0)
+    fps: int = Field(default=30, description="Target frames per second", ge=1, le=60)
+    border_width: int = Field(default=10, description="Border width in pixels", ge=1, le=100)
+    brightness: float = Field(default=1.0, description="Global brightness (0.0-1.0)", ge=0.0, le=1.0)
+    color_correction: Optional[ColorCorrection] = Field(
+        default_factory=ColorCorrection,
+        description="Color correction settings"
+    )
+
+
+class CalibrationSegment(BaseModel):
+    """Calibration segment for LED mapping."""
+
+    edge: Literal["top", "right", "bottom", "left"] = Field(description="Screen edge")
+    led_start: int = Field(description="Starting LED index", ge=0)
+    led_count: int = Field(description="Number of LEDs on this edge", gt=0)
+    reverse: bool = Field(default=False, description="Reverse LED order on this edge")
+
+
+class Calibration(BaseModel):
+    """Calibration configuration for pixel-to-LED mapping."""
+
+    layout: Literal["clockwise", "counterclockwise"] = Field(
+        default="clockwise",
+        description="LED strip layout direction"
+    )
+    start_position: Literal["top_left", "top_right", "bottom_left", "bottom_right"] = Field(
+        default="bottom_left",
+        description="Position of LED index 0"
+    )
+    segments: List[CalibrationSegment] = Field(
+        description="LED segments for each screen edge",
+        min_length=1,
+        max_length=4
+    )
+
+
+class DeviceResponse(BaseModel):
+    """Device information response."""
+
+    id: str = Field(description="Device ID")
+    name: str = Field(description="Device name")
+    url: str = Field(description="WLED device URL")
+    led_count: int = Field(description="Total number of LEDs")
+    enabled: bool = Field(description="Whether device is enabled")
+    status: Literal["connected", "disconnected", "error"] = Field(
+        description="Connection status"
+    )
+    settings: ProcessingSettings = Field(description="Processing settings")
+    calibration: Optional[Calibration] = Field(None, description="Calibration configuration")
+    created_at: datetime = Field(description="Creation timestamp")
+    updated_at: datetime = Field(description="Last update timestamp")
+
+
+class DeviceListResponse(BaseModel):
+    """List of devices response."""
+
+    devices: List[DeviceResponse] = Field(description="List of devices")
+    count: int = Field(description="Number of devices")
+
+
+# Processing State Schemas
+
+class ProcessingState(BaseModel):
+    """Processing state for a device."""
+
+    device_id: str = Field(description="Device ID")
+    processing: bool = Field(description="Whether processing is active")
+    fps_actual: Optional[float] = Field(None, description="Actual FPS achieved")
+    fps_target: int = Field(description="Target FPS")
+    display_index: int = Field(description="Current display index")
+    last_update: Optional[datetime] = Field(None, description="Last successful update")
+    errors: List[str] = Field(default_factory=list, description="Recent errors")
+
+
+class MetricsResponse(BaseModel):
+    """Device metrics response."""
+
+    device_id: str = Field(description="Device ID")
+    processing: bool = Field(description="Whether processing is active")
+    fps_actual: Optional[float] = Field(None, description="Actual FPS")
+    fps_target: int = Field(description="Target FPS")
+    uptime_seconds: float = Field(description="Processing uptime in seconds")
+    frames_processed: int = Field(description="Total frames processed")
+    errors_count: int = Field(description="Total error count")
+    last_error: Optional[str] = Field(None, description="Last error message")
+    last_update: Optional[datetime] = Field(None, description="Last update timestamp")
+
+
+# Error Schemas
+
+class ErrorResponse(BaseModel):
+    """Error response."""
+
+    error: str = Field(description="Error type")
+    message: str = Field(description="Error message")
+    detail: Optional[Dict] = Field(None, description="Additional error details")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Error timestamp")