feat: implement media echo fix and YouTube screenshare design

- Introduced a new `ScreenShareController` to manage YouTube screenshare functionality.
- Updated `DiscordPlayer` to track ownership of audio streams, preventing conflicts between music playback and screenshare.
- Added error handling for various states including voice connection checks and media busy states.
- Created unit tests for `ScreenShareController` and `DiscordPlayer` ownership rules to ensure correct functionality.
- Added documentation for the new media echo fix and screenshare design.

docs/superpowers/specs/2026-05-16-media-echo-screenshare-design.md

@@ -0,0 +1,71 @@
+# Media Echo Fix and YouTube Screenshare Design
+
+## Context
+
+Media playback currently uses the same `DiscordPlayer` instance as the browser audio bridge. The browser bridge is started during webserver startup and subscribes the shared player to the active voice connection. Music playback also uses that player. This shared ownership can let the bridge interfere with media playback and contribute to voice audio being reflected back during playback.
+
+The project already includes `@dank074/discord-video-stream`, which supports Discord Go Live video streaming from a direct media URL or readable stream.
+
+## Goals
+
+- Prevent voice audio from being reflected back while music/media playback is active.
+- Keep normal music playback behavior for existing `/api/media/queue` users.
+- Add a YouTube screenshare path that streams video through Discord Go Live.
+- Fail clearly when voice is not connected, another media mode is busy, or screenshare dependencies fail.
+
+## Non-goals
+
+- Replace the existing voice recorder pipeline.
+- Disable message or voice monitoring during music playback.
+- Build full production UI for screenshare controls in the first implementation.
+- Add Discord integration tests that require a live account or server.
+
+## Design
+
+### Audio player ownership
+
+`DiscordPlayer` will track which subsystem owns the active stream: `none`, `browser-bridge`, `music`, or `screen`. A caller may only start playback when the player has no owner or when the caller owns the current stream. This prevents the browser bridge from overwriting music or screen playback.
+
+The browser bridge in `src/webserver.ts` will not start at server boot. It will be created lazily only when browser audio arrives and no media playback is active. When media playback starts, the bridge is stopped or left inactive so it cannot transmit captured audio back into Discord.
+
+Music playback will claim the `music` owner before calling `playStream`. When music finishes or stops, ownership is released and browser audio may resume later if the browser sends new audio.
+
+### Screenshare mode
+
+The media queue endpoint will accept an optional `mode` field. If omitted, mode defaults to `music` to preserve existing API behavior. `mode: "screen"` starts a separate screenshare flow instead of audio-only music playback.
+
+A new `ScreenShareController` will:
+
+1. Verify a voice channel is connected.
+2. Reject start if music or browser bridge owns playback, or if another screen stream is active.
+3. Resolve a YouTube URL to a direct playable video URL through the existing yt-dlp utilities.
+4. Use `@dank074/discord-video-stream` with `prepareStream(...)` and `playStream(..., { type: "go-live" })`.
+5. Track active screen state and provide stop behavior.
+
+Screenshare state will be exposed through media state as the active mode so the frontend can distinguish music from screen playback.
+
+### Busy-state rules
+
+- Music cannot start while screen is active.
+- Screen cannot start while music is active.
+- Browser bridge cannot start while music or screen is active.
+- Stop stops the active media mode and releases ownership.
+
+### Error handling
+
+- `VOICE_NOT_CONNECTED`: media or screen requested before joining voice.
+- `MEDIA_BUSY`: another active media mode owns playback.
+- `SCREEN_STREAM_FAILED`: yt-dlp, stream preparation, or Go Live playback fails.
+
+Errors should surface through existing Express error handling as JSON responses.
+
+## Testing
+
+- Unit test `DiscordPlayer` ownership rules: browser bridge cannot override music; music releases ownership on stop.
+- Media controller tests: default mode remains music, screen mode is routed separately, and busy conflicts reject with `MEDIA_BUSY`.
+- Route tests: `/api/media/queue` accepts optional `mode` and passes it to the controller.
+- Screenshare controller tests mock yt-dlp and `@dank074/discord-video-stream`; no live Discord account is required.
+
+## Rollout
+
+Implement ownership first and verify existing music tests still pass. Then add mode parsing and the screenshare controller behind the same media route. UI changes can follow as a small enhancement after API behavior is stable.

src/media/mediaController.ts

@@ -3,10 +3,14 @@ import { discordPlayer } from "../player";
 import { MediaQueue } from "./mediaQueue";
 import { resolveMediaSource } from "./mediaResolver";
 import type {
+  MediaMode,
   MediaState,
   MusicPlayback,
   MusicPlayer,
+  QueueMediaOptions,
   ResolvedMediaSource,
+  ScreenShareController,
+  ScreenSharePlayback,
 } from "./mediaTypes";
 import { createMusicPlayer } from "./musicPlayer";
 
@@ -15,6 +19,7 @@ export interface MediaControllerDependencies {
   isBrowserStreaming?: () => boolean;
   resolveMediaSource?: (source: string) => Promise<ResolvedMediaSource>;
   musicPlayer?: MusicPlayer;
+  screenController?: ScreenShareController;
   onStateChange?: (state: MediaState) => void;
 }
 
