@xmov/avatar 2.0.0-beta.11 → 2.0.0-beta.13

package/dist/modules/ResourceManager.d.ts

@@ -3,7 +3,7 @@ import XmovAvatar from "../index";
 /**
  * 资源处理模块，加载并存储资源
  */
-type TOptions = Pick<IAvatarOptions, "appId" | "appSecret" | "gatewayServer" | 'cacheServer' | "sdkInstance" | "config" | "headers" | "gateway_type" | "tag" | "asr_id" | "llm_id" | "session_speak_req_id"> & {
+type TOptions = Pick<IAvatarOptions, "appId" | "appSecret" | "gatewayServer" | 'cacheServer' | "sdkInstance" | "config" | "headers" | "gateway_type" | "tag" | "asr_id" | "llm_id" | "session_speak_req_id" | "audioOnlyMode"> & {
     sessionRequestData?: Record<string, unknown>;
     onNetworkInfo(quality: INetworkInfo): void;
     onStartSessionWarning?: (message: Object) => void;
@@ -169,6 +169,7 @@ export default class ResourceManager {
     private isProcessingVideo;
     private cacheServer?;
     private startSessionTimer;
+    private audioOnlyMode;
     private downloadingVideos;
     first_load: boolean;
     constructor(options: TOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-beta.11",
+  "version": "2.0.0-beta.13",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",
@@ -28,7 +28,9 @@
   "scripts": {
     "build": "microbundle --workers --define ENV=production,VERSION=$npm_package_version --external none --tsconfig tsconfig.json && pnpm run build:agent && node upload-sdk.js build",
     "build:agent": "microbundle --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json && node scripts/build-agent-entry.mjs",
-    "sdk": "microbundle watch --workers --define ENV=development,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
+    "sdk": "pnpm --filter @xmov/avatar run --parallel --no-bail \"/^sdk:.+$/\"",
+    "sdk:core": "microbundle watch --workers --define ENV=development,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
+    "sdk:agent": "node scripts/build-agent-entry.mjs && microbundle watch --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json",
     "app": "cd app/ && npm run dev",
     "app:lan": "pnpm --dir app dev:lan",
     "test:agent": "node scripts/run-agent-tests.mjs",

package/src/baseRender/AudioRenderer.ts

@@ -225,19 +225,25 @@ export default class AudioRender {
   pause() {
     this.isPlaying = false;
     this.options.dataCacheQueue._clearAudio(this.speech_id);
+    this.lastFrameIndex = -1;
     this.firstFrameIndex = -1;
+    this.cacheFirstFrameIndex = -1;
+    this.cacheAudioData = [];
+    this.mseCacheAudioData = [];
+    this.oldSpeechId = -1;
     // 停止 PCM 播放
     this.audio?.stop();
-    
+
     // 停止 WebM 播放
     this.mseAudioPlayer?.stop(this.addNewAudioSegment.bind(this));
     this.speech_id = -1;
   }
 
   stop(speech_id: number) {
-    // 如果当前需要结束的是旧的语音ID，直接返回
-    if(this.oldSpeechId >= speech_id) return;
-    
+    // speech_id === -1 表示强制清理（用于 pauseRender / destroy / 断网重连场景），不受 oldSpeechId 限制
+    // 否则如果 oldSpeechId >= speech_id 直接返回，避免重复处理
+    if (speech_id !== -1 && this.oldSpeechId >= speech_id) return;
+
     this.isPlaying = false;
     this.options.dataCacheQueue._clearAudio(speech_id);
     this.firstFrameIndex = -1;
@@ -255,7 +261,12 @@ export default class AudioRender {
     }
     this.oldSpeechId = speech_id;
     this.speech_id = -1;
-    if (this.cacheAudioData.length > 0) {
+    if (speech_id === -1) {
+      // 强制清理：清空所有缓存数据，不推入音频流（用于 pauseRender / destroy / 断网重连）
+      this.cacheFirstFrameIndex = -1;
+      this.cacheAudioData = [];
+      this.mseCacheAudioData = [];
+    } else if (this.cacheAudioData.length > 0) {
       this.firstFrameIndex = this.cacheFirstFrameIndex;
       this.cacheFirstFrameIndex = -1;
       // 新的缓存下来的数据，推入音频流

package/src/baseRender/AvatarRenderer.ts

@@ -19,16 +19,11 @@ type Option = {
   resourceManager: ResourceManager;
   saveAndDownload: SaveAndDownload;
   forceSyncDecoder: () => void;
-  reportMessage: (message: {
-    code: EErrorCode;
-    message: string;
-    e?: object;
-  }) => void;
+  reportMessage: (message: { code: EErrorCode; message: string; e?: object }) => void;
   onDownloadProgress: (progress: number) => void;
   onStateChange: (state: string) => void;
   onRenderChange: (state: RenderState) => void;
   sendVideoInfo: (info: { name: string; body_id: number; id: number }) => void;
-  onError: (error: any) => void;
   sendSdkPoint: (point: string, data: any) => void;
 };
 export default class AvatarRender {
@@ -989,13 +984,13 @@ export default class AvatarRender {
     } else {
       if(this.lastRealFaceFrame === -1) {
         faceFrame = curRealFaceData;
-        // this.options.onError({
+        // this.options.reportMessage({
         //   code: EErrorCode.RENDER_FACE_ERROR,
         //   message: `第${frameIndex}帧 实时面部数据为空,原始数据渲染`,
         //   e: JSON.stringify({ bodyFrame, faceFrame }),
         // });
       } else {
-        // this.options.onError({
+        // this.options.reportMessage({
         //   code: EErrorCode.RENDER_FACE_ERROR,
         //   message: `第${frameIndex}帧 实时面部数据为空，插值渲染`,
         //   e: JSON.stringify({ bodyFrame, faceFrame }),
@@ -1036,30 +1031,26 @@ export default class AvatarRender {
       // 判断bodyFrame和faceFrame是否为空
       if (!bodyFrame) {
         this.allLostFrameCount++;
-        this.options.onError({
+        this.options.reportMessage({
           code: EErrorCode.RENDER_BODY_ERROR,
           message: `Error:  第${frameIndex}帧 bodyFrame为空`,
-          e: JSON.stringify({ bodyFrame, faceFrame }),
+          e: { bodyFrame, faceFrame },
         });
       } else if (!faceFrame) {
         this.allLostFaceFrameCount++;
-        this.options.onError({
+        this.options.reportMessage({
           code: EErrorCode.RENDER_FACE_ERROR,
           message: `Error: 第${frameIndex}帧 faceFrame为空`,
-          e: JSON.stringify({ bodyFrame, faceFrame }),
+          e: { bodyFrame, faceFrame },
         });
       }
       if(this.allLostFrameCount === this.maxLostFrameCount) {
         this.options.reportMessage({
           code: EErrorCode.RENDER_DATA_MISSING,
-          message: `连续${this.maxLostFrameCount}帧 身体渲染数据缺失.`,
+          message: `连续${this.maxLostFrameCount}帧 身体渲染数据缺失`,
+          e: { bodyFrame, faceFrame },
         });
         // 丢失过多帧,达到最大允许丢失帧数后,触发解码器对齐到最新的一帧
-         this.options.onError({
-          code: EErrorCode.RENDER_DATA_MISSING,
-          message: `Error: 连续${this.maxLostFrameCount}帧 身体渲染数据缺失`,
-          e: JSON.stringify({ bodyFrame, faceFrame }),
-        });
         this.forceSyncDecoder();
         this.allLostFrameCount = 0;
       }
@@ -1180,10 +1171,10 @@ export default class AvatarRender {
           rendered = true;
         } catch (error) {
           (window as any).avatarSDKLogger.error(this.TAG, "渲染帧失败:", error);
-          this.options.onError({
+          this.options.reportMessage({
             code: EErrorCode.WebGL_RENDER_ERROR,
             message: `Error: 第${frameIndex}帧 webgl渲染异常`,
-            e: JSON.stringify({ bodyFrame, faceFrame, error }),
+            e: { bodyFrame, faceFrame, error },
           });
         } finally {
           // 渲染完成后再关闭VideoFrame

package/src/baseRender/MSEAudioPlayer.ts

@@ -184,14 +184,25 @@ export default class MediaSourceAudioPlayer {
    * 获取缓冲范围
    */
   private getBufferedRanges(): string {
-    if (this.sourceBuffer && this.sourceBuffer.buffered.length > 0) {
-      const ranges: string[] = [];
-      for (let i = 0; i < this.sourceBuffer.buffered.length; i++) {
-        const start = this.sourceBuffer.buffered.start(i).toFixed(2);
-        const end = this.sourceBuffer.buffered.end(i).toFixed(2);
-        ranges.push(`[${start}-${end}]`);
+    try {
+      // stop/destroy 流程中浏览器会先移除 SourceBuffer 再置空引用，
+      // 此时访问 .buffered 会抛 InvalidStateError，需要 readyState 校验 + 兜底
+      if (
+        this.sourceBuffer &&
+        this.mediaSource?.readyState === "open" &&
+        this.sourceBuffer.buffered.length > 0
+      ) {
+        const ranges: string[] = [];
+        for (let i = 0; i < this.sourceBuffer.buffered.length; i++) {
+          const start = this.sourceBuffer.buffered.start(i).toFixed(2);
+          const end = this.sourceBuffer.buffered.end(i).toFixed(2);
+          ranges.push(`[${start}-${end}]`);
+        }
+        return ranges.join(", ");
       }
-      return ranges.join(", ");
+    } catch (e) {
+      // SourceBuffer 已被移除（stop/destroy 竞态），视为无缓冲数据
+      return "-";
     }
     return "-";
   }

package/src/control/RenderScheduler.ts

@@ -158,9 +158,6 @@ export default class RenderScheduler {
         this.renderState = state;
       },
       sendVideoInfo: config.sendVideoInfo,
-      onError: (error: any) => {
-        this.sdk.onMessage(error);
-      },
     });
     this.uiRenderer = new UIRenderer({
       sdk: this.sdk,
@@ -341,9 +338,10 @@ export default class RenderScheduler {
           } else {
             nowFaceData.push(faceData[i]);
           }
-          nowFaceData.length && this.dataCacheQueue._updateFacial(nowFaceData);
-          realFaceData.length && this.dataCacheQueue._updateRealFacial(realFaceData);
         }
+        // 分类完成后一次性入队，避免循环内对累加数组重复 push 导致队列数据重复
+        nowFaceData.length && this.dataCacheQueue._updateFacial(nowFaceData);
+        realFaceData.length && this.dataCacheQueue._updateRealFacial(realFaceData);
         break;
       case EFrameDataType.AUDIO:
         const audioData = data as IRawAudioFrameData[];
@@ -411,6 +409,11 @@ export default class RenderScheduler {
             clearTimeout(this._speedResetTimer);
         }
 
+        // 播放加速大于4，直接丢弃
+        if (playbackSpeed > 4) {
+          return;
+        }
+
         // 8. 应用速度
         this.audioRenderer.setSpeed(playbackSpeed);
 
@@ -490,7 +493,34 @@ export default class RenderScheduler {
             code: EErrorCode.EVENT_TRIGGERED,
             message: 'WARNING: 有新的speak_start事件，但是上一轮仍未结束，触发兜底结束',
           });
-          this.interrupt('new_speak_start');
+          const currentSpeakStart = d.flatMap(item => item.e ?? []).find(ev => ev.type === 'speak_start');
+          const newSpeakId = currentSpeakStart?.speech_id ?? 0;
+          const playingSpeechId = this.audioRenderer.speech_id;
+          // 仅当正在播放的确实是上一轮（sid 小于新一轮）时才打断旧轮次。
+          // 若事件晚于音频到达（playingSpeechId 已是新一轮 sid），此时播放的就是新一轮，
+          // 不能用 interrupt()（其目标取 audioRenderer.speech_id），否则会误清新一轮的音频队列、
+          // 字幕事件，并因 lastSpeechId/oldSpeechId 更新导致后续音视频帧全部被丢弃，
+          // 表现为"有口型、无字幕、无音频"。
+          if (playingSpeechId !== -1 && playingSpeechId < newSpeakId) {
+            this.interrupt('new_speak_start', playingSpeechId);
+            // stop() 内部有 oldSpeechId >= speech_id 的防重入守卫：当 speech_id 停留在
+            // 异常残留值（如初始值 0，长会话中 isPlaying 卡死为 true）时 stop 会被拦截，
+            // isPlaying/speech_id 无法复位，导致新一轮音频在 _updateAudio 中永远走缓存分支
+            // 不播放（日志表现：缓存数据长度持续增长且无"开始播放"）。
+            // 这里检测到 stop 未生效（speech_id 未复位为 -1）时，用 pause() 强制复位，
+            // pause 会 flush 已缓存音频并把 speech_id/oldSpeechId 重置，新一轮可正常起播。
+            if (this.audioRenderer.speech_id !== -1) {
+              this.audioRenderer.pause();
+            }
+          }
+          // 新 speak_start 已到来，立即复位 interrupt 并更新轮次状态，
+          // 避免依赖 UIRenderer 在 sf 帧处理事件时（sf==当前帧且事件在 compose 后被处理）被漏处理，
+          // 导致新轮次实际说话期间仍被强制渲染为闭嘴表情
+          if (currentSpeakStart) {
+            this.currentSpeechId = currentSpeakStart.speech_id ?? 0;
+            this.avatarRenderer.setInterrupt(false);
+            this.uiRenderer.lastSpeechId = currentSpeakStart.speech_id ?? 0;
+          }
         }
 
         // 2. 处理过期speak_start
@@ -830,6 +860,14 @@ export default class RenderScheduler {
     if (frame) {
       this.decoder._offLineMode(this.resourceManager._getOfflineIdle(), frame);
     }
+    // 重置所有 speechId 相关状态，避免联网后新语音被过滤
+    // - lastSpeechId: 用于过滤旧 sid 的音频数据（L444）
+    // - currentSpeechId: 用于 speak_end 时判断是否 setInterrupt
+    // - uiRenderer.lastSpeechId: UIRenderer 会过滤 sid < lastSpeechId 的事件（含 speak_start）
+    //   若不重置，联网后新语音的 speak_start 会被过滤，导致字幕正常但无音频
+    this.lastSpeechId = -1;
+    this.currentSpeechId = -1;
+    this.uiRenderer.lastSpeechId = -1;
   }
   _offlineRun() {
     this.decoder._offlineRun()
@@ -844,6 +882,16 @@ export default class RenderScheduler {
     this.audioRenderer.resume();
   }
 
+  /**
+   * app 切后台时暂停音频并清空对齐状态（复用断网离线时的 pause()）
+   * 不能保留缓存续播：Android 后台视频帧号持续递增而音频停留在暂停位置，
+   * 恢复后音画基准脱节；且后台期间可能下发新 speak 数据，旧缓存与新 sf 冲突。
+   * 恢复后依赖新下发音频的 sf 作为 firstFrameIndex 重新对齐
+   */
+  pauseForBackground() {
+    this.audioRenderer.pause();
+  }
+
   /**
    * 设置数字人canvas的显隐状态
    * @param visible 是否可见
@@ -859,10 +907,13 @@ export default class RenderScheduler {
     this.avatarRenderer.setWalkConfig(walkConfig);
   }
 
-  interrupt(type?: string): number{
+  // targetSpeechId: 显式指定要打断的轮次 sid。缺省时取 audioRenderer.speech_id（当前播放轮次）。
+  // 当事件晚于音频到达时，audioRenderer.speech_id 可能已经切换到新一轮，此时必须显式传旧 sid，
+  // 避免误清新一轮的音频与字幕。
+  interrupt(type?: string, targetSpeechId?: number): number{
     const start = Date.now();
     // 插入中断字幕和语音结束事件
-    const speech_id = this.audioRenderer.speech_id;
+    const speech_id = targetSpeechId ?? this.audioRenderer.speech_id;
     if(type === "in_offline_mode") {
       this.lastSpeechId = -1;
     } else {

package/src/index.ts

@@ -270,6 +270,7 @@ export default class XmovAvatar {
       gatewayServer,
       cacheServer,
       config:_config,
+      audioOnlyMode: options.audioOnlyMode || false,
       onNetworkInfo(networkInfo) {
         self.networkInfo = networkInfo;
         options.onNetworkInfo?.(networkInfo);
@@ -1039,12 +1040,28 @@ export default class XmovAvatar {
 
   visibilitychange() {
     if (document.hidden) {
-      // this.offlineMode()
-      // tab 回来时，强制同步解帧队列
-      // this.renderScheduler.forceSyncDecoder();
+      // 进入后台：暂停渲染循环和解码器（省电）、清空音频与表情数据
+      // 仅渲染中暂停（resumeRender 要求 paused 状态才能恢复），
+      // 其他状态（init/stopped/隐身 paused）只停止音频，避免强制暂停后无法恢复
+      const rs = this.renderScheduler?.getRenderState();
+      if (rs === RenderState.rendering || rs === RenderState.resumed) {
+        this.renderScheduler?.pauseRender();
+      } else {
+        this.renderScheduler?.pauseForBackground();
+      }
     } else {
-      if (this.ttsa?.getStatus()) {
-        this.renderScheduler.forceSyncDecoder();
+      // 回到前台：若处于暂停态则恢复渲染（内部已 forceSyncDecoder 对齐最新帧）
+      if (this.renderScheduler?.getRenderState() === RenderState.paused) {
+        this.renderScheduler?.resumeRender();
+      } else if (this.ttsa?.getStatus()) {
+        // 未暂停但连接正常：兜底同步解帧队列
+        this.renderScheduler?.forceSyncDecoder();
+      }
+      // WebSocket 在后台断开且已进入离线模式，网络可用则主动触发重连，
+      // 否则用户切回前台续播时无响应且无任何报错
+      if (!this.ttsa?.getStatus() && this.status === AvatarStatus.offline && NetworkMonitor.ONLINE) {
+        (window as any).avatarSDKLogger.warn(this.TAG, "切回前台发现连接已断开，主动触发重连");
+        this.onlineMode();
       }
       // tab 切换回来时，恢复音频捕获的 AudioContext
       if (this.captureAudioCtx && this.captureAudioCtx.state === 'suspended') {
@@ -1350,7 +1367,7 @@ export default class XmovAvatar {
     // 薄客户端模式：通知 server 端销毁，然后清理本地资源
     if (this._isClientMode) {
       this._apiForwarder?.destroy(stop_reason);
-      this.destroyClient();
+      await this.destroyClient();
       this.onStatusChange(AvatarStatus.close);
       return;
     }
@@ -1358,8 +1375,8 @@ export default class XmovAvatar {
     this.ttsa?.sendSdkPoint('close_session', {
       reason: stop_reason,
     });
-    this.destroyClient();
     const res = await this.resourceManager.stopSession(stop_reason);
+    await this.destroyClient();
     if(res) {
       this.onStatusChange(AvatarStatus.close);
     }
@@ -1480,6 +1497,8 @@ export default class XmovAvatar {
     });
     this.incompleteInitializationCleanupPromise = (async () => {
       try {
+        // 先等待房间释放完成，再清理本地资源，避免房间泄漏
+        await stopSessionPromise;
         await this.destroyClient();
       } catch (error) {
         (window as any).avatarSDKLogger.warn(this.TAG, '清理初始化未完成的本地资源时出错', error);

package/src/modules/ResourceManager.ts

@@ -17,7 +17,7 @@ import CacheManager from './cache-manager';
 type TOptions = Pick<
   IAvatarOptions,
   "appId" | "appSecret" | "gatewayServer" | 'cacheServer' | "sdkInstance" | "config" | "headers" | "gateway_type" | "tag" |
-  "asr_id" | "llm_id" | "session_speak_req_id"
+  "asr_id" | "llm_id" | "session_speak_req_id" | "audioOnlyMode"
 > & {
   sessionRequestData?: Record<string, unknown>
   onNetworkInfo(quality: INetworkInfo): void
@@ -205,12 +205,14 @@ export default class ResourceManager {
   private isProcessingVideo = false; // 防止在视频处理过程中清理缓存
   private cacheServer?: CacheManager;
   private startSessionTimer: any = null;
+  private audioOnlyMode: boolean = false;
 
   // 新增：正在下载的视频跟踪
   private downloadingVideos = new Map<string, Promise<ArrayBuffer | undefined>>();
   first_load = true;
   constructor(options: TOptions) {
     this.options = options;
+    this.audioOnlyMode = options.audioOnlyMode || false;
     this.sdk = options.sdkInstance as XmovAvatar;
     this.mouthShapeLib = {
       char_info: null,
@@ -303,9 +305,15 @@ export default class ResourceManager {
     }, 100);
     // http 请求算 10 进度
     const result = await this.startSession();
-    // 如果在 startSession 过程中被销毁了，直接返回，避免继续加载资源
+    const res = result as unknown as ISessionResponse;
+    // 先记录 session_id，确保后续 stopSession 能正确释放房间
+    if (res?.session_id) {
+      this.session_id = res.session_id;
+    }
+    // 如果在 startSession 过程中被销毁了，释放刚创建的房间并返回，避免房间泄漏
     if (this.destroyed) {
       (window as any).avatarSDKLogger.warn(this.TAG, "sdk destroyed during load, aborting after startSession");
+      await this.stopSession("destroy_during_init");
       return null;
     }
     if (!result) {
@@ -318,15 +326,15 @@ export default class ResourceManager {
     this.startSessionTimer = null;
     this.progress = 15;
     onDownloadProgress?.(this.progress);
-    const res = result as unknown as ISessionResponse;
-    this.session_id = res?.session_id;
     this.resource_pack = res.resource_pack;
     this.config = res.config as any;
     this.offlineIdle = res.resource_pack?.offline_idle || []
     if (this.resource_pack) {
-      await this.loadMouthShapeLib(onDownloadProgress);
+      if(!this.audioOnlyMode) {
+        await this.loadMouthShapeLib(onDownloadProgress);
+      }
       this.getBackgroundImage();
-      if (!this.mouthShapeLib?.char_info && res?.resource_pack?.face_ani_char_data) {
+      if (!this.mouthShapeLib?.char_info && res?.resource_pack?.face_ani_char_data && !this.audioOnlyMode) {
         return null
       }
     }
@@ -838,6 +846,11 @@ export default class ResourceManager {
     }
     const res = result as unknown as ISessionResponse;
     this.session_id = res?.session_id;
+    // 重连过程中被销毁，释放刚创建的房间，避免房间泄漏
+    if (this.destroyed) {
+      await this.stopSession("destroy_during_reload");
+      return null;
+    }
     this.resource_pack = res.resource_pack;
     this.config = res.config as any;
     this.offlineIdle = res.resource_pack?.offline_idle || []

package/src/modules/decoder.ts

@@ -279,12 +279,32 @@ export default class ParallelDecoder {
 
   _startWorker(file: bodyFile) {
     const taskId = this.currentTaskId;
-    const worker = new Worker(workerURL);
+    let worker: Worker;
+    try {
+      worker = new Worker(workerURL);
+    } catch (err) {
+      this.reportMessage({
+        code: EErrorCode.INIT_WORKER_ERROR,
+        message: '初始化视频抽帧Worker失败',
+        e: err as object,
+      });
+      return;
+    }
     const id = `${file.body_id ?? file.id ?? 0}_${file.name}`;
     const data = file.data;
     const dataCopy = new ArrayBuffer(data.byteLength);
     new Uint8Array(dataCopy).set(new Uint8Array(data));
 
+    // 监听 Worker 运行时错误（脚本加载/解析失败等）
+    worker.addEventListener("error", (err) => {
+      if (taskId !== this.currentTaskId) return;
+      this.reportMessage({
+        code: EErrorCode.INIT_WORKER_ERROR,
+        message: '视频抽帧Worker运行时错误',
+        e: err as object,
+      });
+    });
+
     const onMessage = (e: MessageEvent) => {
       if (taskId !== this.currentTaskId) return; // 只处理当前任务
       if (e.data.type === "frame") {
@@ -335,6 +355,19 @@ export default class ParallelDecoder {
         }
         this._tryStartNext();
       } else if (e.data.type === "error") {
+        // 根据 Worker 上报的 error 内容区分错误码
+        // Worker 中有两处 postMessage({ type: 'error' }):
+        //   1. VideoDecoder error 回调 → 视频抽帧错误 (VIDEO_FRAME_EXTRACT_ERROR)
+        //   2. 解码配置不支持 → 视频流处理错误 (PROCESS_VIDEO_STREAM_ERROR)
+        const errorMsg = e.data.error ?? '';
+        const code = errorMsg.includes('不支持')
+          ? EErrorCode.PROCESS_VIDEO_STREAM_ERROR
+          : EErrorCode.VIDEO_FRAME_EXTRACT_ERROR;
+        this.reportMessage({
+          code,
+          message: errorMsg || '视频解码错误',
+          e: { fileName: file.name, error: errorMsg } as object,
+        });
         const task = this.tasks.get(id);
         if (task) {
           task.status = "error";

package/src/view/DebugOverlay.ts

@@ -71,12 +71,17 @@ export class DebugOverlay {
   }
 
   public show(): void {
-    if (this.container) {
+    if (!this.container) {
+      this.createOverlay();
+    }
+    if(this.container) {
       this.container.style.display = "block";
-      return;
     }
-    this.createOverlay();
-    this.updateInterval = window.setInterval(() => this.updateTextOnly(), 200);
+    // 重启定时器：hide() 会清除 updateInterval，再次 show 时需要重建
+    // 否则界面显示但内容永不刷新
+    if (!this.updateInterval) {
+      this.updateInterval = window.setInterval(() => this.updateTextOnly(), 200);
+    }
     this.updateTextOnly();
   }