7f9efee47a
- SUMMARY.md for 02-03 (waveform extractor + transport UI) - STATE.md: checkpoint at human-verify task 3, decisions recorded - ROADMAP.md: phase 2 progress updated (3/3 plans) - REQUIREMENTS.md: AUD-05 marked complete
6.3 KiB
6.3 KiB
Requirements: LightSync
Defined: 2026-04-05 Core Value: Load a song, build a synchronized light show, play it back live — with precise control over every effect on every device.
v1 Requirements
Audio Engine
- AUD-01: Load audio from a local file (MP3, WAV, FLAC, OGG)
- AUD-02: Load audio from a YouTube URL via yt-dlp + MPV
- AUD-03: Playback controls: play, pause, seek to position
- AUD-04: Realtime position reporting from MPV to UI (via named pipe IPC, ≤10ms poll interval)
- AUD-05: Waveform display rendered from audio samples in the timeline UI
Device Registry
- DEV-01: Register a device with: name, strip type (SK6812 / WS2801 / generic), LED count, target IP, target port
- DEV-02: Devices persist across sessions (stored in config file)
- DEV-03: Device list shown in UI — enable/disable per show
Animation Library
- ANI-01: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color
- ANI-02: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density
- ANI-03: RGBW-aware color handling for SK6812 (separate W channel)
- ANI-04: RGB color handling for WS2801
Timeline Editor
- TL-01: Per-device horizontal tracks on a time axis
- TL-02: Drag-and-place animation blocks onto a track
- TL-03: Move, resize, and delete animation blocks
- TL-04: Color picker per animation block
- TL-05: Playback cursor (vertical line) tracking audio position in realtime
- TL-06: Undo/redo for all timeline mutations (min 20 steps, command pattern)
- TL-07: Beat detection marks overlaid on timeline (librosa beat_track)
- TL-08: Snap-to-beat when placing/resizing blocks
Show Engine
- SHW-01: Show files saved and loaded as JSON (schema_version field required in v1)
- SHW-02: Show file includes: audio path/URL, device registry snapshot, all animation blocks with timestamps, beat analysis data
- SHW-03: Live show execution — follow MPV position, dispatch animation commands to devices via UDP at correct timestamps
UDP Communication
- UDP-01: Animation command packet: device ID, animation type, params — sent when block starts
- UDP-02: Raw pixel frame packet: WLED DRGB/DNRGB/DRGBW protocol — used for AI-generated sequences
- UDP-03: Multi-packet framing for frames >MTU (SK6812 300 LEDs RGBW = 1200 bytes, exceeds WiFi MTU)
- UDP-04: Software UDP receiver/simulator for testing without physical hardware
Automatic Sync
- SYNC-01: Beat detection via librosa — produces beat timestamps and onset marks from loaded audio
- SYNC-02: Beat calibration offset (UI control) — compensate for librosa's systematic 20-60ms latency bias
- SYNC-03: AI-assisted show generation — given beat/segment analysis, auto-fill timeline with matched animations (basic heuristic mapping in v1; LLM enhancement optional)
UI / UX
- UI-01: Web app served by Python backend — no external hosting required
- UI-02: Terminal/hacker aesthetic — dark theme, monospace fonts, CRT/scanline vibe; NOT generic SaaS look
- UI-03: All primary operations accessible without mouse (keyboard shortcuts for play/pause/seek/undo)
- UI-04: Live preview panel — simulated LED strip visualization in browser canvas, synced to playback
Infrastructure
- INF-01: Python 3.11 backend (FastAPI + uvicorn)
- INF-02: Modular device abstraction — adding a new strip type requires only a new device class, no changes to core engine
- INF-03: Windows 11 timer resolution fix applied at startup (
timeBeginPeriod(1)via ctypes)
v2 Requirements
Enhancements (deferred)
- V2-01: Structural segmentation overlay — librosa section detection (verse/chorus/bridge) shown as colored regions on waveform
- V2-02: Effect grouping / scenes — group blocks across devices into named scenes, drag-place whole scenes
- V2-03: Frequency band mapping — bass/mid/treble energy mapped to device params
- V2-04: Parameter animation curves — envelope curves on per-block params (speed, brightness) over time
- V2-05: Show export for standalone/offline playback (self-contained show package)
Firmware (deferred — last phase)
- FW-01: MicroPython firmware for ESP32/Pico/RPi 4B — receives UDP animation command packets, renders animations locally
- FW-02: MicroPython firmware — receives DRGB/DNRGB/DRGBW raw frame packets, outputs to LED strip
Out of Scope
| Feature | Reason |
|---|---|
| Real-time microphone input | Conflicts with file-based deterministic sync model; adds latency pipeline |
| Multi-user / collaborative editing | Zero personal-use value; conflicts complicate state management |
| Cloud sync / remote access | Local network only; Authelia provides LAN access |
| MIDI controller support | Beat detection covers the use case; adds OS driver complexity |
| DMX / ArtNet / E1.31 | Direct UDP is simpler and lower latency at this scale |
| Plugin / extension system | Add effects directly in Python; modular device abstraction covers extensibility |
| 3D fixture visualizer | 2D canvas preview is sufficient for LED strips |
| Scheduling / playlist automation | Interactive personal tool; manual launch from UI is correct |
Traceability
| Requirement | Phase | Status |
|---|---|---|
| INF-01, INF-02 | Phase 1 | Pending |
| SHW-01, SHW-02 | Phase 1 | Pending |
| DEV-01, DEV-02, DEV-03 | Phase 1 | Pending |
| AUD-01, AUD-02, AUD-03, AUD-04 | Phase 2 | Pending |
| AUD-05 | Phase 2 | Complete |
| INF-03 | Phase 2 | Complete |
| UDP-01, UDP-02, UDP-03, UDP-04 | Phase 3 | Pending |
| ANI-01, ANI-02, ANI-03, ANI-04 | Phase 3 | Pending |
| TL-01, TL-02, TL-03, TL-04, TL-05, TL-06 | Phase 4 | Pending |
| TL-07, TL-08, SYNC-01, SYNC-02 | Phase 4 | Pending |
| SHW-03, UI-03 | Phase 5 | Pending |
| UI-01, UI-02, UI-04 | Phases 1-5 (progressive) | Pending |
| SYNC-03 | Phase 6 | Pending |
| FW-01, FW-02 | Phase 7 | Pending |
Coverage:
- v1 requirements: 31 total
- Mapped to phases: 31
- Unmapped: 0 ✓
Requirements defined: 2026-04-05 Last updated: 2026-04-05 after initialization