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

package/package.json

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

package/src/control/RenderScheduler.ts

@@ -854,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 || []