Add WebSocket support for real-time media status updates

Replace HTTP polling with WebSocket push notifications for instant
state change responses. Server broadcasts updates only when significant
changes occur (state, track, volume, etc.) while letting Home Assistant
interpolate position during playback. Includes seek detection for
timeline updates and automatic fallback to HTTP polling if WebSocket
disconnects.

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

media_server/routes/media.py

@@ -1,11 +1,18 @@
 """Media control API endpoints."""
 
-from fastapi import APIRouter, Depends, HTTPException, status
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
+from fastapi import status
 from fastapi.responses import Response
 
 from ..auth import verify_token, verify_token_or_query
+from ..config import settings
 from ..models import MediaStatus, VolumeRequest, SeekRequest
 from ..services import get_media_controller, get_current_album_art
+from ..services.websocket_manager import ws_manager
+
+logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/media", tags=["media"])
 
@@ -184,3 +191,52 @@ async def get_artwork(_: str = Depends(verify_token_or_query)) -> Response:
         content_type = "image/webp"
 
     return Response(content=art_bytes, media_type=content_type)
+
+
+@router.websocket("/ws")
+async def websocket_endpoint(
+    websocket: WebSocket,
+    token: str = Query(..., description="API authentication token"),
+) -> None:
+    """WebSocket endpoint for real-time media status updates.
+
+    Authentication is done via query parameter since WebSocket
+    doesn't support custom headers in the browser.
+
+    Messages sent to client:
+    - {"type": "status", "data": {...}} - Initial status on connect
+    - {"type": "status_update", "data": {...}} - Status changes
+    - {"type": "error", "message": "..."} - Error messages
+
+    Client can send:
+    - {"type": "ping"} - Keepalive, server responds with {"type": "pong"}
+    - {"type": "get_status"} - Request current status
+    """
+    # Verify token
+    if token != settings.api_token:
+        await websocket.close(code=4001, reason="Invalid authentication token")
+        return
+
+    await ws_manager.connect(websocket)
+
+    try:
+        while True:
+            # Wait for messages from client (for keepalive/ping)
+            data = await websocket.receive_json()
+
+            if data.get("type") == "ping":
+                await websocket.send_json({"type": "pong"})
+            elif data.get("type") == "get_status":
+                # Allow manual status request
+                controller = get_media_controller()
+                status_data = await controller.get_status()
+                await websocket.send_json({
+                    "type": "status",
+                    "data": status_data.model_dump(),
+                })
+
+    except WebSocketDisconnect:
+        await ws_manager.disconnect(websocket)
+    except Exception as e:
+        logger.error("WebSocket error: %s", e)
+        await ws_manager.disconnect(websocket)