---
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*