14 KiB
phase, verified, status, score, gaps, human_verification
| phase | verified | status | score | gaps | human_verification | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 05-live-show-execution | 2026-04-07T00:00:00Z | gaps_found | 9/11 must-haves verified |
|
|
Phase 5: Live Show Execution — Verification Report
Phase Goal: A complete show runs end-to-end — audio plays, cues fire at correct timestamps via UDP, live preview updates in the browser, and the show persists across sessions
Verified: 2026-04-07 Status: gaps_found Re-verification: No — initial verification
Goal Achievement
Observable Truths
| # | Truth | Status | Evidence |
|---|---|---|---|
| 1 | Server fires UDP animation commands when audio position reaches a cue timestamp | PARTIAL | Cue scheduler is fully implemented in ws.py with correct LOOKAHEAD=0.060, udp.send, encode_animation_cmd wiring — but the scheduler gate (is_playing) is never set to True from mouse-based play button clicks, only from Space key |
| 2 | Seeking resets the cue pointer so past cues are marked fired and future cues re-arm | VERIFIED | ws.py:207-214: fired_ids rebuilt as set comprehension on seek, marking all cues before position-0.060 as fired |
| 3 | Loading a show via WebSocket populates per-connection cue list from show_store | VERIFIED | ws.py:232-242: load handler imports lightsync.main, calls _main.show_store.load(show_id), assigns to per-connection show variable |
| 4 | Cues within 60ms ahead of tick position fire immediately (never late) | VERIFIED | ws.py:134: LOOKAHEAD = 0.060; ws.py:155: fires cues where timestamp <= position + LOOKAHEAD |
| 5 | Pausing does not add cues to fired_ids; cues only fire during active playback | PARTIAL | Server-side pause handler is correct (is_playing=False, fired_ids untouched) — but pause WS message only sent from keyboard shortcut, not play button |
| 6 | Live preview panel shows active animation color and type per device, updated in sync with playback | VERIFIED | app.js:77-92: updatePreviewStrip updates strip DOM on preview_update WS messages; ws.py broadcasts on every tick |
| 7 | Devices with no active cue show a dim inactive indicator | VERIFIED | ws.py:181-188: sends preview_update with animation:null, color:null for inactive tracks; app.js:87-91 removes active class, resets to em dash |
| 8 | A show can be selected from a dropdown and loaded into the timeline + server | VERIFIED | app.js:496-567: refreshShows() populates #show-select from /api/shows; btn-load-show handler fetches full show, populates timeline tracks, calls client.send({type:'load', show_id}) |
| 9 | Space bar toggles play/pause without triggering button clicks or scrolling | VERIFIED | app.js:188-197: Space handler checks tag !== 'button', calls e.preventDefault(), toggles audio.play()/pause(), sends WS play/pause |
| 10 | Arrow keys seek audio forward/backward by 5 seconds and send seek message to server | VERIFIED | app.js:198-223: ArrowLeft/Right set audio.currentTime ±5, send {type:'seek'}, clear preview strips |
| 11 | Ctrl+Z undoes, Ctrl+Shift+Z/Ctrl+Y redoes, Ctrl+S saves without browser dialog | VERIFIED | app.js:224-244: all three bindings implemented with e.preventDefault(), timeline?.history.undo()/redo(), Ctrl+S does GET+POST round-trip |
Score: 9/11 truths verified (2 partial due to same root cause)
Required Artifacts
| Artifact | Expected | Status | Details |
|---|---|---|---|
lightsync/api/ws.py |
Server-side cue scheduler in tick handler | VERIFIED | 250 lines; contains LOOKAHEAD, fired_ids, is_playing, encode_animation_cmd, udp.send, preview_update broadcast, seek rebuild, show loading |
lightsync/frontend/index.html |
live-preview div, show selector UI | VERIFIED | #live-preview between canvas and inspector; #show-select, #btn-load-show in transport bar; .keyboard-hint span present |
lightsync/frontend/style.css |
Terminal-aesthetic preview panel styles | VERIFIED | .live-preview, .device-strip, .strip-label, .strip-color, .strip-anim, .keyboard-hint all present; max-height:60px; no border-radius in new rules |
lightsync/frontend/app.js |
preview_update handler, show selector, wireKeyboard | VERIFIED | All functions present: updatePreviewStrip, buildPreviewStrips, refreshShows, wireKeyboard; all key links wired |
Key Link Verification
| From | To | Via | Status | Details |
|---|---|---|---|---|
| lightsync/api/ws.py | lightsync/protocol/animation_cmd.encode_animation_cmd | import + call in tick branch | WIRED | Line 25 top-level import; line 167 call in cue scheduler |
| lightsync/api/ws.py | lightsync/protocol/udp_sender.UDPSender.send | websocket.app.state.udp_sender.send() | WIRED | Line 135: udp = websocket.app.state.udp_sender; line 168: udp.send(payload, device.ip, device.port) |
| lightsync/api/ws.py | lightsync/main.show_store | import lightsync.main, call show_store.load() | WIRED | Line 234: import lightsync.main as _main; line 235: await _main.show_store.load(show_id) |
| lightsync/frontend/app.js | lightsync/api/ws.py | WebSocket onmessage for preview_update | WIRED | Line 53: else if (msg.type === 'preview_update') updatePreviewStrip(...) |
| lightsync/frontend/app.js | /api/shows | fetch to list and load shows | WIRED | Line 500: fetch('/api/shows'); line 524: fetch(/api/shows/${showId}) |
| lightsync/frontend/app.js | lightsync/frontend/timeline/commands.js | setCurrentShowId() call on show load | WIRED | Line 6: import {setCurrentShowId}; line 542: setCurrentShowId(showId) |
| wireKeyboard | HTML5 audio element | audio.play()/pause()/currentTime | WIRED | Lines 192, 195, 201, 214 |
| wireKeyboard | timeline.history | undo()/redo() calls | WIRED | Lines 226, 229 |
Gap in wiring (not a key_link but critical):
| From | To | Via | Status | Details |
|---|---|---|---|---|
| wireAudio btn-play click | lightsync/api/ws.py is_playing | client.send({type:'play'}) | NOT WIRED | wireAudio plays/pauses audio but does not notify server; server is_playing stays False on mouse play |
Data-Flow Trace (Level 4)
| Artifact | Data Variable | Source | Produces Real Data | Status |
|---|---|---|---|---|
| app.js updatePreviewStrip | animation, color | preview_update WS message from ws.py tick handler | Yes — driven by actual cue data from show_store | FLOWING (when is_playing is True) |
| app.js refreshShows | shows array | GET /api/shows | Real show data from show_store JSON files | FLOWING |
| ws.py cue scheduler | show.tracks, cue.timestamp | show_store.load(show_id) from JSON persistence | Real data from saved show file | FLOWING |
| app.js buildPreviewStrips | devices | GET /api/devices | Real device registry | FLOWING |
Behavioral Spot-Checks
| Behavior | Command | Result | Status |
|---|---|---|---|
| ws.py parses without syntax errors | ast.parse(open('lightsync/api/ws.py').read()) | Syntax: OK | PASS |
| LOOKAHEAD constant present | grep -c 'LOOKAHEAD = 0.060' ws.py | 1 | PASS |
| preview_update appears in ws.py | grep -c 'preview_update' ws.py | 3 | PASS |
| fired_ids appears 4+ times | grep -c 'fired_ids' ws.py | 6 | PASS |
| is_playing assignments present | grep 'is_playing' ws.py | True + False assignments and gate | PASS |
| wireKeyboard wired | grep 'wireKeyboard()' app.js | Called at line 351 | PASS |
| setCurrentShowId exported | grep 'export function setCurrentShowId' commands.js | Line 7 | PASS |
| play/pause WS from btn-play | grep events in wireAudio btn click | audio.play()/pause() only — no client.send | FAIL |
Requirements Coverage
| Requirement | Source Plan | Description | Status | Evidence |
|---|---|---|---|---|
| SHW-03 | 05-01, 05-02 | Live show execution — follow MPV position, dispatch animation commands to devices via UDP at correct timestamps | PARTIAL | Scheduler implemented and correct, but only armed via keyboard Space — mouse play button does not send play message to server |
| UI-03 | 05-03 | All primary operations accessible without mouse (keyboard shortcuts for play/pause/seek/undo) | VERIFIED | wireKeyboard() wires all 7 shortcuts with correct guards and preventDefault |
| UI-04 | 05-02 | Live preview panel — simulated LED strip visualization in browser canvas, synced to playback | VERIFIED | DOM strips, CSS styles, preview_update handler, and preview broadcast all present and wired |
Note on REQUIREMENTS.md traceability: The traceability table maps SHW-03 and UI-03 to Phase 5; UI-04 is mapped to "Phases 1-5 (progressive)". All three IDs appear across the three plan frontmatters — no orphaned requirements.
Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|---|---|---|---|---|
| app.js | 130-133 | btn-play click sends no WS play/pause message | BLOCKER | Mouse playback leaves server is_playing=False; cue scheduler never fires UDP when using the transport button |
The HTML placeholder attributes in form fields (lines 32, 38-40 of index.html) are form hint text, not code stubs — not flagged.
Human Verification Required
1. Mouse-Based Playback (blocked pending gap fix)
Test: Load a show using the show selector, then click the transport bar play button (not Space) Expected: Animation blocks should trigger UDP commands and the LED simulator/devices should respond Why human: Requires running server + loaded show + observing UDP traffic
2. Live Preview Strip Updates
Test: Load a show with at least one device and animation block, press Space to play Expected: Device strips in the preview panel light up with animation name and color; strips dim between blocks Why human: Visual DOM state — requires live WebSocket + audio playback
3. Seek + Reschedule
Test: Play a show to the middle, drag the seek bar to an earlier position, continue playing Expected: Cues already passed are not re-fired; cues after seek position fire correctly Why human: Real-time timing behavior requires live playback
4. Ctrl+S Save
Test: Load a show, make a change (drag a block), press Ctrl+S Expected: No browser save dialog; console shows "[save] show saved via Ctrl+S"; reloading the show reflects the change Why human: Round-trip persistence requires live app + file system check
Gaps Summary
One root cause accounts for both failing truths: the transport bar play/pause button (#btn-play) in wireAudio() calls audio.play() and audio.pause() directly but does not notify the server via WebSocket. The server-side is_playing flag therefore stays False for mouse-based playback. The entire cue scheduler is gated on is_playing and show is not None — meaning UDP cues never fire when the user clicks the button.
The keyboard Space shortcut in wireKeyboard() correctly sends { type: 'play' } and { type: 'pause' } to the server. All server-side logic is correct. The fix is minimal: move or duplicate the WS send calls into the audio.addEventListener('play', ...) and audio.addEventListener('pause', ...) event listeners in wireAudio(), which fire regardless of whether play/pause was triggered by keyboard or mouse.
All other Phase 5 deliverables are fully implemented: seek-safe cue scheduling, show loading, live preview panel, show selector, and all 7 keyboard shortcuts with proper guards.
Verified: 2026-04-07 Verifier: Claude (gsd-verifier)