# LED Sync Studio

## What This Is

Eine Cyberpunk-Terminal-App (Python/Textual) zur Steuerung von LED-Streifen, die auf einem Raspberry Pi 4B laeuft und per SSH bedient wird. Die App ermoeglicht sowohl Song-Choreografie (Animationen manuell auf Zeitpunkte im Song mappen) als auch Live-Reaktiv-Modus (Beat-Detection aus System-Audio). Die Animationen laufen lokal auf einem ESP32-C3, der per JSON-Kommandos ueber WiFi gesteuert wird.

## Core Value

Songs mit LED-Animationen choreografieren und abspielen — der Nutzer baut Timeline-basierte Lichtshows zu seiner Musik.

## Requirements

### Validated

- ESP32-C3 Firmware: Animationen lokal ausfuehren, JSON-Kommandos empfangen — Validated in Phase 1
- Pi-zu-ESP Kommunikation ueber WiFi (JSON-Protokoll) — Validated in Phase 1
- Vielzahl an LED-Animationen (8 Built-in: Chase, Pulse, Rainbow, Strobe, Color Wash, Breathe, Sparkle, Gradient Sweep) — Validated in Phase 1
- Animationen mit Parametern konfigurierbar (Farbe/RGBW, Speed, Intensitaet) — Validated in Phase 1
- 2 LED-Zonen unabhaengig steuerbar (WS2801 Schrank + SK6812 Wand) — Validated in Phase 1

### Active

- [ ] Song abspielen und an beliebiger Stelle stoppen/fortsetzen
- [ ] Animationen auf Zeitpunkte im Song zuweisen (Choreografie-Editor)
- [ ] Timeline-Ansicht (horizontal, Song laeuft links-rechts, Animationen als Bloecke)
- [ ] Event-Liste-Ansicht (tabellarisch, Zeitpunkte mit Animationen)
- [ ] Loop-Funktion fuer Animationen (Wiederholungen definieren)
- [ ] Choreografien als Dateien speichern und laden (JSON/YAML)
- [ ] Live-Reaktiv-Modus mit Beat-Detection aus System-Audio (PipeWire/PulseAudio)
- [ ] Lokale Songdateien abspielen (MP3/FLAC/WAV)
- [ ] Streaming-Dienst-Integration (Spotify o.ae.) als Audio-Quelle
- [ ] Cyberpunk/Neon Terminal-UI mit Textual

### Out of Scope

- Frame-Streaming vom Pi zum ESP — ESP fuehrt Animationen lokal aus, Pi sendet nur Kommandos
- Web-UI oder GUI — reines Terminal mit Textual
- Mehr als ein ESP32 — beide Strips laufen an einem ESP32-C3

## Context

- **Hardware:** ESP32-C3 SuperMini mit 2 LED-Strips: WS2801 5m/160 LEDs (U-Turn um Schrank) und SK6812 5m/300 LEDs (Wand entlang)
- **Host:** Raspberry Pi 4B, Zugriff per SSH vom Laptop
- **Kommunikation:** Pi sendet JSON-Kommandos an ESP ueber WiFi — keine Frame-Daten, nur Animation-Name + Parameter
- **Audio:** System-Audio-Stream (PipeWire/PulseAudio) fuer Beat-Detection und Song-Playback
- **Firmware:** ESP32-C3 Firmware muss komplett neu gebaut werden (Arduino/ESP-IDF)
- **UI-Style:** Cyberpunk/Neon — leuchtende Neonfarben, dunkler Hintergrund, Glitch-Aesthetic

## Constraints

- **Platform**: Raspberry Pi 4B (ARM, Linux) — App muss performant auf Pi laufen
- **Terminal**: Textual TUI Framework (Python) — muss ueber SSH funktionieren
- **ESP**: ESP32-C3 SuperMini — begrenzter Speicher, ein Core, WiFi only
- **LED-Protokoll**: WS2801 (SPI/Clock+Data) und SK6812 (single-wire like NeoPixel) — unterschiedliche Ansteuerung
- **Latenz**: JSON-Kommandos muessen schnell genug sein fuer musikalische Synchronisation

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Animationen laufen auf ESP, nicht gestreamt | Reduziert WiFi-Last und Latenz, ESP ist autonom | -- Pending |
| Ein ESP fuer beide Strips | Einfacheres Setup, ESP32-C3 hat genug GPIOs | -- Pending |
| Textual als UI-Framework | Terminal-basiert, laeuft ueber SSH, Python-Oekosystem | -- Pending |
| JSON ueber WiFi (Pi->ESP) | Einfach, flexibel, kein Kabel noetig | -- Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd:transition`):
1. Requirements invalidated? -> Move to Out of Scope with reason
2. Requirements validated? -> Move to Validated with phase reference
3. New requirements emerged? -> Add to Active
4. Decisions to log? -> Add to Key Decisions
5. "What This Is" still accurate? -> Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-04-03 after Phase 1 completion*