fix(classroom): 优化音频捕获回退与显示媒体处理

- 重构 useClassroomAudio/useAudioRecovery 音频恢复逻辑
- 新增 displayMediaHandler 处理显示媒体请求
- 调整 audioCapture 与主进程音频初始化

Author: Aparencia

client/electron/audioCapture.ts

@@ -18,6 +18,7 @@
 
 import { desktopCapturer, DesktopCapturerSource, BrowserWindow } from 'electron';
 import { logger } from './logger';
+import { setPreferredDisplaySource } from './displayMediaHandler';
 
 // ================================================================
 // 类型定义
@@ -127,18 +128,15 @@ export class AudioCapture {
    * 开始音频捕获
    *
    * 1. 如果未指定 sourceId，自动选择第一个可用的系统音频源
-   * 2. 方案A：若指定的是窗口源（window:xxx），优先尝试窗口级音频捕获，
-   *    同时解析一个屏幕环回源作为降级候选（Windows 上窗口源音频支持
-   *    依赖 Chromium 版本，失败时渲染进程自动回退环回源）
-   * 3. 向渲染进程发送启动指令（含 sourceId + fallbackSourceId + 配置）
-   * 4. 渲染进程负责 getUserMedia 和音频切片
+   * 2. 将期望源登记到 displayMedia handler（渲染进程 getDisplayMedia 时生效）
+   * 3. 向渲染进程发送启动指令（含 sourceId + 配置）
+   * 4. 渲染进程负责 getDisplayMedia 与音频切片
    */
   async start(win: BrowserWindow, sourceId?: string): Promise<void> {
     if (this.capturing || this.disposed) return;
 
     // 解析音频源
     let resolvedSourceId = sourceId ?? null;
-    let fallbackSourceId: string | null = null;
     if (!resolvedSourceId) {
       const sources = await listAudioSources();
       if (sources.length === 0) {
@@ -147,17 +145,12 @@ export class AudioCapture {
       }
       resolvedSourceId = sources[0].id;
       logger.info(`[AudioCapture] 自动选择音频源: ${sources[0].name} (${resolvedSourceId})`);
-    } else if (resolvedSourceId.startsWith('window:')) {
-      // 方案A：窗口源直采目标应用（如 B站客户端/浏览器）的音频，
-      // 预解析屏幕环回源作为降级候选，防御窗口级捕获不受支持的环境
-      const sources = await listAudioSources();
-      fallbackSourceId = sources[0]?.id ?? null;
-      logger.info(
-        `[AudioCapture] 方案A 窗口源音频捕获: ${resolvedSourceId}, ` +
-        `降级候选: ${fallbackSourceId ?? '无'}`,
-      );
     }
 
+    // 登记期望源：渲染进程随后调用 getDisplayMedia，主进程 handler 据此授权
+    // 并附加 audio: 'loopback' 才能拿到真实系统音频（详见 displayMediaHandler.ts）
+    setPreferredDisplaySource(resolvedSourceId);
+
     this.capturing = true;
     this.boundWin = win;
 
@@ -171,7 +164,6 @@ export class AudioCapture {
     if (!win.isDestroyed()) {
       win.webContents.send('audio_capture_do_start', {
         sourceId: resolvedSourceId,
-        fallbackSourceId,
         options: this.options,
       });
     }

client/electron/displayMediaHandler.ts

@@ -0,0 +1,73 @@
+/**
+ * Electron 系统音频环回请求处理器（getDisplayMedia 桥）
+ *
+ * @ai-context: Windows 系统音频捕获的唯一可靠路径。Electron 30+ / Chromium 中，
+ * 渲染进程用 getUserMedia({ audio: { chromeMediaSource: 'desktop' } }) 单独请求
+ * 音频轨已不返回真实音频——会拿到一条恒为数字零的静音轨（RMS 0.00，不抛错），
+ * 这是"监听 0 句 / 时间轴全静默"的根因。正确做法是主进程注册
+ * setDisplayMediaRequestHandler 并在 callback 中返回 audio: 'loopback'，
+ * 由渲染进程调用 getDisplayMedia({ video: true, audio: true }) 触发。
+ * @ai-context: audio: 'loopback' 捕获系统输出混音（含本应用自身声音）；
+ * 若需静音本地播放改用 'loopbackWithMute'。handler 全局唯一，重复注册会覆盖。
+ *
+ * TODO(现场课程): 麦克风输入不走 displayMedia 路径，直接以 deviceId 调用
+ * getUserMedia({ audio: { deviceId } }) 即可，无需本模块参与。
+ */
+
+import { session, desktopCapturer } from 'electron';
+import { logger } from './logger';
+
+/**
+ * 期望捕获的视频源 ID（window:xxx / screen:xxx）。
+ * 仅用于让 loopback 请求绑定到目标窗口所在屏幕；音频始终是系统混音。
+ */
+let preferredSourceId: string | null = null;
+
+/** 设置本次采集期望的源 ID（由 AudioCapture.start 调用），null 表示用首个屏幕源 */
+export function setPreferredDisplaySource(sourceId: string | null): void {
+  preferredSourceId = sourceId;
+}
+
+/**
+ * 注册 displayMedia 请求处理器（须在 app.whenReady 后调用一次）
+ *
+ * 渲染进程调用 navigator.mediaDevices.getDisplayMedia() 时进入此 handler，
+ * 我们直接指定源并附加 loopback 音频，跳过系统选择器（无需用户二次确认）。
+ */
+export function registerDisplayMediaHandler(): void {
+  session.defaultSession.setDisplayMediaRequestHandler(
+    (_request, callback) => {
+      void (async () => {
+        try {
+          const sources = await desktopCapturer.getSources({
+            types: ['screen', 'window'],
+            thumbnailSize: { width: 1, height: 1 },
+          });
+          if (sources.length === 0) {
+            logger.error('[DisplayMedia] 无可用捕获源，拒绝请求');
+            // 空对象表示拒绝授权（Electron 约定）
+            callback({});
+            return;
+          }
+          // 优先匹配期望源；未命中则退回首个屏幕源（屏幕源对 loopback 最稳定）
+          const matched = preferredSourceId
+            ? sources.find((s) => s.id === preferredSourceId)
+            : undefined;
+          const screenSource = sources.find((s) => s.id.startsWith('screen:'));
+          const chosen = matched ?? screenSource ?? sources[0];
+
+          logger.info(
+            `[DisplayMedia] 授予捕获: source=${chosen.name} (${chosen.id}), audio=loopback`,
+          );
+          callback({ video: chosen, audio: 'loopback' });
+        } catch (err) {
+          logger.error('[DisplayMedia] 处理捕获请求失败:', err);
+          callback({});
+        }
+      })();
+    },
+    // 使用应用内指定源而非 Windows 系统选择器，保持无感采集体验
+    { useSystemPicker: false },
+  );
+  logger.info('[DisplayMedia] setDisplayMediaRequestHandler 已注册（audio: loopback）');
+}

client/electron/main.ts

@@ -33,6 +33,7 @@ import { resolveDbPath } from './db/storageConfig.js';
 import { registerMigrationHandlers } from './db/migration.js';
 import { loadEnvironment } from './envLoader.js';
 import { installCspPolicy } from './cspPolicy.js';
+import { registerDisplayMediaHandler } from './displayMediaHandler.js';
 import { registerDbIpcHandlers } from './db/dbIpcHandlers.js';
 import { registerStorageIpcHandlers } from './storageIpcHandlers.js';
 import { registerKeyframeScheme, registerKeyframeIpcHandlers } from './ipc/keyframeStorage.js';
@@ -123,6 +124,10 @@ if (!gotTheLock) {
     // SEC-005: CSP 安全策略注入（详见 cspPolicy.ts）
     installCspPolicy(isDevMode());
 
+    // 系统音频环回捕获授权（详见 displayMediaHandler.ts）
+    // 必须在渲染进程发起 getDisplayMedia 之前注册，否则请求会被默认拒绝
+    registerDisplayMediaHandler();
+
     // 加载持久化的 AI 网关地址（在注册 handler 之前，确保 handler 可用正确的 URL）
     await loadPersistedGatewayUrl();
     logger.info(`[AI] Gateway URL resolved: ${gatewayUrl()}`);

client/src/features/classroom/hooks/useAudioRecovery.ts

@@ -1,15 +1,12 @@
 /**
- * 课堂音频自动恢复 hook（静音诊断 / 窗口源回退 / 设备变更重启）
+ * 课堂音频自动恢复 hook（静音诊断 / 设备变更重启）
  *
- * @ai-context: 从 useClassroomAudio 拆出的独立恢复层。三条恢复路径：
- * ①窗口源静音回退——Windows 上窗口源（window:xxx）getUserMedia 可能"成功但
- * 给出纯静音轨"（不抛错，异常降级不会触发），SilenceTracker 检出连续静音后
- * 自动 stop→start 以环回源重启（每会话仅回退一次）；
- * ②输出设备不匹配提示——已在环回源仍持续静音，说明视频声音输出到了
- * 非默认设备，提示用户核对默认输出设备；
- * ③设备变更重启——默认输出设备切换后环回仍绑定旧设备，devicechange 时
- * 自动重启重新绑定。
- * @ai-context: 仅依赖 refs 的稳定回调，重启经 restartingRef 互斥防止并发。
+ * @ai-context: 从 useClassroomAudio 拆出的独立恢复层。两条恢复路径：
+ * ①输出设备不匹配诊断——系统环回只录默认输出设备，视频声音若输出到其他
+ * 设备（HDMI/蓝牙）会表现为"音频块正常但持续静音"，检出后提示用户核对；
+ * ②设备变更重启——默认输出设备切换后环回仍绑定旧设备，devicechange 时
+ * 自动 stop→start 重新绑定。
+ * @ai-context: 仅依赖 refs 的稳定回调，重启经 restartingRef 互斥防并发。
  */
 import { useEffect, useRef, useCallback } from 'react';
 import type { CaptureMode, SessionStatus } from '@/lib/capture';
@@ -26,19 +23,16 @@ const RESTART_CLEANUP_DELAY_MS = 500;
 interface UseAudioRecoveryOptions {
   status: SessionStatus;
   mode: CaptureMode;
-  /** 方案A：会话选中窗口的源 ID（回退环回后置空） */
+  /** 会话选中窗口的源 ID，重启时沿用同一源 */
   audioSourceId?: string | null;
   onNotify: (type: 'warning' | 'error', message: string) => void;
 }
 
 export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseAudioRecoveryOptions) {
   const notifyRef = useRef(onNotify);
   notifyRef.current = onNotify;
-  /** 当前生效的音频源（窗口源回退环回后变为 undefined） */
   const effectiveSourceRef = useRef<string | undefined>(audioSourceId ?? undefined);
   const silenceTrackerRef = useRef(new SilenceTracker());
-  /** 本会话是否已执行过窗口源→环回回退 */
-  const fellBackRef = useRef(false);
   const restartingRef = useRef(false);
 
   const audioEnabled = status === 'capturing' && (mode === 'audio' || mode === 'mixed');
@@ -47,7 +41,6 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
   useEffect(() => {
     if (status !== 'capturing') return;
     effectiveSourceRef.current = audioSourceId ?? undefined;
-    fellBackRef.current = false;
     silenceTrackerRef.current.reset();
     // eslint-disable-next-line react-hooks/exhaustive-deps -- 仅会话开始时快照 audioSourceId
   }, [status]);
@@ -73,31 +66,19 @@ export function useAudioRecovery({ status, mode, audioSourceId, onNotify }: UseA
     }
   }, []);
 
-  // 静音诊断：窗口源先自动回退环回；已是环回仍静音则提示核对输出设备
+  // 静音诊断：音频块正常但持续无声 → 提示核对系统默认输出设备
   useEffect(() => {
     if (!audioEnabled || !window.electronAPI) return;
     const off = window.electronAPI.on('audio_capture_chunk', (...args: unknown[]) => {
       const chunk = args[0] as { audioBuffer: ArrayBuffer };
       if (!silenceTrackerRef.current.push(computeChunkRms(chunk.audioBuffer))) return;
-
-      const src = effectiveSourceRef.current;
-      if (src?.startsWith('window:') && !fellBackRef.current) {
-        // 方案A 漏洞补偿：窗口源"成功但静音"不抛错，只能靠静音检测触发回退
-        fellBackRef.current = true;
-        effectiveSourceRef.current = undefined;
-        console.warn('[useAudioRecovery] 窗口音频源持续静音，自动回退系统环回');
-        void restartCapture(undefined).then((ok) => {
-          if (ok) notifyRef.current('warning', '窗口音频源持续静音，已自动切换为系统环回捕获');
-        });
-        return;
-      }
       void getDefaultOutputDeviceLabel().then((label) => {
         notifyRef.current('warning',
-          `持续收到静音音频：请确认视频声音正在播放，且输出到系统默认设备${label ? `「${label}」` : ''}（音频捕获只能录到默认输出设备的声音）`);
+          `持续收到静音音频：请确认视频声音正在播放，且输出到系统默认设备${label ? `「${label}」` : ''}（系统音频捕获只能录到默认输出设备的声音）`);
       });
     });
     return off;
-  }, [audioEnabled, restartCapture]);
+  }, [audioEnabled]);
 
   // 设备变更自动重启：重新绑定新的默认输出设备
   useEffect(() => {

client/src/features/classroom/hooks/useClassroomAudio.ts

@@ -28,8 +28,6 @@ const CHUNK_GAP_TIMEOUT_MS = 10000;
 
 interface AudioStartPayload {
   sourceId: string;
-  /** 方案A 窗口源不可用时的环回降级候选（主进程解析） */
-  fallbackSourceId?: string | null;
   options: { sampleRate: number; channels: number; chunkDurationMs: number };
 }
 
@@ -47,27 +45,35 @@ interface UseClassroomAudioOptions {
 }
 
 /**
- * 以桌面源打开系统/窗口音频流。
- * 方案A 防御：窗口源（window:xxx）音频捕获在部分 Windows/Chromium 环境
- * 不受支持（NotFoundError/NotAllowedError），失败时自动回退环回降级候选。
+ * 打开系统音频环回流。
+ *
+ * 必须走 getDisplayMedia 且同时请求 video —— 主进程的
+ * setDisplayMediaRequestHandler 会在授权时附加 audio: 'loopback'，
+ * 这是 Windows 下拿到真实系统音频的唯一可靠路径。
+ * 旧的 getUserMedia({ audio: { chromeMediaSource: 'desktop' } }) 在
+ * Electron 30+ 会静默返回恒为数字零的静音轨（RMS 0.00），不可再用。
+ * 拿到流后立即停掉视频轨，仅保留音频，避免屏幕捕获的额外开销。
  */
-async function openDesktopAudioStream(payload: AudioStartPayload): Promise<MediaStream> {
-  const request = (id: string) => navigator.mediaDevices.getUserMedia({
-    audio: {
-      chromeMediaSource: 'desktop',
-      chromeMediaSourceId: id,
-    } as MediaTrackConstraintSet,
+async function openDesktopAudioStream(): Promise<MediaStream> {
+  const stream = await navigator.mediaDevices.getDisplayMedia({
+    video: true,
+    audio: true,
   });
-  try {
-    return await request(payload.sourceId);
-  } catch (err) {
-    if (!payload.fallbackSourceId) throw err;
-    console.warn(
-      `[useClassroomCapture] 窗口源音频捕获失败(${payload.sourceId})，回退系统环回:`,
-      err,
-    );
-    return request(payload.fallbackSourceId);
+  const audioTracks = stream.getAudioTracks();
+  if (audioTracks.length === 0) {
+    stream.getTracks().forEach((t) => t.stop());
+    throw new Error('系统音频轨缺失：displayMedia 未返回 loopback 音频');
   }
+  // 视频轨仅用于触发 loopback 授权，立即停止释放屏幕捕获资源
+  stream.getVideoTracks().forEach((t) => {
+    t.stop();
+    stream.removeTrack(t);
+  });
+  console.info(
+    `[useClassroomCapture] 系统音频环回已获取: track="${audioTracks[0].label}", ` +
+    `enabled=${audioTracks[0].enabled}, muted=${audioTracks[0].muted}`,
+  );
+  return stream;
 }
 
 export function useClassroomAudio({ captureManager, status, mode, onNotify }: UseClassroomAudioOptions) {
@@ -152,8 +158,8 @@ export function useClassroomAudio({ captureManager, status, mode, onNotify }: Us
       const payload = args[0] as AudioStartPayload;
       (async () => {
         try {
-          // 方案A：优先窗口源直采，失败自动回退环回降级候选
-          const stream = await openDesktopAudioStream(payload);
+          // 系统音频环回（主进程 handler 附加 audio: 'loopback'）
+          const stream = await openDesktopAudioStream();
           const audioCtx = new AudioContext({ sampleRate: payload.options.sampleRate });
           // 关键修复：非用户手势调用栈中创建的 AudioContext 默认 suspended，
           // 必须显式 resume()，否则 onaudioprocess 永不触发（0 音频块）。