led-sync-studio/.planning/ROADMAP.md

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.

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

• 01-01-PLAN.md — PlatformIO scaffold, dual LED driver, WiFi+RMT coexistence validation
• 01-02-PLAN.md — UDP server, JSON protocol parser, FreeRTOS command queue
• 01-03-PLAN.md — Animation engine (50fps FreeRTOS), all 8 built-in animations
• 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:

• 02-01-PLAN.md — Project scaffold (pyproject.toml, uv deps) + Pydantic choreography models
• 02-02-PLAN.md — UDP transport client (asyncio DatagramProtocol to ESP32)
• 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	-