From f89ff71fd6935a0edbd9e275b2c63aad37b9a8a1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Apr 2026 12:02:56 +0200 Subject: [PATCH] docs: initialize project --- .planning/PROJECT.md | 85 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..942fe38 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,85 @@ +# 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 + +(None yet — ship to validate) + +### 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) +- [ ] Vielzahl an LED-Animationen (Farbwechsel, Lauflichter, Pulsieren, Spektrum, etc.) +- [ ] Animationen mit Parametern konfigurierbar (Farbe, Speed, Intensitaet, etc.) +- [ ] 2 LED-Zonen unabhaengig steuerbar (WS2801 Schrank + SK6812 Wand) +- [ ] 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 +- [ ] ESP32-C3 Firmware: Animationen lokal ausfuehren, JSON-Kommandos empfangen +- [ ] Pi-zu-ESP Kommunikation ueber WiFi (JSON-Protokoll) +- [ ] 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 initialization*