3483de871e
- BlockInspector with color/speed/direction/length param controls - UpdateParamsCommand for full undo/redo param editing - Phase 04 complete (4/4 plans), TL-04 requirement marked done - Progress: 14/14 plans (100%)
135 lines
6.3 KiB
Markdown
135 lines
6.3 KiB
Markdown
# 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
|
|
|
|
- [x] **AUD-01**: Load audio from a local file (MP3, WAV, FLAC, OGG)
|
|
- [x] **AUD-02**: Load audio from a YouTube URL via yt-dlp + MPV
|
|
- [x] **AUD-03**: Playback controls: play, pause, seek to position
|
|
- [x] **AUD-04**: Realtime position reporting from MPV to UI (via named pipe IPC, ≤10ms poll interval)
|
|
- [x] **AUD-05**: Waveform display rendered from audio samples in the timeline UI
|
|
|
|
### Device Registry
|
|
|
|
- [x] **DEV-01**: Register a device with: name, strip type (SK6812 / WS2801 / generic), LED count, target IP, target port
|
|
- [x] **DEV-02**: Devices persist across sessions (stored in config file)
|
|
- [x] **DEV-03**: Device list shown in UI — enable/disable per show
|
|
|
|
### Animation Library
|
|
|
|
- [x] **ANI-01**: Built-in animation types: chase, pulse, rainbow, strobe, color wipe, fire, solid color
|
|
- [x] **ANI-02**: Per-animation parameters: speed, primary color(s), secondary color(s), direction, length/density
|
|
- [x] **ANI-03**: RGBW-aware color handling for SK6812 (separate W channel)
|
|
- [x] **ANI-04**: RGB color handling for WS2801
|
|
|
|
### Timeline Editor
|
|
|
|
- [x] **TL-01**: Per-device horizontal tracks on a time axis
|
|
- [x] **TL-02**: Drag-and-place animation blocks onto a track
|
|
- [x] **TL-03**: Move, resize, and delete animation blocks
|
|
- [x] **TL-04**: Color picker per animation block
|
|
- [x] **TL-05**: Playback cursor (vertical line) tracking audio position in realtime
|
|
- [x] **TL-06**: Undo/redo for all timeline mutations (min 20 steps, command pattern)
|
|
- [x] **TL-07**: Beat detection marks overlaid on timeline (librosa beat_track)
|
|
- [x] **TL-08**: Snap-to-beat when placing/resizing blocks
|
|
|
|
### Show Engine
|
|
|
|
- [x] **SHW-01**: Show files saved and loaded as JSON (schema_version field required in v1)
|
|
- [x] **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
|
|
|
|
- [x] **UDP-01**: Animation command packet: device ID, animation type, params — sent when block starts
|
|
- [x] **UDP-02**: Raw pixel frame packet: WLED DRGB/DNRGB/DRGBW protocol — used for AI-generated sequences
|
|
- [x] **UDP-03**: Multi-packet framing for frames >MTU (SK6812 300 LEDs RGBW = 1200 bytes, exceeds WiFi MTU)
|
|
- [x] **UDP-04**: Software UDP receiver/simulator for testing without physical hardware
|
|
|
|
### Automatic Sync
|
|
|
|
- [x] **SYNC-01**: Beat detection via librosa — produces beat timestamps and onset marks from loaded audio
|
|
- [x] **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
|
|
|
|
- [x] **UI-01**: Web app served by Python backend — no external hosting required
|
|
- [x] **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
|
|
|
|
- [x] **INF-01**: Python 3.11 backend (FastAPI + uvicorn)
|
|
- [x] **INF-02**: Modular device abstraction — adding a new strip type requires only a new device class, no changes to core engine
|
|
- [x] **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*
|