From 1d26fc2dc5d1d1a3ad8c1b8a68126e1c0c4f56e5 Mon Sep 17 00:00:00 2001
From: Claude <claude@groll.cloud>
Date: Fri, 3 Apr 2026 12:29:27 +0200
Subject: [PATCH] docs: define v1 requirements

---
 .planning/REQUIREMENTS.md | 89 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 .planning/REQUIREMENTS.md

diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..2abb702
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,89 @@
+# 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
+
+- [ ] **FW-01**: ESP32-C3 treibt WS2801 (160 LEDs, SPI) und SK6812 (300 LEDs, RMT/RGBW) gleichzeitig an
+- [ ] **FW-02**: ESP32-C3 empfaengt JSON-Kommandos ueber UDP und fuehrt benannte Animationen aus
+- [ ] **FW-03**: Mindestens 8 Built-in-Animationen (Chase, Pulse, Rainbow, Strobe, Color Wash, Breathe, Sparkle, Gradient Sweep)
+- [ ] **FW-04**: Jede Animation akzeptiert konfigurierbare Parameter (Farbe/RGBW, Speed, Intensitaet)
+- [ ] **FW-05**: Beide LED-Zonen (Schrank/Wand) sind unabhaengig steuerbar ueber das JSON-Protokoll
+
+### Audio
+
+- [ ] **AUD-01**: User kann lokale Songdateien laden und abspielen (MP3, FLAC, WAV)
+- [ ] **AUD-02**: User kann Songs pausieren, fortsetzen und an beliebige Stelle springen (Seek)
+- [ ] **AUD-03**: System-Audio wird ueber PipeWire/PulseAudio fuer Beat-Detection erfasst
+- [ ] **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)
+- [ ] **CHR-04**: Choreografien koennen als JSON-Dateien gespeichert und geladen werden
+- [ ] **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 |
+|-------------|-------|--------|
+| (populated during roadmap creation) | | |
+
+**Coverage:**
+- v1 requirements: 22 total
+- Mapped to phases: 0
+- Unmapped: 22
+
+---
+*Requirements defined: 2026-04-03*
+*Last updated: 2026-04-03 after initial definition*