docs(05-01): complete cue scheduler plan — SUMMARY, STATE, ROADMAP updated

- 05-01-SUMMARY.md created with task commits, decisions, next-phase readiness - STATE.md advanced to plan 2/3, progress 88%, decisions logged - ROADMAP.md updated: phase 5 in progress (1/3 summaries) - REQUIREMENTS.md: SHW-03 marked complete
2026-04-07 10:12:09 +00:00
parent 64c49c9e64
commit 7809402d54
4 changed files with 128 additions and 15 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -43,7 +43,7 @@

 - [x] **SHW-01**: Show files saved and loaded as JSON (schema_version field required in v1)
 - [x] **SHW-02**: Show file includes: audio path/URL, device registry snapshot, all animation blocks with timestamps, beat analysis data
- [ ] **SHW-03**: Live show execution — follow MPV position, dispatch animation commands to devices via UDP at correct timestamps
+- [x] **SHW-03**: Live show execution — follow MPV position, dispatch animation commands to devices via UDP at correct timestamps

 ### UDP Communication

--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -109,7 +109,7 @@ Plans:
 **Plans**: 3 plans

 Plans:
- [ ] 05-01-PLAN.md — Cue scheduler: server-side position-driven scheduling, 60ms look-ahead, seek-safe fired_ids reset
+- [x] 05-01-PLAN.md — Cue scheduler: server-side position-driven scheduling, 60ms look-ahead, seek-safe fired_ids reset
 - [ ] 05-02-PLAN.md — Live preview panel + show selector: DOM device strips, preview_update handler, show load into timeline
 - [ ] 05-03-PLAN.md — Keyboard shortcuts: Space, arrows, Ctrl+Z/Y/S for mouse-free operation
 **UI hint**: yes
@@ -156,6 +156,6 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
 | 2. Audio Engine | 3/3 | Complete   | 2026-04-06 |
 | 3. Communication Protocol | 3/3 | Complete   | 2026-04-06 |
 | 4. Timeline Editor | 4/4 | Complete   | 2026-04-06 |
-| 5. Live Show Execution | 0/3 | Not started | - |
+| 5. Live Show Execution | 1/3 | In Progress|  |
 | 6. AI Sync | 0/3 | Not started | - |
 | 7. Microcontroller Firmware | 0/3 | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,15 +2,15 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-status: verifying
-stopped_at: Phase 5 UI-SPEC approved
-last_updated: "2026-04-07T09:07:03.684Z"
+status: executing
+stopped_at: Completed 05-live-show-execution/05-01-PLAN.md
+last_updated: "2026-04-07T10:11:59.087Z"
 last_activity: 2026-04-07
 progress:
  total_phases: 7
  completed_phases: 4
-  total_plans: 14
-  completed_plans: 14
+  total_plans: 17
+  completed_plans: 15
  percent: 0
 ---

@@ -21,13 +21,13 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-05)

 **Core value:** Load a song, build a synchronized light show, play it back live — with precise control over every effect on every device.
-**Current focus:** Phase 04 — timeline-editor
+**Current focus:** Phase 05 — live-show-execution

 ## Current Position

-Phase: 5
-Plan: Not started
-Status: Phase complete — ready for verification
+Phase: 05 (live-show-execution) — EXECUTING
+Plan: 2 of 3
+Status: Ready to execute
 Last activity: 2026-04-07

 Progress: [░░░░░░░░░░] 0%
@@ -66,6 +66,7 @@ Progress: [░░░░░░░░░░] 0%
 | Phase 04-timeline-editor P02 | 9 | 2 tasks | 6 files |
 | Phase 04-timeline-editor P03 | 2 | 1 tasks | 3 files |
 | Phase 04-timeline-editor P04 | 4min | 2 tasks | 4 files |
+| Phase 05-live-show-execution P01 | 152 | 2 tasks | 1 files |

 ## Accumulated Context

@@ -110,6 +111,8 @@ Recent decisions affecting current work:
 - [Phase 04-timeline-editor]: BeatGrid.load() normalizes API field variants: beats/beat_times and tempo/tempo_bpm — actual API returns 'beats'/'tempo' not the plan's expected field names
 - [Phase 04-timeline-editor]: UpdateParamsCommand uses currentShowId (module-level var) not this._showId — matches existing command pattern in commands.js
 - [Phase 04-timeline-editor]: Color input fires 'change' not 'input' to create command — avoids flooding command history during native color picker drag
+- [Phase 05-live-show-execution]: WebSocket cue scheduler: LOOKAHEAD=60ms inline in tick handler, is_playing gate prevents pause/seek fires, seek rebuilds fired_ids via set comprehension
+- [Phase 05-live-show-execution]: active_cue tracks already-fired blocks within duration window so preview stays lit; past-cue threshold 100ms for silent skip without UDP dispatch

 ### Pending Todos

@@ -123,8 +126,8 @@ None yet.

 ## Session Continuity

