3de7f43b3f
- 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
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
---
|
|
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*
|