wled-screen-controller-mixed/TODO.md

Pending Features & Issues

Priority: P1 quick win · P2 moderate · P3 large effort

Processing Pipeline

• P1 Noise gate — Suppress small color changes below threshold, preventing shimmer on static content
• P1 Color temperature filter — Already covered by existing Color Correction filter (2000-10000K)
• P1 Zone grouping — Merge adjacent LEDs into logical groups sharing one averaged color
  • Complexity: medium — doesn't fit the PP filter model (operates on extracted LED colors, not images); needs a new param on calibration/color-strip-source config + PixelMapper changes
  • Impact: high — smooths out single-LED noise, visually cleaner ambilight on sparse strips
• P2 Palette quantization — Force output to match a user-defined palette (preset or custom hex)
• P2 Drag-and-drop filter ordering — Reorder postprocessing filter chains visually
• P3 Transition effects — Crossfade, wipe, or dissolve between sources/profiles instead of instant cut
  • Complexity: large — requires a new transition layer concept in ProcessorManager; must blend two live streams simultaneously during switch, coordinating start/stop timing
  • Impact: medium — polishes profile switching UX but ambient lighting rarely switches sources frequently

Output Targets

• P1 Rename picture-targets to output-targets — Rename API endpoints and internal references for clarity
• P2 OpenRGB — Control PC peripherals (keyboard, mouse, RAM, fans) as ambient targets
• P2 Art-Net / sACN (E1.31) — Stage/theatrical lighting protocols, DMX controllers
  • Complexity: medium — UDP-based protocols with well-documented specs; similar architecture to DDP client; needs DMX universe/channel mapping UI
  • Impact: medium — opens stage/theatrical use case, niche but differentiating

Automation & Integration

• P2 Webhook/MQTT trigger — Let external systems activate profiles without HA integration
  • Complexity: low-medium — webhook: simple FastAPI endpoint calling SceneActivator; MQTT: add asyncio-mqtt dependency + subscription loop
  • Impact: high — key integration point for home automation users without Home Assistant
• P2 WebSocket event bus — Broadcast all state changes over a single WS channel
  • Complexity: low-medium — ProcessorManager already emits events; add a WS endpoint that fans out JSON events to connected clients
  • Impact: medium — enables real-time dashboards, mobile apps, and third-party integrations
• P3 Notification reactive — Flash/pulse on OS notifications (optional app filter)
  • Complexity: large — OS-level notification listener (platform-specific: Win32 WinToast/pystray, macOS pyobjc); needs a new "effect source" type that triggers color pulses
  • Impact: low-medium — fun but niche; platform-dependent maintenance burden

Multi-Display

• P2 Investigate multimonitor support — Research and plan support for multi-monitor setups
  • Complexity: research — audit DXGI/MSS capture engine's display enumeration; test with 2+ monitors; identify gaps in calibration UI (per-display config)
  • Impact: high — many users have multi-monitor setups; prerequisite for multi-display unification
• P3 Multi-display unification — Treat 2-3 monitors as single virtual display for seamless ambilight
  • Complexity: large — virtual display abstraction stitching multiple captures; edge-matching calibration between monitors; significant UI changes
  • Impact: high — flagship feature for multi-monitor users, but depends on investigation results

Capture Engines

• P3 SCRCPY capture engine — Implement SCRCPY-based screen capture for Android devices
  • Complexity: large — external dependency on scrcpy binary; need to manage subprocess lifecycle, parse video stream (ffmpeg/AV pipe), handle device connect/disconnect
  • Impact: medium — enables phone screen mirroring to ambient lighting; appeals to mobile gaming use case
• P3 Camera / webcam — Border-sampling from camera feed for video calls or room-reactive lighting

Code Health (from review 2026-03-09)

Bugs

• P1 Thread safety: dict mutation during iteration — composite_stream.py / mapped_stream.py _sub_streams.clear() crashes processing loop
• P1 Thread safety: SyncClockRuntime.get_time() race — compound read without lock causes time double-counting
• P1 Thread safety: SyncClockManager unprotected dicts — _runtimes/_ref_counts mutated from multiple threads without lock
• P1 Clock ref-count corruption on hot-swap — _release_clock reads new clock_id from store instead of old one
• P1 Path traversal guard — auto_backup.py uses string checks instead of Path.resolve().is_relative_to()
• P2 Crash doesn't fire state_change event — fatal exception path in wled_target_processor.py doesn't notify dashboard
• P2 WS broadcast client mismatch — kc_target_processor.py zip(clients, results) can pair wrong clients after concurrent removal

Performance

• P1 Triple FFT for mono audio — analysis.py runs 3 identical FFTs when audio is mono (2x wasted CPU)
• P2 Per-frame np.array() from list — ddp_client.py:195 allocates new numpy array every frame
• P2 frame_time recomputed every loop iteration — 1.0/fps in 8 stream files, should be cached
• P2 Effect/composite/mapped streams hardcoded to 30 FPS — ignores target FPS, bottlenecks 60 FPS targets
• P3 Spectrum .copy() per audio chunk — analysis.py ~258 array allocations/sec for read-only consumers

Code Quality

• P2 12 store classes with duplicated boilerplate — no base class; BaseJsonStore[T] would eliminate ~60%
• P2 DeviceStore.save() uses unsafe temp file — fixed-path .tmp instead of atomic_write_json
• P2 Route code directly mutates ProcessorManager internals — devices.py accesses manager._devices in 13+ places
• P2 scene_activator.py accesses ProcessorManager._processors directly — bypasses public API
• P3 datetime.utcnow() deprecated — 88 call sites in 42 files, should use datetime.now(timezone.utc)
• P3 color-strips.js 1900+ lines — should be split into separate modules
• P3 No DataCache for color strip sources — fetched with raw fetchWithAuth in 5+ places

Features

• P1 Auto-restart crashed processing loops — add backoff-based restart when _processing_loop dies
• P1 "Start All" targets button — "Stop All" exists but "Start All" is missing
• P2 Manual backup trigger endpoint — POST /system/auto-backup/trigger (~5 lines)
• P2 Scene snapshot should capture device brightness — software_brightness not saved/restored
• P2 Device health WebSocket events — eliminate 5-30s poll latency for online/offline detection
• P2 Distinguish "crashed" vs "stopped" in dashboard — metrics.last_error is already populated
• P3 Home Assistant MQTT discovery — publish auto-discovery payloads; MQTT infra already exists
• P3 CSS source import/export — share individual sources without full config backup
• P3 Exponential backoff on events WS reconnect — currently fixed 3s retry

UX

• P2 Tags / groups for cards — Assign tags to devices, targets, and sources; filter and group cards by tag
• P3 PWA / mobile layout — Mobile-first layout + "Add to Home Screen" manifest
• P1 Collapse dashboard running target stats — Show only FPS chart by default; uptime, errors, and pipeline timings in an expandable section collapsed by default
• P1 Review protocol badge on LED target cards — Review and improve the protocol badge display on LED target cards