dc-recorder/docs/superpowers/specs/2026-05-15-media-music-phase-1-design.md

# Media Music Phase 1 Design

## Goal

Add a first media playback phase focused on play music: users can queue, play, skip, and stop audio sources from the dashboard while preserving the existing Discord voice recorder, browser microphone transmit, and moderation capture flows.

## Scope

Phase 1 implements audio-only playback and queue control. Share screen/video streaming is intentionally reserved for phase 2, but the controller shape should leave room for a later `screen` mode using the already vendored `@dank074/discord-video-stream` APIs seen in `MythEclipse/StreamBot`.

## Recommended Architecture

Create a small media subsystem under `src/media/`:

- `mediaTypes.ts` defines `MediaMode`, `MediaQueueItem`, `MediaState`, and request/response types.
- `mediaQueue.ts` owns in-memory queue operations: add, current, next, remove current, clear, snapshot.
- `mediaResolver.ts` resolves initial supported sources. Phase 1 should support direct HTTP(S) URLs and local file paths. YouTube/search can be added later because it requires adding or wrapping yt-dlp behavior.
- `musicPlayer.ts` converts a media source to Ogg Opus using ffmpeg and feeds the existing `discordPlayer.playStream()`.
- `mediaController.ts` coordinates queue state, voice connection assumptions, play/skip/stop, and WebSocket broadcast state.

The existing `VoiceController` remains the owner of joining/leaving voice channels. Phase 1 does not create a second voice connection path. Music playback requires the bot to already be connected through the existing voice UI or `/api/connect`; otherwise the media route returns `409 VOICE_NOT_CONNECTED`.

## Data Flow

1. Browser submits a source to `/api/media/queue` with `{ source }`.
2. `mediaResolver` validates and resolves the source into `{ source, title, kind }`.
3. `mediaQueue` appends a `MediaQueueItem`.
4. If no item is playing, `mediaController` starts playback of the current queue item.
5. `musicPlayer` spawns ffmpeg and outputs Ogg Opus to `discordPlayer.playStream()`.
6. When playback finishes, the controller removes the completed item and starts the next item.
7. State changes broadcast over the existing moderation broadcaster as a JSON WebSocket event, or via a small media broadcaster wrapper if that keeps types cleaner.

## API Design

Add `src/routes/mediaRoutes.ts` mounted under `/api`:

- `GET /api/media/status` returns `{ playing, current, queue }`.
- `POST /api/media/queue` accepts `{ source: string }`, queues it, and returns the updated state.
- `POST /api/media/skip` skips current item and starts the next if present.
- `POST /api/media/stop` stops playback and clears the queue.

All routes should use `AppError` for boundary validation. Empty source returns `400 MISSING_MEDIA_SOURCE`. No voice connection returns `409 VOICE_NOT_CONNECTED`.

## Dashboard Design

Add a compact Media card to the existing voice tab for phase 1:

- Source input: URL or local path.
- Buttons: Queue/Play, Skip, Stop.
- Current item label and queue list.

Do not add a separate full media tab yet. The voice tab already owns voice channel selection and connection state, so colocating music controls there reduces user confusion.

## Playback Details

Use ffmpeg directly or the existing `src/audio/ffmpegProcess.ts` helper if it already fits. The target stream should be Ogg Opus because `DiscordPlayer.playStream()` currently expects `StreamType.OggOpus`.

Recommended ffmpeg output shape:

- Input: local file or HTTP(S) URL.
- Output format: `ogg`.
- Audio codec: `libopus`.
- Sample rate: `48000`.
- Channels: `2`.

The controller owns an `AbortController` or child process handle so skip/stop can terminate ffmpeg. Stop must also call `discordPlayer.stop()` so the audio player releases the current resource.

## Concurrency Rules

- Only one media item plays at a time.
- Browser microphone transmit and music playback both use `discordPlayer`; phase 1 should disable music start while `isStreaming` is true, or stop browser transmit before playback. Prefer returning `409 BROWSER_STREAM_ACTIVE` to avoid surprising the user.
- Voice recording can continue while music plays because recording uses the receiver pipeline and music uses the player pipeline.
- Skip is serialized: concurrent skip calls should return the same resulting state or reject with `409 MEDIA_SKIP_IN_PROGRESS`.

## Error Handling

- Unsupported source format: `400 UNSUPPORTED_MEDIA_SOURCE`.
- ffmpeg spawn failure: current item becomes failed, playback advances to the next queued item if present.
- ffmpeg runtime failure: log stderr summary, mark item failed, advance queue.
- Stop is idempotent: stopping while idle returns current idle state.

## Tests

Unit tests should cover:

- Queue add/next/remove/clear behavior.
- Resolver accepts HTTP(S) URLs and existing local paths, rejects empty/unsupported input.
- Controller rejects playback when voice is not connected.
- Controller starts next item after completion.
- Skip aborts current playback and advances queue.
- Routes validate payloads and call controller methods.

Manual verification should cover:

- Connect to a voice channel, queue a short audio URL or local file, hear playback in Discord.
- Queue two items, confirm automatic advance.
- Skip moves to the next item.
- Stop clears playback and queue.
- Existing voice recording and text moderation still work after media playback.

## Phase 2 Compatibility

Phase 2 can add `MediaMode = "screen"` and a `screenSharePlayer.ts` using StreamBot's pattern:

- `new Streamer(client)`
- `streamer.joinVoice(guildId, channelId)` only if phase 2 decides to own its own connection path
- `prepareStream(source, videoOptions, signal)`
- `playStream(output, streamer, { type: "go-live" }, signal)`

Phase 1 should not instantiate `Streamer`; it should only reserve type and controller seams so adding screen share later does not rewrite queue/status APIs.