# Requirements: LED Sync Studio

**Defined:** 2026-04-03
**Core Value:** Songs mit LED-Animationen choreografieren und abspielen — der Nutzer baut Timeline-basierte Lichtshows zu seiner Musik.

## v1 Requirements

### Firmware

- [x] **FW-01**: ESP32-C3 treibt WS2801 (160 LEDs, SPI) und SK6812 (300 LEDs, RMT/RGBW) gleichzeitig an
- [x] **FW-02**: ESP32-C3 empfaengt JSON-Kommandos ueber UDP und fuehrt benannte Animationen aus
- [x] **FW-03**: Mindestens 8 Built-in-Animationen (Chase, Pulse, Rainbow, Strobe, Color Wash, Breathe, Sparkle, Gradient Sweep)
- [x] **FW-04**: Jede Animation akzeptiert konfigurierbare Parameter (Farbe/RGBW, Speed, Intensitaet)
- [x] **FW-05**: Beide LED-Zonen (Schrank/Wand) sind unabhaengig steuerbar ueber das JSON-Protokoll

### Audio

- [x] **AUD-01**: User kann lokale Songdateien laden und abspielen (MP3, FLAC, WAV)
- [x] **AUD-02**: User kann Songs pausieren, fortsetzen und an beliebige Stelle springen (Seek)
- [x] **AUD-03**: System-Audio wird ueber PipeWire/PulseAudio fuer Beat-Detection erfasst
- [x] **AUD-04**: Beat/Onset-Detection erkennt Schlaege aus dem Audio-Stream in Echtzeit

### Choreografie

- [ ] **CHR-01**: User kann an einer Stelle im Song stoppen und eine Animation mit Parametern zuweisen
- [ ] **CHR-02**: User kann Timing-Marks setzen durch Tastendruck waehrend der Wiedergabe (Tapper)
- [ ] **CHR-03**: User kann Animationsloops definieren (N-mal wiederholen oder bis zum naechsten Event)
- [x] **CHR-04**: Choreografien koennen als JSON-Dateien gespeichert und geladen werden
- [x] **CHR-05**: Choreografie-Playback sendet Animationskommandos zeitgenau an den ESP32

### Live Reaktiv

- [ ] **LIVE-01**: User kann in den Live-Reaktiv-Modus wechseln (Beat-Detection -> Animation-Trigger)
- [ ] **LIVE-02**: User kann Empfindlichkeit der Beat-Detection kalibrieren

### Terminal UI

- [ ] **UI-01**: Textual TUI mit Cyberpunk/Neon-Aesthetic (leuchtende Farben, dunkler Hintergrund)
- [ ] **UI-02**: Timeline-Ansicht mit horizontaler Zeitachse und Animationsbloecken pro Zone
- [ ] **UI-03**: Event-Liste-Ansicht (tabellarisch: Zeitpunkt, Animation, Parameter, Zone)
- [ ] **UI-04**: Transport-Controls (Play, Pause, Stop, Seek) in der UI
- [ ] **UI-05**: Animations-Panel zum Auswaehlen und Konfigurieren von Animationen
- [ ] **UI-06**: App funktioniert vollstaendig ueber SSH

### Spotify

- [ ] **SPT-01**: User kann Spotify als Audio-Quelle nutzen (via System-Audio-Loopback oder Spotify Connect)

## v2 Requirements

### Editor Polish

- **EDIT-01**: Undo / Redo fuer alle Editor-Aktionen
- **EDIT-02**: Per-Block Transition-Effekte (Crossfade, Dissolve zwischen Animationen)
- **EDIT-03**: Auto-Beat-Detection Timing Marks (aubio analysiert Song, setzt Marks automatisch)
- **EDIT-04**: Audio-Waveform-Anzeige auf der Timeline

### Reactive Advanced

- **REACT-01**: Zone-aware Beat-Routing (Bass -> Schrank, Treble -> Wand)
- **REACT-02**: Animation-Preview im Terminal (ASCII LED-Simulation)

## Out of Scope

| Feature | Reason |
|---------|--------|
| Frame-Streaming vom Pi zum ESP | ESP fuehrt Animationen lokal aus; WiFi-Jitter macht Frame-Streaming unzuverlaessig |
| Web-UI / Browser-Interface | Terminal-SSH ist das Alleinstellungsmerkmal |
| Mehrere ESP32s | Ein ESP32-C3 steuert beide Strips; kein zusaetzlicher Controller |
| Cloud-Sync / Multi-User | Lokales Tool, keine Netzwerk-Abhaengigkeit |
| DMX / E1.31 / sACN Protokoll | Out of hardware scope; xLights deckt das ab |
| 2D-Matrix-Effekte | Hardware ist 1D (Strips), keine Matrix |
| xLights .xsq Import/Export | Komplexes Format, unklarer Bedarf |
| Scripted Effect DSL | Power-User-Feature, nicht fuer v1 |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| FW-01 | Phase 1 | Complete |
| FW-02 | Phase 1 | Complete |
| FW-03 | Phase 1 | Complete |
| FW-04 | Phase 1 | Complete |
| FW-05 | Phase 1 | Complete |
| AUD-01 | Phase 2 | Complete |
| AUD-02 | Phase 2 | Complete |
| AUD-03 | Phase 2 | Complete |
| AUD-04 | Phase 2 | Complete |
| CHR-04 | Phase 2 | Complete |
| CHR-05 | Phase 2 | Complete |
| CHR-01 | Phase 3 | Pending |
| CHR-02 | Phase 3 | Pending |
| CHR-03 | Phase 3 | Pending |
| UI-01 | Phase 3 | Pending |
| UI-02 | Phase 3 | Pending |
| UI-03 | Phase 3 | Pending |
| UI-04 | Phase 3 | Pending |
| UI-05 | Phase 3 | Pending |
| UI-06 | Phase 3 | Pending |
| LIVE-01 | Phase 4 | Pending |
| LIVE-02 | Phase 4 | Pending |
| SPT-01 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 23 total
- Mapped to phases: 23
- Unmapped: 0

---
*Requirements defined: 2026-04-03*
*Last updated: 2026-04-03 after roadmap creation*