# 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)
- [ ] **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

- [ ] **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

- [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

- [ ] **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

- [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 | Pending |
| 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*