-Last session: 2026-04-07T09:07:03.676Z
-Stopped at: Phase 5 UI-SPEC approved
-Resume file: .planning/phases/05-live-show-execution/05-UI-SPEC.md
+Last session: 2026-04-07T10:11:59.079Z
+Stopped at: Completed 05-live-show-execution/05-01-PLAN.md
+Resume file: None

 Next action: `/gsd:plan-phase 1`
--- a/.planning/phases/05-live-show-execution/05-01-SUMMARY.md
+++ b/.planning/phases/05-live-show-execution/05-01-SUMMARY.md
@@ -0,0 +1,110 @@
+---
+phase: 05-live-show-execution
+plan: 01
+subsystem: api
+tags: [websocket, udp, cue-scheduler, animation, fastapi, lightsync]
+
+# Dependency graph
+requires:
+  - phase: 04-timeline-editor
+    provides: Show model with tracks/cues and encode_animation_cmd UDP encoder
+
+provides:
+  - Server-side cue scheduler in websocket tick handler that fires UDP animation commands at correct timestamps
+  - Per-connection show state (show, fired_ids, is_playing) scoped to each WebSocket connection
+  - preview_update broadcast messages sent to all clients on each tick
+  - Seek-safe fired_ids rebuild preventing double-fire or missed cues after seeking
+
+affects:
+  - 05-02 (live preview UI consumes preview_update messages)
+  - 05-03 (keyboard shortcuts drive play/pause/seek which gates cue scheduler)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Per-connection mutable state pattern for WebSocket handlers (show, fired_ids, is_playing)
+    - 60ms LOOKAHEAD window for cue scheduling with fire-and-forget UDP dispatch
+    - Seek-safe fired_ids set comprehension rebuild from show cues before seek position
+    - active_cue tracking per track for preview state (not just newly-fired cues)
+    - Batch preview_update broadcast after each tick's cue scheduling pass
+
+key-files:
+  created: []
+  modified:
+    - lightsync/api/ws.py
+
+key-decisions:
+  - "LOOKAHEAD = 0.060 (60ms) defined inline per tick — not a module constant — matches D-02 spec"
+  - "is_playing gate on cue scheduler prevents any cue firing during pause or seek drag"
+  - "Past cues (>100ms behind position) silently marked fired without UDP dispatch — prevents late blasts on seek"
+  - "active_cue tracking includes already-fired cues still within their duration window — preview stays lit for duration of block"
+  - "import lightsync.main as _main inside load handler — deferred import avoids circular import at module level"
+
+patterns-established:
+  - "Pattern: Per-connection WebSocket state — mutable variables scoped inside async handler function"
+  - "Pattern: Seek rebuild — set comprehension over all tracks/cues to mark past cues fired"
+  - "Pattern: Preview batching — collect preview_updates list then broadcast after cue loop"
+
+requirements-completed:
+  - SHW-03
+
+# Metrics
+duration: 8min
+completed: 2026-04-07
+---
+
+# Phase 5 Plan 01: Live Show Execution — Cue Scheduler Summary
+
+**WebSocket tick handler extended with 60ms look-ahead cue scheduler that fires UDP animation commands at exact timestamps, with seek-safe fired_ids rebuild and preview_update broadcast on every tick**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-04-07T10:09:19Z
+- **Completed:** 2026-04-07T10:17:00Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- Per-connection show state (show, fired_ids, is_playing) integrated into WebSocket handler
+- Load message extended to load show from show_store by show_id, resetting scheduler state
+- Play/pause handlers gate is_playing flag (pause never touches fired_ids per spec)
+- Seek handler rebuilds fired_ids via set comprehension over all cues before seek position
+- 60ms LOOKAHEAD cue scheduler fires UDP animation commands during active playback
+- Past cues (>100ms behind) silently skipped — no late UDP bursts after seek
+- active_cue tracking covers both newly-fired and already-active cues for preview continuity
+- preview_update messages broadcast to all connected clients on each tick tick (active and clear states)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add per-connection show state and load handler to ws.py** - `3d36cc5` (feat)
+2. **Task 2: Add cue scheduling loop and preview_update broadcast to tick handler** - `64c49c9` (feat)
+
+## Files Created/Modified
+- `lightsync/api/ws.py` - Extended with cue scheduler, show loading, play/pause/seek handlers, preview_update broadcast
+
+## Decisions Made
+- `LOOKAHEAD = 0.060` defined inline inside the tick branch (not as module constant) — keeps it local to the scheduler logic
+- Deferred import of `lightsync.main as _main` inside the load handler body to avoid circular import at module level
+- `active_cue` tracks already-fired cues still within their duration window so preview stays lit for the full block duration, not just at fire time
+- Past-cue threshold set at 100ms (not 60ms) to give a small recovery window without causing stale fires
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None. The Python runtime was invoked via `uv run python` (no `python`/`python3` on PATH in this environment).
+
+## Next Phase Readiness
+- WebSocket cue scheduler is fully functional — ready for 05-02 (live preview UI consuming preview_update messages)
+- preview_update messages broadcast device_id, animation name, and color on each tick — frontend can render device state
+- Seek and pause behavior are correct per spec — no double-fire, no late blasts
+
+---
+*Phase: 05-live-show-execution*
+*Completed: 2026-04-07*