@xmov/avatar 2.0.0-alpha.46 → 2.0.0-alpha.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-alpha.46",
+  "version": "2.0.0-alpha.48",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",

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/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,
@@ -857,6 +854,16 @@ export default class RenderScheduler {
     this.audioRenderer.resume();
   }
 
+  /**
+   * app 切后台时暂停音频并清空对齐状态（复用断网离线时的 pause()）
+   * 不能保留缓存续播：Android 后台视频帧号持续递增而音频停留在暂停位置，
+   * 恢复后音画基准脱节；且后台期间可能下发新 speak 数据，旧缓存与新 sf 冲突。
+   * 恢复后依赖新下发音频的 sf 作为 firstFrameIndex 重新对齐
+   */
+  pauseForBackground() {
+    this.audioRenderer.pause();
+  }
+
   /**
    * 设置数字人canvas的显隐状态
    * @param visible 是否可见

package/src/index.ts

@@ -1040,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') {
@@ -1351,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;
     }
@@ -1359,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);
     }
@@ -1481,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

@@ -305,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) {
@@ -320,8 +326,6 @@ 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 || []
@@ -842,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";