From 1afa95ffc35cebe07a69806686689487aa1ee700 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Apr 2026 14:14:07 +0200 Subject: [PATCH] docs(02-app-core-audio): create phase 2 plan (6 plans, 3 waves) --- .planning/ROADMAP.md | 85 -------------------------------------------- 1 file changed, 85 deletions(-) delete mode 100644 .planning/ROADMAP.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md deleted file mode 100644 index f078e9e..0000000 --- a/.planning/ROADMAP.md +++ /dev/null @@ -1,85 +0,0 @@ -# Roadmap: LED Sync Studio - -## Overview - -Four phases build a music-synchronized LED choreography system from hardware up. Phase 1 validates the ESP32 firmware and retires all hardware risks before any Pi-side code is written. Phase 2 builds the headless Pi core — audio playback, beat detection, choreography engine, and UDP transport — all CLI-testable against real hardware. Phase 3 assembles the full cyberpunk TUI on top of the stable core, delivering the choreography editor end-to-end. Phase 4 adds live-reactive mode and Spotify as a second audio source. - -## Phases - -**Phase Numbering:** -- Integer phases (1, 2, 3): Planned milestone work -- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) - -Decimal phases appear between their surrounding integers in numeric order. - -- [x] **Phase 1: ESP32 Firmware** - Both LED strips driven by a WiFi-connected ESP32 that executes named animations from JSON commands (completed 2026-04-03) -- [ ] **Phase 2: App Core + Audio** - Headless Pi layer: song playback, beat detection, choreography engine, UDP transport -- [ ] **Phase 3: Choreography TUI** - Full cyberpunk terminal UI with timeline editor, event list, transport controls, and animation panel -- [ ] **Phase 4: Live Reactive + Spotify** - Beat-driven animation mode with sensitivity calibration and Spotify as audio source - -## Phase Details - -### Phase 1: ESP32 Firmware -**Goal**: Both LED strips are driven by one ESP32-C3 that receives JSON commands over WiFi and executes named animations autonomously -**Depends on**: Nothing (first phase) -**Requirements**: FW-01, FW-02, FW-03, FW-04, FW-05 -**Success Criteria** (what must be TRUE): - 1. WS2801 (160 LEDs, SPI) and SK6812 (300 LEDs, RMT/RGBW) both illuminate correctly and simultaneously with no flicker from WiFi interference - 2. Sending a UDP JSON command (e.g. `{"zone":"wall","animation":"chase","speed":0.5}`) from a laptop triggers the named animation on the correct strip within 50ms - 3. All 8 built-in animations (Chase, Pulse, Rainbow, Strobe, Color Wash, Breathe, Sparkle, Gradient Sweep) run on either zone without crashing - 4. Each zone can be commanded independently — different animations run on Schrank and Wand simultaneously - 5. Animation parameters (color/RGBW, speed, intensity) visibly change behavior when included in the JSON command -**Plans**: 4 plans - -Plans: -- [x] 01-01-PLAN.md — PlatformIO scaffold, dual LED driver, WiFi+RMT coexistence validation -- [x] 01-02-PLAN.md — UDP server, JSON protocol parser, FreeRTOS command queue -- [x] 01-03-PLAN.md — Animation engine (50fps FreeRTOS), all 8 built-in animations -- [x] 01-04-PLAN.md — System integration, final wiring, hardware acceptance checkpoint - -### Phase 2: App Core + Audio -**Goal**: The Pi can play songs, detect beats, schedule choreography events, and send animation commands to the ESP32 — all testable from the command line without any TUI -**Depends on**: Phase 1 -**Requirements**: AUD-01, AUD-02, AUD-03, AUD-04, CHR-04, CHR-05 -**Success Criteria** (what must be TRUE): - 1. A local MP3, FLAC, or WAV file plays with audible output and the current playback position is readable at any moment - 2. Playback can be paused, resumed, and seeked to an arbitrary timestamp via CLI commands - 3. Beat events are detected from the system audio stream in real time (aubio) with visible console output per beat - 4. A choreography JSON file loads and plays back: correct animations fire on the ESP32 at the timestamps specified in the file - 5. Choreography edits (adding an event) save to a JSON file that reloads correctly on next run -**Plans**: TBD - -### Phase 3: Choreography TUI -**Goal**: The full cyberpunk terminal UI is usable over SSH: user can load a song, place animations on the timeline, and play back a complete light show -**Depends on**: Phase 2 -**Requirements**: CHR-01, CHR-02, CHR-03, UI-01, UI-02, UI-03, UI-04, UI-05, UI-06 -**Success Criteria** (what must be TRUE): - 1. The TUI launches over SSH with cyberpunk/neon styling — dark background, glowing colored elements — and all panels are legible in a standard terminal - 2. User can select a position in the song, choose an animation with parameters, and assign it to a zone — it appears as a block on the timeline view - 3. User can tap a key on the beat during playback to stamp timing marks, and those marks are visible on the timeline - 4. User can switch between Timeline view (horizontal blocks) and Event List view (table of timestamps) for the same choreography - 5. Pressing Play runs the full light show — animations fire on the ESP32 in sync with the song — and the playhead advances visibly on the timeline -**Plans**: TBD -**UI hint**: yes - -### Phase 4: Live Reactive + Spotify -**Goal**: Users can switch into live-reactive mode where beats drive LED animations in real time, and can optionally use Spotify as the audio source -**Depends on**: Phase 3 -**Requirements**: LIVE-01, LIVE-02, SPT-01 -**Success Criteria** (what must be TRUE): - 1. User can switch from choreography mode to live-reactive mode without restarting the app, and LEDs respond to beats within 100ms of audio onset - 2. User can adjust beat-detection sensitivity in the UI and see the effect immediately — more sensitive triggers fire on quieter transients, less sensitive ignores them - 3. Spotify audio passes through the system audio pipeline and triggers beat-reactive animations the same way local file playback does -**Plans**: TBD - -## Progress - -**Execution Order:** -Phases execute in numeric order: 1 → 2 → 3 → 4 - -| Phase | Plans Complete | Status | Completed | -|-------|----------------|--------|-----------| -| 1. ESP32 Firmware | 4/4 | Complete | 2026-04-03 | -| 2. App Core + Audio | 0/? | Not started | - | -| 3. Choreography TUI | 0/? | Not started | - | -| 4. Live Reactive + Spotify | 0/? | Not started | - |