docs(02-02): complete audio engine plan 02 — WebSocket broadcast + REST audio endpoints
- SUMMARY: WebSocket hub wired to broadcast MPV position at 10Hz, command dispatch - STATE: plan advanced to 3/3, progress 86%, decisions added - ROADMAP: phase 2 progress updated (2/3 summaries) - REQUIREMENTS: AUD-02, AUD-04 marked complete
This commit is contained in:
Claude
108
.planning/phases/02-audio-engine/02-02-SUMMARY.md
Normal file
108
.planning/phases/02-audio-engine/02-02-SUMMARY.md
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
phase: 02-audio-engine
|
||||
plan: "02"
|
||||
subsystem: api
|
||||
tags: [websocket, fastapi, mpv, asyncio, audio, rest]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 02-audio-engine/02-01
|
||||
provides: MPVEngine with get_state/play/pause/seek/load/stop, module-level engine in main.py
|
||||
provides:
|
||||
- broadcast_loop sending position ticks at 10Hz over WebSocket
|
||||
- WebSocket command dispatch (play/pause/seek/load) to MPVEngine
|
||||
- REST POST /api/audio/load with file validation
|
||||
- REST GET /api/audio/state returning current playback state
|
||||
affects: [03-waveform, 04-editor, 05-timeline, frontend-transport-ui]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "broadcast_loop uses get_engine callable to avoid circular import at module level"
|
||||
- "asyncio.to_thread for blocking engine calls in async endpoints"
|
||||
- "asyncio.create_task in lifespan for background loops with cancel on shutdown"
|
||||
- "request.app.state.engine pattern for engine access in REST endpoints"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- lightsync/api/audio.py
|
||||
modified:
|
||||
- lightsync/api/ws.py
|
||||
- lightsync/main.py
|
||||
|
||||
key-decisions:
|
||||
- "broadcast_loop accepts get_engine callable instead of direct engine import — avoids circular import between ws.py and main.py"
|
||||
- "asyncio.to_thread for engine.load in REST endpoint — engine.load is synchronous (python-mpv-jsonipc), must not block event loop"
|
||||
- "AUD-02 (YouTube URL loading) noted as Phase 6 deferral — not in scope for this plan"
|
||||
|
||||
patterns-established:
|
||||
- "Background loop pattern: asyncio.create_task in lifespan, cancel + await in shutdown"
|
||||
- "Engine access in REST: request.app.state.engine (not module-level import)"
|
||||
- "Engine access in WebSocket: deferred import from lightsync.main inside handler"
|
||||
|
||||
requirements-completed: [AUD-02, AUD-04]
|
||||
|
||||
# Metrics
|
||||
duration: 8min
|
||||
completed: 2026-04-06
|
||||
---
|
||||
|
||||
# Phase 02 Plan 02: Audio Engine WebSocket + REST Summary
|
||||
|
||||
**WebSocket hub broadcasting MPV position at 10Hz and dispatching play/pause/seek/load commands; REST /api/audio/load with extension and existence validation**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 8 min
|
||||
- **Started:** 2026-04-06T13:10:00Z
|
||||
- **Completed:** 2026-04-06T13:18:00Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 3
|
||||
|
||||
## Accomplishments
|
||||
- Replaced WebSocket echo stub with full transport command dispatch (play/pause/seek/load) to MPVEngine
|
||||
- Added `broadcast_loop` sending `{type: "tick", position, paused, duration, loaded, file}` at 10Hz
|
||||
- Wired broadcast_loop as asyncio task in lifespan, properly cancelled on shutdown
|
||||
- Created `lightsync/api/audio.py` with POST /load (validates path + extension) and GET /state
|
||||
- Registered audio router at `/api/audio` prefix before static file catch-all in main.py
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Wire WebSocket broadcast loop and command dispatch** - `5e400a6` (feat)
|
||||
2. **Task 2: Add REST audio load endpoint with file validation** - `de45540` (feat)
|
||||
|
||||
**Plan metadata:** _(to be committed)_
|
||||
|
||||
## Files Created/Modified
|
||||
- `lightsync/api/ws.py` - broadcast_loop function; full command dispatch replacing echo stub
|
||||
- `lightsync/main.py` - asyncio.create_task(broadcast_loop) in lifespan; audio router registration
|
||||
- `lightsync/api/audio.py` - REST POST /load with file/extension validation; GET /state
|
||||
|
||||
## Decisions Made
|
||||
- `broadcast_loop` accepts `get_engine: callable` instead of importing engine directly — avoids circular import (ws.py would import main.py which imports ws.py)
|
||||
- `asyncio.to_thread` wraps `engine.load()` in the REST endpoint since python-mpv-jsonipc's load is synchronous and would block the event loop
|
||||
- AUD-02 (YouTube URL loading) deferred to Phase 6 — noted in docstring, not implemented
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None. The get_engine callable pattern from the plan cleanly prevented the circular import issue that would otherwise occur if ws.py imported `engine` from main.py at module level.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- WebSocket + audio REST layer complete; browser can now receive real-time position ticks and send transport commands
|
||||
- Phase 02-03 (waveform analysis) can proceed: `GET /api/audio/state` provides current file path; waveform endpoint can use that as input
|
||||
- No blockers
|
||||
|
||||
---
|
||||
*Phase: 02-audio-engine*
|
||||
*Completed: 2026-04-06*
|
||||
Reference in New Issue
Block a user