b6a08c4e25
- 02-01-SUMMARY.md: plan outcomes, decisions, deviations documented - STATE.md: plan counter advanced to 4/6, decisions added, metrics recorded - ROADMAP.md: Phase 02 progress updated (3/6 summaries complete) - REQUIREMENTS.md: CHR-04 marked complete
94 lines
6.2 KiB
Markdown
94 lines
6.2 KiB
Markdown
# 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**: 6 plans
|
|
|
|
Plans:
|
|
- [x] 02-01-PLAN.md — Project scaffold (pyproject.toml, uv deps) + Pydantic choreography models
|
|
- [x] 02-02-PLAN.md — UDP transport client (asyncio DatagramProtocol to ESP32)
|
|
- [x] 02-03-PLAN.md — Audio player (miniaudio playback, position tracking, pause/seek)
|
|
- [ ] 02-04-PLAN.md — Choreography scheduler (absolute monotonic clock, event dispatch)
|
|
- [ ] 02-05-PLAN.md — Beat detector (sounddevice + aubio, asyncio bridge)
|
|
- [ ] 02-06-PLAN.md — Main entry point + asyncio REPL + hardware acceptance checkpoint
|
|
|
|
### 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/6 | Not started | - |
|
|
| 3. Choreography TUI | 0/? | Not started | - |
|
|
| 4. Live Reactive + Spotify | 0/? | Not started | - |
|