@@ -24,6 +29,8 @@ export class MediaController {
   private playback: MusicPlayback | null = null;
   private playbackToken = 0;
   private skipInProgress = false;
+  private screenPlayback: ScreenSharePlayback | null = null;
+  private activeMode: MediaMode | null = null;
 
   constructor(private readonly dependencies: MediaControllerDependencies = {}) {
     this.musicPlayer = dependencies.musicPlayer ?? createMusicPlayer();
@@ -32,17 +39,27 @@ export class MediaController {
   getState(): MediaState {
     const snapshot = this.queueStore.snapshot();
     return {
-      playing: snapshot.current?.status === "playing",
+      playing:
+        this.activeMode === "screen" || snapshot.current?.status === "playing",
+      activeMode: this.activeMode ?? snapshot.current?.mode ?? null,
       ...snapshot,
     };
   }
 
-  async queue(source: string): Promise<MediaState> {
+  async queue(
-    this.assertCanStart();
+    source: string,
+    options: QueueMediaOptions = {},
+  ): Promise<MediaState> {
+    const mode = options.mode ?? "music";
+    if (mode === "screen") {
+      return this.startScreen(source);
+    }
+
+    this.assertCanStartMusic();
     const resolved = await (
       this.dependencies.resolveMediaSource ?? resolveMediaSource
     )(source);
-    this.queueStore.add(resolved);
+    this.queueStore.add(resolved, mode, options.requestedBy);
     this.startNextIfIdle();
     return this.emitState();
   }
@@ -73,11 +90,14 @@ export class MediaController {
     this.playbackToken++;
     this.playback?.stop();
     this.playback = null;
+    this.screenPlayback?.stop();
+    this.screenPlayback = null;
+    this.activeMode = null;
     this.queueStore.clear();
     return this.emitState();
   }
 
-  private assertCanStart(): void {
+  private assertCanStartMusic(): void {
     const isVoiceConnected =
       this.dependencies.isVoiceConnected ?? (() => discordPlayer.isConnected());
     if (!isVoiceConnected()) {
@@ -88,6 +108,10 @@ export class MediaController {
       );
     }
 
+    if (this.screenPlayback || this.dependencies.screenController?.isActive()) {
+      throw new AppError("Another media mode is active", "MEDIA_BUSY", 409);
+    }
+
     if (this.dependencies.isBrowserStreaming?.()) {
       throw new AppError(
         "Stop browser microphone streaming before playing media",
@@ -97,6 +121,46 @@ export class MediaController {
     }
   }
 
+  private async startScreen(source: string): Promise<MediaState> {
+    if (
+      this.screenPlayback ||
+      this.dependencies.screenController?.isActive() ||
+      this.playback ||
+      this.queueStore.snapshot().current
+    ) {
+      throw new AppError("Another media mode is active", "MEDIA_BUSY", 409);
+    }
+    const screenController = this.dependencies.screenController;
+    if (!screenController) {
+      throw new AppError(
+        "Screen sharing is unavailable",
+        "SCREEN_UNAVAILABLE",
+        500,
+      );
+    }
+
+    this.activeMode = "screen";
+    try {
+      this.screenPlayback = await screenController.start(source);
+    } catch (error) {
+      this.activeMode = null;
+      throw error;
+    }
+
+    this.screenPlayback.done.then(
+      () => this.finishScreen(),
+      () => this.finishScreen(),
+    );
+    return this.emitState();
+  }
+
+  private finishScreen(): void {
+    if (!this.screenPlayback || this.activeMode !== "screen") return;
+    this.screenPlayback = null;
+    this.activeMode = null;
+    this.emitState();
+  }
+
   private startNextIfIdle(): void {
     if (this.playback) return;
     const item = this.queueStore.startNext();

src/media/mediaQueue.ts

@@ -1,4 +1,5 @@
 import type {
+  MediaMode,
   MediaQueueItem,
   MediaState,
   ResolvedMediaSource,
@@ -13,10 +14,14 @@ export class MediaQueue {
     private readonly now = () => Date.now(),
   ) {}
 
-  add(source: ResolvedMediaSource, requestedBy = "dashboard"): MediaQueueItem {
+  add(
+    source: ResolvedMediaSource,
+    mode: MediaQueueItem["mode"] = "music",
+    requestedBy = "dashboard",
+  ): MediaQueueItem {
     const item: MediaQueueItem = {
       id: this.createId(),
-      mode: "music",
+      mode,
       requestedBy,
       addedAt: this.now(),
       status: "queued",

src/media/mediaTypes.ts

@@ -25,10 +25,16 @@ export interface MediaQueueItem extends ResolvedMediaSource {
 
 export interface MediaState {
   playing: boolean;
+  activeMode: MediaMode | null;
   current: MediaQueueItem | null;
   queue: MediaQueueItem[];
 }
 
+export interface QueueMediaOptions {
+  mode?: MediaMode;
+  requestedBy?: string;
+}
+
 export interface MusicPlayback {
   done: Promise<void>;
   stop(): void;
@@ -38,8 +44,23 @@ export interface MusicPlayer {
   play(source: ResolvedMediaSource): MusicPlayback;
 }
 
-export interface DiscordAudioPlayer {
+export interface ScreenSharePlayback {
-  isConnected(): boolean;
+  done: Promise<void>;
-  playStream(stream: Readable): void;
   stop(): void;
 }
+
+export interface ScreenShareController {
+  isActive(): boolean;
+  start(source: string): Promise<ScreenSharePlayback>;
+}
+
+export type DiscordPlayerOwner = "none" | "browser-bridge" | "music" | "screen";
+
+export interface DiscordAudioPlayer {
+  getOwner(): DiscordPlayerOwner;
+  isConnected(): boolean;
+  playStream(stream: Readable, owner: DiscordPlayerOwner): void;
+  pause(owner?: DiscordPlayerOwner): void;
+  unpause(owner?: DiscordPlayerOwner): boolean;
+  stop(owner?: DiscordPlayerOwner): void;
+}

src/media/musicPlayer.ts

@@ -30,13 +30,27 @@ export function createMusicPlayer(
       }) as unknown as ChildProcessWithoutNullStreams;
       proc.stderr.resume();
 
-      audioPlayer.playStream(proc.stdout);
+      audioPlayer.playStream(proc.stdout, "music");
 
       let stopped = false;
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        audioPlayer.stop("music");
+      };
+
       const done = new Promise<void>((resolve, reject) => {
-        proc.on("error", reject);
+        proc.on("error", (error) => {
-        proc.stdout.on("error", reject);
+          release();
+          reject(error);
+        });
+        proc.stdout.on("error", (error) => {
+          release();
+          reject(error);
+        });
         proc.on("close", (code) => {
+          release();
           if (code === 0 || stopped) {
             resolve();
             return;
@@ -51,7 +65,7 @@ export function createMusicPlayer(
           if (stopped) return;
           stopped = true;
           proc.kill("SIGTERM");
-          audioPlayer.stop();
+          release();
         },
       };
     },

src/media/screenShareController.ts

@@ -0,0 +1,123 @@
+import type { Readable } from "node:stream";
+import {
+  playStream as defaultPlayStream,
+  prepareStream as defaultPrepareStream,
+  Encoders,
+  Utils,
+} from "@dank074/discord-video-stream";
+import { AppError } from "../errors";
+import { discordPlayer } from "../player";
+import type { DiscordPlayerOwner, ScreenSharePlayback } from "./mediaTypes";
+import { createYtDlp } from "./ytdlp";
+
+export interface ScreenShareVoiceStatus {
+  connected: boolean;
+  activeGuildId: string | null;
+  activeChannelId: string | null;
+}
+
+interface PreparedScreenStream {
+  command: { kill?: (signal: NodeJS.Signals) => unknown };
+  output: Readable;
+}
+
+type PrepareScreenStream = (
+  source: string,
+  options: object,
+) => PreparedScreenStream;
+
+type PlayScreenStream = (
+  output: Readable,
+  streamer: unknown,
+  options: { type: "go-live" },
+) => Promise<void>;
+
+export interface ScreenShareControllerDependencies {
+  getVoiceStatus: () => ScreenShareVoiceStatus;
+  getPlayerOwner?: () => DiscordPlayerOwner;
+  getDirectVideoUrl?: (source: string) => Promise<string>;
+  prepareStream?: PrepareScreenStream;
+  playStream?: PlayScreenStream;
+  streamer: unknown;
+}
+
+export function createScreenShareController(
+  dependencies: ScreenShareControllerDependencies,
+) {
+  let active: ScreenSharePlayback | null = null;
+  const ytdlp = createYtDlp();
+  const getPlayerOwner =
+    dependencies.getPlayerOwner ?? (() => discordPlayer.getOwner());
+  const getDirectVideoUrl =
+    dependencies.getDirectVideoUrl ??
+    ((source) => ytdlp.getDirectVideoUrl(source));
+  const prepareStream =
+    dependencies.prepareStream ??
+    (defaultPrepareStream as unknown as PrepareScreenStream);
+  const playStream =
+    dependencies.playStream ??
+    (defaultPlayStream as unknown as PlayScreenStream);
+
+  return {
+    isActive(): boolean {
+      return active !== null;
+    },
+
+    async start(source: string): Promise<ScreenSharePlayback> {
+      const status = dependencies.getVoiceStatus();
+      if (
+        !status.connected ||
+        !status.activeGuildId ||
+        !status.activeChannelId
+      ) {
+        throw new AppError(
+          "Connect to a voice channel before sharing screen",
+          "VOICE_NOT_CONNECTED",
+          409,
+        );
+      }
+
+      if (active || getPlayerOwner() !== "none") {
+        throw new AppError("Another media mode is active", "MEDIA_BUSY", 409);
+      }
+
+      try {
+        const directUrl = await getDirectVideoUrl(source);
+        const { command, output } = prepareStream(directUrl, {
+          encoder: Encoders.software({ x264: { preset: "superfast" } }),
+          height: 720,
+          frameRate: 30,
+          bitrateVideo: 2500,
+          bitrateVideoMax: 4000,
+          includeAudio: true,
+          videoCodec: Utils.normalizeVideoCodec("H264"),
+        });
+
+        let stopped = false;
+        const done = playStream(output, dependencies.streamer, {
+          type: "go-live",
+        }).finally(() => {
+          active = null;
+        });
+
+        active = {
+          done,
+          stop() {
+            if (stopped) return;
+            stopped = true;
+            command.kill?.("SIGTERM");
+            active = null;
+          },
+        };
+        return active;
+      } catch (error) {
+        active = null;
+        throw new AppError(
+          error instanceof Error ? error.message : "Screen stream failed",
+          "SCREEN_STREAM_FAILED",
+          500,
+        );
+      }
+    },
+  };
+}

src/media/ytdlp.ts

@@ -9,6 +9,7 @@ export interface YtDlpMetadata {
 export interface YtDlpClient {
   getMetadata(url: string): Promise<YtDlpMetadata>;
   getDirectAudioUrl(url: string): Promise<string>;
+  getDirectVideoUrl(url: string): Promise<string>;
 }
 
 export interface YtDlpDependencies {
@@ -49,6 +50,19 @@ export function createYtDlp(dependencies: YtDlpDependencies = {}): YtDlpClient {
       ]);
       return value.trim().split("\n")[0] || url;
     },
+
+    async getDirectVideoUrl(url: string): Promise<string> {
+      const value = await runYtDlp(spawn, [
+        url,
+        "--get-url",
+        "--format",
+        "bestvideo[protocol^=http]+bestaudio[protocol^=http]/best[protocol^=http]/best",
+        "--no-playlist",
+        "--no-warnings",
+        "--quiet",
+      ]);
+      return value.trim().split("\n")[0] || url;
+    },
   };
 }
 

src/moderation/aiAnalyzer.ts

@@ -144,7 +144,9 @@ async function runAnalysisInWorker(
   messages: MessageRecord[],
 ): Promise<AnalysisWorkerResponse> {
   return new Promise((resolve, reject) => {
-    const worker = new Worker(new URL("./aiAnalysisWorker.ts", import.meta.url));
+    const worker = new Worker(
+      new URL("./aiAnalysisWorker.ts", import.meta.url),
+    );
 
     worker.once("message", (response: AnalysisWorkerResponse) => {
       worker.terminate().catch((error) => {
@@ -213,7 +215,6 @@ function scheduleConversationAnalysis(conversationKey: string): void {
 export async function queueMessageAnalysis(messageId: string): Promise<void> {
   if (!config.AI_ANALYSIS_ENABLED) return;
 
-
   try {
     // Look up the message to get its conversation key
     const message = await getMessageById(messageId);
@@ -242,7 +243,6 @@ export async function queueMessageAnalysis(messageId: string): Promise<void> {
 export function queueConversationAnalysis(conversationKey: string): void {
   if (!config.AI_ANALYSIS_ENABLED) return;
 
-
   // Schedule debounced analysis
   scheduleConversationAnalysis(conversationKey);
 }

src/player.ts

@@ -7,10 +7,12 @@ import {
   StreamType,
   VoiceConnection,
 } from "@discordjs/voice";
+import type { DiscordPlayerOwner } from "./media/mediaTypes";
 
 export class DiscordPlayer {
   private player: AudioPlayer;
   private connection: VoiceConnection | null = null;
+  private owner: DiscordPlayerOwner = "none";
 
   constructor() {
     this.player = createAudioPlayer();
@@ -21,6 +23,7 @@ export class DiscordPlayer {
 
     this.player.on("error", (error) => {
       console.error(`[player] Error: ${error.message}`);
+      this.owner = "none";
     });
   }
 
@@ -29,17 +32,28 @@ export class DiscordPlayer {
     this.connection.subscribe(this.player);
   }
 
+  public getOwner(): DiscordPlayerOwner {
+    return this.owner;
+  }
+
   public isConnected(): boolean {
     return this.connection !== null;
   }
 
-  public playStream(stream: Readable) {
+  public playStream(stream: Readable, owner: DiscordPlayerOwner) {
-    console.log("[player] Starting new audio stream...");
+    if (owner === "none") {
+      throw new Error("Discord audio player owner is required");
+    }
+    this.assertOwnerAvailable(owner);
 
     const resource = createAudioResource(stream, {
       inputType: StreamType.OggOpus,
     });
 
+    if (this.owner === owner) {
+      this.player.stop();
+    }
+    this.owner = owner;
     this.player.play(resource);
     this.connection?.subscribe(this.player);
   }
@@ -48,16 +62,30 @@ export class DiscordPlayer {
     return this.player.state.status;
   }
 
-  public pause() {
+  public pause(owner?: DiscordPlayerOwner) {
+    if (!this.canControl(owner)) return;
     this.player.pause(true);
   }
 
-  public unpause(): boolean {
+  public unpause(owner?: DiscordPlayerOwner): boolean {
+    if (!this.canControl(owner)) return false;
     return this.player.unpause();
   }
 
-  public stop() {
+  public stop(owner?: DiscordPlayerOwner) {
+    if (!this.canControl(owner)) return;
     this.player.stop();
+    this.owner = "none";
+  }
+
+  private assertOwnerAvailable(owner: DiscordPlayerOwner): void {
+    if (this.owner !== "none" && this.owner !== owner) {
+      throw new Error(`Discord audio player is owned by ${this.owner}`);
+    }
+  }
+
+  private canControl(owner?: DiscordPlayerOwner): boolean {
+    return !owner || this.owner === "none" || this.owner === owner;
   }
 }
 

src/recorder.ts

@@ -89,6 +89,8 @@ export async function startRecording(
 
   // Dengarkan siapapun yang mulai bicara
   receiver.speaking.on("start", async (userId) => {
+    if (userId === client.user?.id) return;
+
     const userMetadata = await collectUserMetadata(client, userId, channel);
     logger.info(
       { userId, username: userMetadata.username },

src/routes/mediaRoutes.ts

@@ -2,6 +2,7 @@ import type { Router } from "express";
 import express from "express";
 import { AppError } from "../errors";
 import type { MediaController } from "../media/mediaController";
+import type { MediaMode } from "../media/mediaTypes";
 
 export type MediaRouteController = Pick<
   MediaController,
@@ -21,7 +22,10 @@ export function createMediaRoutes(controller: MediaRouteController): Router {
 
   router.post("/media/queue", async (req, res, next) => {
     try {
-      const { source } = req.body as { source?: string };
+      const { source, mode = "music" } = req.body as {
+        source?: string;
+        mode?: MediaMode;
+      };
       if (!source) {
         throw new AppError(
           "Media source is required",
@@ -29,7 +33,10 @@ export function createMediaRoutes(controller: MediaRouteController): Router {
           400,
         );
       }
-      res.json(await controller.queue(source));
+      if (mode !== "music" && mode !== "screen") {
+        throw new AppError("Invalid media mode", "INVALID_MEDIA_MODE", 400);
+      }
+      res.json(await controller.queue(source, { mode }));
     } catch (error) {
       next(error);
     }

src/webserver.ts

@@ -1,15 +1,17 @@
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
+import { Streamer } from "@dank074/discord-video-stream";
+import { AudioPlayerStatus } from "@discordjs/voice";
 import type { Client } from "discord.js-selfbot-v13";
 import express from "express";
 import helmet from "helmet";
-import { AudioPlayerStatus } from "@discordjs/voice";
 import * as prism from "prism-media";
 import { WebSocketServer } from "ws";
 import { AppError } from "./errors";
 import { createChildLogger, logger } from "./logger";
 import { MediaController } from "./media/mediaController";
+import { createScreenShareController } from "./media/screenShareController";
 import { getMetrics, uptimeGauge } from "./metrics";
 import { createBroadcaster } from "./moderation/broadcaster";
 import type { ModerationBroadcaster } from "./moderation/types";
@@ -163,9 +165,16 @@ export async function startWebserver(
   const broadcaster = createBroadcaster();
   (globalThis as VoiceGlobals).moderationBroadcaster = broadcaster;
 
+  const streamer = new Streamer(_client);
+  const screenController = createScreenShareController({
+    getVoiceStatus: () => voiceController.getStatus(),
+    streamer,
+  });
+
   const mediaController = new MediaController({
     isVoiceConnected: () => voiceController.getStatus().connected,
     isBrowserStreaming: () => sharedUIState.isStreaming,
+    screenController,
     onStateChange: (state) => broadcaster.mediaState(state),
   });
 
@@ -287,11 +296,12 @@ export async function startWebserver(
   const SILENCE_TAIL_MS = 300; // continue sending silence for 300ms after browser stops
   const MAX_BUF_BYTES = BYTES_PER_FRAME * 50; // cap at 1 second to avoid runaway buffer
 
-  let opusEncoder: prism.opus.Encoder;
+  let opusEncoder: prism.opus.Encoder | null = null;
   let bridgePlayerPaused = true;
   const SILENCE_FRAME = Buffer.alloc(BYTES_PER_FRAME, 0);
 
   function startBrowserAudioBridge(): void {
+    if (opusEncoder) return;
     opusEncoder = new prism.opus.Encoder({
       rate: RATE,
       channels: CHANNELS,
@@ -308,19 +318,23 @@ export async function startWebserver(
     opusEncoder.on("error", () => {});
     opusEncoder.pipe(oggBitstream);
     opusEncoder.write(Buffer.alloc(BYTES_PER_FRAME, 0));
-    discordPlayer.playStream(oggBitstream);
+    discordPlayer.playStream(oggBitstream, "browser-bridge");
-    discordPlayer.pause();
+    discordPlayer.pause("browser-bridge");
     bridgePlayerPaused = true;
   }
 
-  function ensureBrowserAudioBridge(): void {
+  function ensureBrowserAudioBridge(): boolean {
-    if (discordPlayer.getStatus() === AudioPlayerStatus.Idle) {
+    const owner = discordPlayer.getOwner();
+    if (owner !== "none" && owner !== "browser-bridge") return false;
+    if (
+      owner === "none" ||
+      discordPlayer.getStatus() === AudioPlayerStatus.Idle
+    ) {
       startBrowserAudioBridge();
     }
+    return true;
   }
 
-  startBrowserAudioBridge();
-
   let pcmBuffer = Buffer.alloc(0);
   let lastBrowserAudioTime = 0;
 
@@ -351,9 +365,12 @@ export async function startWebserver(
       dbAccum += rmsDb(frame);
       dbCount++;
 
-      ensureBrowserAudioBridge();
+      if (!ensureBrowserAudioBridge()) {
+        pcmBuffer = Buffer.alloc(0);
+        return;
+      }
       if (bridgePlayerPaused) {
-        const unpaused = discordPlayer.unpause();
+        const unpaused = discordPlayer.unpause("browser-bridge");
         bridgePlayerPaused = false;
         wsLogger.info({ unpaused }, "Transmitting — Discord indicator ON");
       }
@@ -362,7 +379,7 @@ export async function startWebserver(
       frame = SILENCE_FRAME;
     } else if (!bridgePlayerPaused && msSinceAudio >= SILENCE_TAIL_MS) {
       // No audio for a while — pause Discord indicator
-      discordPlayer.pause();
+      discordPlayer.pause("browser-bridge");
       bridgePlayerPaused = true;
       wsLogger.info("Stopped — Discord indicator OFF");
       return;
@@ -371,6 +388,7 @@ export async function startWebserver(
     }
 
     // Write one frame. If encoder is backpressured, skip this tick to avoid stalling.
+    if (!opusEncoder) return;
     const ok = opusEncoder.write(frame);
     if (!ok) {
       opusEncoder.once("drain", () => {}); // re-arm drain without blocking

tests/media/mediaController.test.ts

@@ -5,6 +5,7 @@ import type {
   MusicPlayback,
   MusicPlayer,
   ResolvedMediaSource,
+  ScreenShareController,
 } from "../../src/media/mediaTypes";
 
 function deferred() {
@@ -190,7 +191,62 @@ describe("MediaController", () => {
     const state = await controller.stop();
 
     expect(stop).toHaveBeenCalled();
-    expect(state).toEqual({ playing: false, current: null, queue: [] });
+    expect(state).toEqual({
+      playing: false,
+      activeMode: null,
+      current: null,
+      queue: [],
+    });
+  });
+
+  it("starts screen share mode without resolving music source", async () => {
+    const screenPlayback = deferred();
+    const screenController: ScreenShareController = {
+      isActive: vi.fn(() => false),
+      start: vi.fn(async () => ({
+        done: screenPlayback.promise,
+        stop: vi.fn(),
+      })),
+    };
+    const resolveMediaSource = vi.fn(async (input) => source(input));
+    const controller = new MediaController({
+      isVoiceConnected: () => true,
+      isBrowserStreaming: () => false,
+      resolveMediaSource,
+      musicPlayer: { play: vi.fn() },
+      screenController,
+    });
+
+    const state = await controller.queue("https://youtu.be/video", {
+      mode: "screen",
+    });
+
+    expect(screenController.start).toHaveBeenCalledWith(
+      "https://youtu.be/video",
+    );
+    expect(resolveMediaSource).not.toHaveBeenCalled();
+    expect(state).toMatchObject({ playing: true, activeMode: "screen" });
+  });
+
+  it("rejects music while screen share is active", async () => {
+    const screenController: ScreenShareController = {
+      isActive: vi.fn(() => true),
+      start: vi.fn(),
+    };
+    const controller = new MediaController({
+      isVoiceConnected: () => true,
+      isBrowserStreaming: () => false,
+      resolveMediaSource: async (input) => source(input),
+      musicPlayer: { play: vi.fn() },
+      screenController,
+    });
+
+    await expect(
+      controller.queue("https://example.com/song.mp3"),
+    ).rejects.toMatchObject({
+      code: "MEDIA_BUSY",
+      statusCode: 409,
+    } satisfies Partial<AppError>);
   });
 
   it("emits state changes", async () => {
@@ -200,7 +256,10 @@ describe("MediaController", () => {
       isBrowserStreaming: () => false,
       resolveMediaSource: async (input) => source(input),
       musicPlayer: {
-        play: vi.fn(() => ({ done: new Promise(() => {}), stop: vi.fn() })),
+        play: vi.fn(() => ({
+          done: new Promise<void>(() => {}),
+          stop: vi.fn(),
+        })),
       },
       onStateChange,
     });

tests/media/mediaQueue.test.ts

@@ -20,7 +20,7 @@ describe("MediaQueue", () => {
       () => 1700000000000,
     );
 
-    const item = queue.add(source(), "tester");
+    const item = queue.add(source(), "music", "tester");
 
     expect(item).toMatchObject({
       id: "item-1",
@@ -40,7 +40,7 @@ describe("MediaQueue", () => {
       () => "item-1",
       () => 1700000000000,
     );
-    const item = queue.add(source(), "tester");
+    const item = queue.add(source(), "music", "tester");
 
     expect(queue.startNext()).toEqual({ ...item, status: "playing" });
     expect(queue.snapshot()).toEqual({
@@ -55,8 +55,8 @@ describe("MediaQueue", () => {
       () => `item-${++id}`,
       () => 1700000000000,
     );
-    queue.add(source({ title: "first" }), "tester");
+    queue.add(source({ title: "first" }), "music", "tester");
-    queue.add(source({ title: "second" }), "tester");
+    queue.add(source({ title: "second" }), "music", "tester");
     queue.startNext();
 
     queue.completeCurrent();
@@ -71,7 +71,7 @@ describe("MediaQueue", () => {
       () => "item-1",
       () => 1700000000000,
     );
-    const item = queue.add(source(), "tester");
+    const item = queue.add(source(), "music", "tester");
     queue.startNext();
 
     expect(queue.failCurrent()).toEqual({ ...item, status: "failed" });
@@ -83,7 +83,7 @@ describe("MediaQueue", () => {
       () => "item-1",
       () => 1700000000000,
     );
-    queue.add(source(), "tester");
+    queue.add(source(), "music", "tester");
     queue.startNext();
 
     queue.clear();

tests/media/musicPlayer.test.ts

@@ -1,7 +1,14 @@
+import type { spawn as nodeSpawn } from "node:child_process";
+
+type Spawn = typeof nodeSpawn;
+
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import { describe, expect, it, vi } from "vitest";
-import type { DiscordAudioPlayer } from "../../src/media/mediaTypes";
+import type {
+  DiscordAudioPlayer,
+  DiscordPlayerOwner,
+} from "../../src/media/mediaTypes";
 import { createMusicPlayer } from "../../src/media/musicPlayer";
 
 class FakeProcess extends EventEmitter {
@@ -22,9 +29,15 @@ describe("createMusicPlayer", () => {
     const discordPlayer: DiscordAudioPlayer = {
       isConnected: () => true,
       playStream: vi.fn(),
+      getOwner: vi.fn((): DiscordPlayerOwner => "none"),
+      pause: vi.fn(),
+      unpause: vi.fn(() => true),
       stop: vi.fn(),
     };
-    const player = createMusicPlayer({ spawn, discordPlayer });
+    const player = createMusicPlayer({
+      spawn: spawn as unknown as Spawn,
+      discordPlayer,
+    });
 
     const playback = player.play({
       source: "https://example.com/song.mp3",
@@ -55,7 +68,7 @@ describe("createMusicPlayer", () => {
       ],
       { stdio: ["ignore", "pipe", "pipe"] },
     );
-    expect(discordPlayer.playStream).toHaveBeenCalledWith(proc.stdout);
+    expect(discordPlayer.playStream).toHaveBeenCalledWith(proc.stdout, "music");
   });
 
   it("rejects playback when Discord is not connected", () => {
@@ -63,9 +76,15 @@ describe("createMusicPlayer", () => {
     const discordPlayer: DiscordAudioPlayer = {
       isConnected: () => false,
       playStream: vi.fn(),
+      getOwner: vi.fn((): DiscordPlayerOwner => "none"),
+      pause: vi.fn(),
+      unpause: vi.fn(() => true),
       stop: vi.fn(),
     };
-    const player = createMusicPlayer({ spawn, discordPlayer });
+    const player = createMusicPlayer({
+      spawn: spawn as unknown as Spawn,
+      discordPlayer,
+    });
 
     expect(() =>
       player.play({
@@ -77,15 +96,44 @@ describe("createMusicPlayer", () => {
     expect(spawn).not.toHaveBeenCalled();
   });
 
+  it("releases ownership on normal ffmpeg close", async () => {
+    const proc = new FakeProcess();
+    const discordPlayer: DiscordAudioPlayer = {
+      isConnected: () => true,
+      playStream: vi.fn(),
+      getOwner: vi.fn((): DiscordPlayerOwner => "none"),
+      pause: vi.fn(),
+      unpause: vi.fn(() => true),
+      stop: vi.fn(),
+    };
+    const player = createMusicPlayer({
+      spawn: vi.fn(() => proc) as unknown as Spawn,
+      discordPlayer,
+    });
+
+    const playback = player.play({
+      source: "/tmp/song.ogg",
+      title: "song.ogg",
+      kind: "local",
+    });
+    // simulate normal close
+    proc.emit("close", 0);
+    await playback.done;
+    expect(discordPlayer.stop).toHaveBeenCalledWith("music");
+  });
+
   it("kills ffmpeg and stops Discord playback once", () => {
     const proc = new FakeProcess();
     const discordPlayer: DiscordAudioPlayer = {
       isConnected: () => true,
       playStream: vi.fn(),
+      getOwner: vi.fn((): DiscordPlayerOwner => "none"),
+      pause: vi.fn(),
+      unpause: vi.fn(() => true),
       stop: vi.fn(),
     };
     const player = createMusicPlayer({
-      spawn: vi.fn(() => proc),
+      spawn: vi.fn(() => proc) as unknown as Spawn,
       discordPlayer,
     });
 

tests/media/screenShareController.test.ts

@@ -0,0 +1,94 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it, vi } from "vitest";
+import { AppError } from "../../src/errors";
+import type { DiscordPlayerOwner } from "../../src/media/mediaTypes";
+import { createScreenShareController } from "../../src/media/screenShareController";
+
+function createDependencies() {
+  const output = new PassThrough();
+  return {
+    getVoiceStatus: vi.fn(() => ({
+      connected: true,
+      activeGuildId: "guild-1" as string | null,
+      activeChannelId: "channel-1" as string | null,
+    })),
+    getPlayerOwner: vi.fn((): DiscordPlayerOwner => "none"),
+    getDirectVideoUrl: vi.fn(async () => "https://cdn.example.com/video.mp4"),
+    prepareStream: vi.fn(() => ({
+      command: { kill: vi.fn() },
+      output,
+    })),
+    playStream: vi.fn(() => new Promise<void>(() => {})),
+    streamer: { id: "streamer" },
+  };
+}
+
+describe("createScreenShareController", () => {
+  it("starts a YouTube Go Live stream", async () => {
+    const dependencies = createDependencies();
+    const controller = createScreenShareController(dependencies);
+
+    const playback = await controller.start("https://youtu.be/video");
+
+    expect(dependencies.getDirectVideoUrl).toHaveBeenCalledWith(
+      "https://youtu.be/video",
+    );
+    expect(dependencies.prepareStream).toHaveBeenCalledWith(
+      "https://cdn.example.com/video.mp4",
+      expect.objectContaining({ includeAudio: true }),
+    );
+    expect(dependencies.playStream).toHaveBeenCalledWith(
+      dependencies.prepareStream.mock.results[0].value.output,
+      dependencies.streamer,
+      { type: "go-live" },
+    );
+    expect(controller.isActive()).toBe(true);
+    playback.stop();
+    expect(controller.isActive()).toBe(false);
+  });
+
+  it("rejects when voice is not connected", async () => {
+    const dependencies = createDependencies();
+    dependencies.getVoiceStatus.mockReturnValue({
+      connected: false,
+      activeGuildId: null,
+      activeChannelId: null,
+    });
+    const controller = createScreenShareController(dependencies);
+
+    await expect(
+      controller.start("https://youtu.be/video"),
+    ).rejects.toMatchObject({
+      code: "VOICE_NOT_CONNECTED",
+      statusCode: 409,
+    } satisfies Partial<AppError>);
+  });
+
+  it("rejects when music owns the shared player", async () => {
+    const dependencies = createDependencies();
+    dependencies.getPlayerOwner.mockReturnValue("music");
+    const controller = createScreenShareController(dependencies);
+
+    await expect(
+      controller.start("https://youtu.be/video"),
+    ).rejects.toMatchObject({
+      code: "MEDIA_BUSY",
+      statusCode: 409,
+    } satisfies Partial<AppError>);
+  });
+
+  it("wraps stream startup failures", async () => {
+    const dependencies = createDependencies();
+    dependencies.playStream.mockImplementation(() => {
+      throw new Error("go live failed");
+    });
+    const controller = createScreenShareController(dependencies);
+
+    await expect(
+      controller.start("https://youtu.be/video"),
+    ).rejects.toMatchObject({
+      code: "SCREEN_STREAM_FAILED",
+      statusCode: 500,
+    } satisfies Partial<AppError>);
+  });
+});

tests/media/ytdlp.test.ts

@@ -43,7 +43,8 @@ describe("createYtDlp", () => {
 
   it("reads direct audio URL", async () => {
     const proc = new FakeProcess();
-    const ytdlp = createYtDlp({ spawn: vi.fn(() => proc) });
+    const spawn = vi.fn(() => proc);
+    const ytdlp = createYtDlp({ spawn });
 
     const result = ytdlp.getDirectAudioUrl("https://youtu.be/video");
     proc.stdout.write("https://audio.example.com/stream\n");
@@ -51,6 +52,45 @@ describe("createYtDlp", () => {
     proc.emit("close", 0);
 
     await expect(result).resolves.toBe("https://audio.example.com/stream");
+    expect(spawn).toHaveBeenCalledWith(
+      "yt-dlp",
+      [
+        "https://youtu.be/video",
+        "--get-url",
+        "--format",
+        "bestaudio[protocol^=http]/bestaudio/best",
+        "--no-playlist",
+        "--no-warnings",
+        "--quiet",
+      ],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+  });
+
+  it("reads direct video URL", async () => {
+    const proc = new FakeProcess();
+    const spawn = vi.fn(() => proc);
+    const ytdlp = createYtDlp({ spawn });
+
+    const result = ytdlp.getDirectVideoUrl("https://youtu.be/video");
+    proc.stdout.write("https://video.example.com/stream\n");
+    proc.stdout.end();
+    proc.emit("close", 0);
+
+    await expect(result).resolves.toBe("https://video.example.com/stream");
+    expect(spawn).toHaveBeenCalledWith(
+      "yt-dlp",
+      [
+        "https://youtu.be/video",
+        "--get-url",
+        "--format",
+        "bestvideo[protocol^=http]+bestaudio[protocol^=http]/best[protocol^=http]/best",
+        "--no-playlist",
+        "--no-warnings",
+        "--quiet",
+      ],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
   });
 
   it("rejects when yt-dlp exits non-zero", async () => {

tests/player.test.ts

@@ -0,0 +1,82 @@
+import { Readable } from "node:stream";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock @discordjs/voice
+vi.mock("@discordjs/voice", () => {
+  const mockPlayer = {
+    play: vi.fn(),
+    pause: vi.fn(),
+    unpause: vi.fn().mockReturnValue(true),
+    stop: vi.fn(),
+    on: vi.fn(),
+    state: { status: "idle" },
+  };
+  const mockConnection = {
+    subscribe: vi.fn().mockReturnValue({}),
+  };
+  return {
+    AudioPlayerStatus: { Idle: "idle", Playing: "playing", Paused: "paused" },
+    createAudioPlayer: vi.fn(() => mockPlayer),
+    createAudioResource: vi.fn(() => ({})),
+    StreamType: { OggOpus: "OggOpus" },
+    AudioPlayer: vi.fn(),
+    VoiceConnection: vi.fn(),
+    __mockPlayer: mockPlayer,
+    __mockConnection: mockConnection,
+  };
+});
+
+// Import after mocks
+import { DiscordPlayer } from "../src/player";
+
+describe("DiscordPlayer", () => {
+  let player: DiscordPlayer;
+  const dummyStream = new Readable();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    player = new DiscordPlayer();
+  });
+
+  describe("ownership", () => {
+    it("starts with owner none", () => {
+      expect(player.getOwner()).toBe("none");
+    });
+
+    it("playStream with owner sets owner", () => {
+      player.playStream(dummyStream, "music");
+      expect(player.getOwner()).toBe("music");
+    });
+
+    it("browser bridge cannot override music owner", () => {
+      player.playStream(dummyStream, "music");
+      expect(() => player.playStream(dummyStream, "browser-bridge")).toThrow(
+        "Discord audio player is owned by music",
+      );
+    });
+
+    it("same owner can replace stream without error", () => {
+      player.playStream(dummyStream, "music");
+      expect(() => player.playStream(dummyStream, "music")).not.toThrow();
+      expect(player.getOwner()).toBe("music");
+    });
+
+    it("matching owner stop releases ownership", () => {
+      player.playStream(dummyStream, "music");
+      player.stop("music");
+      expect(player.getOwner()).toBe("none");
+    });
+
+    it("non-owner stop is ignored", () => {
+      player.playStream(dummyStream, "music");
+      player.stop("browser-bridge");
+      expect(player.getOwner()).toBe("music");
+    });
+
+    it("stop without owner releases ownership", () => {
+      player.playStream(dummyStream, "music");
+      player.stop();
+      expect(player.getOwner()).toBe("none");
+    });
+  });
+});

tests/recorder.test.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+
+const speaking = new EventEmitter();
+const subscribe = vi.fn();
+const joinVoiceChannel = vi.fn(() => ({
+  receiver: {
+    speaking,
+    subscriptions: new Map(),
+    subscribe,
+  },
+  on: vi.fn(),
+  destroy: vi.fn(),
+}));
+
+vi.mock("@discordjs/voice", async () => {
+  const actual =
+    await vi.importActual<typeof import("@discordjs/voice")>(
+      "@discordjs/voice",
+    );
+  return {
+    ...actual,
+    joinVoiceChannel,
+    entersState: vi.fn(async () => undefined),
+  };
+});
+
+describe("startRecording", () => {
+  it("does not subscribe to the bot user's own audio", async () => {
+    const { startRecording } = await import("../src/recorder");
+    const client = {
+      user: { id: "bot-user" },
+    };
+    const channel = {
+      id: "voice-channel",
+      name: "Voice",
+      guild: {
+        id: "guild",
+        voiceAdapterCreator: {},
+      },
+    };
+
+    await startRecording(client as never, channel as never);
+    speaking.emit("start", "bot-user");
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(subscribe).not.toHaveBeenCalled();
+  });
+});

tests/routes/mediaRoutes.test.ts

@@ -14,7 +14,12 @@ function getHandler(
 describe("createMediaRoutes", () => {
   it("returns media status", async () => {
     const controller = {
-      getState: vi.fn(() => ({ playing: false, current: null, queue: [] })),
+      getState: vi.fn(() => ({
+        playing: false,
+        activeMode: null,
+        current: null,
+        queue: [],
+      })),
       queue: vi.fn(),
       skip: vi.fn(),
       stop: vi.fn(),
@@ -30,13 +35,14 @@ describe("createMediaRoutes", () => {
 
     expect(json).toHaveBeenCalledWith({
       playing: false,
+      activeMode: null,
       current: null,
       queue: [],
     });
   });
 
   it("queues a source", async () => {
-    const state = { playing: true, current: null, queue: [] };
+    const state = { playing: true, activeMode: null, current: null, queue: [] };
     const controller = {
       getState: vi.fn(),
       queue: vi.fn(async () => state),
@@ -58,10 +64,71 @@ describe("createMediaRoutes", () => {
 
     expect(controller.queue).toHaveBeenCalledWith(
       "https://example.com/song.mp3",
+      { mode: "music" },
     );
     expect(json).toHaveBeenCalledWith(state);
   });
 
+  it("queues a screen source", async () => {
+    const state = {
+      playing: true,
+      activeMode: "screen" as const,
+      current: null,
+      queue: [],
+    };
+    const controller = {
+      getState: vi.fn(),
+      queue: vi.fn(async () => state),
+      skip: vi.fn(),
+      stop: vi.fn(),
+    };
+    const handler = getHandler(
+      createMediaRoutes(controller),
+      "/media/queue",
+      "post",
+    );
+    const json = vi.fn();
+
+    await handler?.(
+      { body: { source: "https://youtu.be/video", mode: "screen" } } as Request,
+      { json } as unknown as Response,
+      vi.fn(),
+    );
+
+    expect(controller.queue).toHaveBeenCalledWith("https://youtu.be/video", {
+      mode: "screen",
+    });
+    expect(json).toHaveBeenCalledWith(state);
+  });
+
+  it("passes invalid mode errors to Express", async () => {
+    const controller = {
+      getState: vi.fn(),
+      queue: vi.fn(),
+      skip: vi.fn(),
+      stop: vi.fn(),
+    };
+    const handler = getHandler(
+      createMediaRoutes(controller),
+      "/media/queue",
+      "post",
+    );
+    const next = vi.fn();
+
+    await handler?.(
+      {
+        body: { source: "https://example.com/song.mp3", mode: "video" },
+      } as Request,
+      { json: vi.fn() } as unknown as Response,
+      next,
+    );
+
+    expect(next.mock.calls[0][0]).toMatchObject({
+      code: "INVALID_MEDIA_MODE",
+      statusCode: 400,
+    });
+  });
+
   it("passes missing source errors to Express", async () => {
     const controller = {
       getState: vi.fn(),