Add real-time audio spectrum test for audio sources and templates

- Add WebSocket endpoints for live audio spectrum streaming at ~20Hz
- Audio source test: resolves device/channel, shares stream via ref-counting
- Audio template test: includes device picker dropdown for selecting input
- Canvas-based 64-band spectrum visualizer with falling peaks and beat flash
- Channel-aware: mono sources show left/right/mixed spectrum correctly

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

server/src/wled_controller/api/routes/audio_sources.py

@@ -1,13 +1,18 @@
-"""Audio source routes: CRUD for audio sources."""
+"""Audio source routes: CRUD for audio sources + real-time test WebSocket."""
 
+import asyncio
+import secrets
 from typing import Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from starlette.websockets import WebSocket, WebSocketDisconnect
 
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import (
     get_audio_source_store,
+    get_audio_template_store,
     get_color_strip_store,
+    get_processor_manager,
 )
 from wled_controller.api.schemas.audio_sources import (
     AudioSourceCreate,
@@ -15,6 +20,7 @@ from wled_controller.api.schemas.audio_sources import (
     AudioSourceResponse,
     AudioSourceUpdate,
 )
+from wled_controller.config import get_config
 from wled_controller.storage.audio_source import AudioSource
 from wled_controller.storage.audio_source_store import AudioSourceStore
 from wled_controller.storage.color_strip_store import ColorStripStore
@@ -140,3 +146,100 @@ async def delete_audio_source(
         return {"status": "deleted", "id": source_id}
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
+
+
+# ===== REAL-TIME AUDIO TEST WEBSOCKET =====
+
+
+@router.websocket("/api/v1/audio-sources/{source_id}/test/ws")
+async def test_audio_source_ws(
+    websocket: WebSocket,
+    source_id: str,
+    token: str = Query(""),
+):
+    """WebSocket for real-time audio spectrum analysis. Auth via ?token=<api_key>.
+
+    Resolves the audio source to its device, acquires a ManagedAudioStream
+    (ref-counted — shares with running targets), and streams AudioAnalysis
+    snapshots as JSON at ~20 Hz.
+    """
+    # Authenticate
+    authenticated = False
+    cfg = get_config()
+    if token and cfg.auth.api_keys:
+        for _label, api_key in cfg.auth.api_keys.items():
+            if secrets.compare_digest(token, api_key):
+                authenticated = True
+                break
+
+    if not authenticated:
+        await websocket.close(code=4001, reason="Unauthorized")
+        return
+
+    # Resolve source → device info
+    store = get_audio_source_store()
+    template_store = get_audio_template_store()
+    manager = get_processor_manager()
+
+    try:
+        device_index, is_loopback, channel, audio_template_id = store.resolve_audio_source(source_id)
+    except ValueError as e:
+        await websocket.close(code=4004, reason=str(e))
+        return
+
+    # Resolve template → engine_type + config
+    engine_type = None
+    engine_config = None
+    if audio_template_id:
+        try:
+            template = template_store.get_template(audio_template_id)
+            engine_type = template.engine_type
+            engine_config = template.engine_config
+        except ValueError:
+            pass  # Fall back to best available engine
+
+    # Acquire shared audio stream
+    audio_mgr = manager.audio_capture_manager
+    try:
+        stream = audio_mgr.acquire(device_index, is_loopback, engine_type, engine_config)
+    except RuntimeError as e:
+        await websocket.close(code=4003, reason=str(e))
+        return
+
+    await websocket.accept()
+    logger.info(f"Audio test WebSocket connected for source {source_id}")
+
+    last_ts = 0.0
+    try:
+        while True:
+            analysis = stream.get_latest_analysis()
+            if analysis is not None and analysis.timestamp != last_ts:
+                last_ts = analysis.timestamp
+
+                # Select channel-specific data
+                if channel == "left":
+                    spectrum = analysis.left_spectrum
+                    rms = analysis.left_rms
+                elif channel == "right":
+                    spectrum = analysis.right_spectrum
+                    rms = analysis.right_rms
+                else:
+                    spectrum = analysis.spectrum
+                    rms = analysis.rms
+
+                await websocket.send_json({
+                    "spectrum": spectrum.tolist(),
+                    "rms": round(rms, 4),
+                    "peak": round(analysis.peak, 4),
+                    "beat": analysis.beat,
+                    "beat_intensity": round(analysis.beat_intensity, 4),
+                })
+
+            await asyncio.sleep(0.05)
+    except WebSocketDisconnect:
+        pass
+    except Exception as e:
+        logger.error(f"Audio test WebSocket error for {source_id}: {e}")
+    finally:
+        audio_mgr.release(device_index, is_loopback, engine_type)
+        logger.info(f"Audio test WebSocket disconnected for source {source_id}")