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):

Requirements invalidated? -> Move to Out of Scope with reason
Requirements validated? -> Move to Validated with phase reference
New requirements emerged? -> Add to Active
Decisions to log? -> Add to Key Decisions
"What This Is" still accurate? -> Update if drifted

After each milestone (via /gsd:complete-milestone):

Full review of all sections
Core Value check — still the right priority?
Audit Out of Scope — reasons still valid?
Update Context with current state

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

4.2 KiB Raw Blame History