@xmov/avatar 2.0.0-alpha.38

package/src/index.ts

@@ -0,0 +1,1920 @@
+import { AvatarStatus, RenderState, IAvatarOptions, IInitParams, InitModel, Layout, WalkConfig } from "./types/index";
+import { EErrorCode } from "./types/error";
+import { EFrameDataType, IRawFrameData, StateChangeInfo, SYNC_FRAME_DATA } from "./types/frame-data";
+import RenderScheduler from "./control/RenderScheduler";
+import ResourceManager, { ISessionResponse, TDownloadProgress } from "./modules/ResourceManager";
+import WidgetDefaultRender from "./modules/TrackRenderer/render-implements";
+import Ttsa from "./control/ttsa";
+import { DebugOverlay } from "./view/DebugOverlay";
+import NetworkMonitor from './modules/network';
+import Errors from './modules/error-handle';
+
+import { performanceConstant } from "./utils/perfermance";
+import  './utils/logger.js';
+import { IBRAnimationGeneratorCharInfo_NN, unpackIBRAnimation, formatMJT } from './utils/DataInterface'
+import { getVertices, getWavefrontObjFromVertices, getPCATextures } from './utils/GLPipelineDebugTools'
+import { GLDevice } from './utils/GLDevice'
+import { GLPipeline } from './utils/GLPipeline'
+import { getDeviceInfo, isharmony, isSupportMES, validateScaleWithDecimal } from "./utils";
+import { StreamingClient } from './control/StreamingClient';
+import { VideoPlayer } from './control/VideoPlayer';
+import { EventDispatcher } from './control/EventDispatcher';
+import { APIForwarder } from './control/APIForwarder';
+import { checkCapability } from './utils/capability-checker';
+import { FPSStats } from "./utils/fpsTracker";
+import { PcmWebMEncoder } from './encoding/pcm-webm-encoder';
+import { MediaRecorderEncoder } from './encoding/media-recorder-encoder';
+
+type InternalAvatarOptions = IAvatarOptions & {
+  sessionRequestData?: Record<string, unknown>
+}
+
+export default class XmovAvatar {
+  //static STATUS: AvatarStatus | -1 = -1;
+
+  private options!: IAvatarOptions;
+
+  private TAG = "[XMOV AVATAR]";
+  private el: HTMLElement | null = null;
+  
+  // 实例状态，每个 XmovAvatar 实例都有自己独立的状态
+  private status: AvatarStatus | -1 = -1;
+
+  // 使用 ! 操作符告诉 TypeScript 这些属性会在构造函数中被初始化
+  private resourceManager!: ResourceManager;
+  private renderScheduler!: RenderScheduler;
+  private networkMonitor: NetworkMonitor | null = null;
+  private ttsa: Ttsa | null = null;
+
+  private debugOverlay: DebugOverlay | null = null;
+
+  private _offlineTimer = -1
+  private readonly _offlineInterval = 300
+  private _env = "production"
+  // 可以与隐身模式做联动，
+  private avatarCanvasVisible: boolean = true; // 数字人canvas显隐状态，默认为true
+  private pendingInvisibleMode: boolean = false; // 待处理的隐身模式（在init时设置，在start时应用）
+  private isInitialized: boolean = false; // 初始化是否完成（progress === 100）
+  public onStateChange: (state: string) => void = () => {};
+
+  public onDownloadProgress: TDownloadProgress | null = null;
+
+  static IBRAnimationGeneratorCharInfo_NN = IBRAnimationGeneratorCharInfo_NN;
+  static unpackIBRAnimation = unpackIBRAnimation;
+  static formatMJT = formatMJT;
+  static getVertices = getVertices;
+  static getPCATextures = getPCATextures;
+  static getWavefrontObjFromVertices = getWavefrontObjFromVertices;
+  static GLDevice = GLDevice;
+  static GLPipeline = GLPipeline;
+  static checkCapability = checkCapability;
+  private boundVisibilityChange: () => void;
+  private replayData: any = null;
+  private startConnectTime: number = 0;
+  private connectSuccessTime: number = 0;
+  private sessionResTime: number = 0;
+  private charbinResTime: number = 0;
+  private isfirstReceive: boolean = true;
+  private enableClientInterrupt: boolean = false; // 是否开启客户端打断
+  private retryCount = 1;
+  private retryTimer = -1;
+  private maxRetryCount = 9;
+  private retryRound = 1; // 重试轮次
+  private maxRetryRound = 3; // 最大轮次
+  private isRetrying = false; // 重试中锁，避免并发调用
+  private isStartRetry = false;
+  private destroyed = false;
+  private incompleteInitializationCleanupPromise: Promise<void> | null = null;
+
+  // 音频捕获相关（用于 ASR 回声消除）
+  private captureAudioCtx: AudioContext | null = null;
+  private captureWorklet: AudioWorkletNode | null = null;
+  private captureSource: MediaElementAudioSourceNode | null = null;
+  private captureSetupPromise: Promise<void> | null = null;
+  private captureLastSpeechId: number = -2;
+  private restartPlaybackCaptureImpl: (() => void) | null = null;
+  private captureEncodeQueue: Promise<void> = Promise.resolve();
+  private captureGeneration = 0;
+
+  // PCM 捕获相关（raw_audio=true 模式）
+  private pcmCaptureLastSpeechId: number = -2;
+  private pcmCaptureFirstChunk: boolean = true;
+  private pcmWebMEncoder: PcmWebMEncoder | null = null;
+  private mediaRecorderEncoder: MediaRecorderEncoder | null = null;
+  private pcmCaptureMode: 'webcodec' | 'mediarecorder' | 'none' = 'none';
+  private pcmEncodeId: number = 0; // 用于 reset 竞态检测，递增标识当前编码会话
+
+  private reconnectDebounceTimer = -1; // 重连防抖定时器
+  private networkInfo: any = {
+    rtt: 0,
+    downlink: 0.0,
+    networkStatus: false,
+  };
+
+  private mediaRecorder: MediaRecorder | null = null;
+  private recordedChunks: Blob[] = [];
+  private stream: MediaStream | null = null;
+
+  // 薄客户端模式相关字段
+  private _isClientMode: boolean = false;
+  private _streamingClient: StreamingClient | null = null;
+  private _videoPlayer: VideoPlayer | null = null;
+  private _eventDispatcher: EventDispatcher | null = null;
+  private _apiForwarder: APIForwarder | null = null;
+  private _clientOnDownloadProgress: ((progress: number) => void) | null = null;
+  private _pendingInit: boolean = false;
+  private _pendingInitConfig: any = null;
+  private _clientSessionId: string = '';
+
+  constructor(options: IAvatarOptions) {
+    (window as any).avatarSDKLogger.setEnabled(options.enableLogger);
+    this.options = options;
+    this._env = options.env || "production"
+    this.enableClientInterrupt = options.enableClientInterrupt || false;
+    this.boundVisibilityChange = this.visibilitychange.bind(this);
+
+    // 薄客户端模式：跳过所有重量级初始化，仅准备容器
+    if (options.renderMode === 'client') {
+      this._isClientMode = true;
+      this.initializeClient(options);
+      return;
+    }
+
+    // 完整渲染模式（原有逻辑）
+    this.initializeSDK(options);
+    this.networkMonitor = new NetworkMonitor({
+      offlineCallback: (message) => {
+        this.onMessage({
+          code: EErrorCode.NETWORK_DOWN,
+          message: message || '网络断开',
+        });
+        console.log('网络断开（network off）', message);
+        
+        // 如果初始化未完成（progress < 100），清除所有已初始化的资源并断开连接
+        if (!this.isInitialized) {
+          (window as any).avatarSDKLogger.warn(this.TAG, '初始化未完成时断网，清除所有资源并断开连接');
+          void this.cleanupBeforeInitComplete("network_offline_before_init");
+          return;
+        }
+        
+        if(this.status !== AvatarStatus.offline) {
+          // 无网断开则进入离线模式
+          this.offlineHandle();
+        }
+      },
+      onlineCallback: (message) => {
+        this.onMessage({
+          code: EErrorCode.NETWORK_UP,
+          message: message || '网络恢复',
+        });
+        
+        // 如果初始化未完成（progress < 100），清除所有已初始化的资源并断开连接
+        if (!this.isInitialized) {
+          (window as any).avatarSDKLogger.warn(this.TAG, '网络恢复但初始化未完成，清除所有资源并断开连接');
+          void this.cleanupBeforeInitComplete("network_online_before_init");
+          return;
+        }
+        
+        // 网络恢复时，取消WebSocket的reconnectTimer，避免与网络恢复的重连逻辑冲突
+        this.ttsa?.clearReconnectTimer();
+        
+        if(this.isStartRetry) {
+          this.triggerReconnect(); 
+        }
+        // this.onStatusChange(AvatarStatus.network_on)
+        // this._reload()
+        // this.ttsa?.connect()
+      },
+      // retryCallback: (count: number) => {
+      //   this.onMessage({
+      //     code: EErrorCode.NETWORK_RETRY,
+      //     message: '网络重试中',
+      //   });
+      //   this.ttsa?.connect();
+        // return this.resourceManager._startSession();
+      // },
+    })
+  }
+
+  public getStatus() {
+    return this.status
+  }
+
+  public get businessENV() {
+    return this._env
+  }
+
+  public getUniqueSpeakId() {
+    return this.ttsa?.getUniqueSpeakId() || `0-${this.getSessionId()}`
+
+  }
+
+  private async initializeSDK(options: IAvatarOptions) {
+    if (!navigator.onLine) {
+      this.onMessage({
+        code: EErrorCode.NETWORK_BREAK,
+        message: '没有网络，请联网后重试',
+      });
+      return
+    }
+    const self = this;
+    const internalOptions = options as InternalAvatarOptions;
+    const { containerId, container, appId, appSecret, gatewayServer, cacheServer, config } = options;
+
+    const {scale = 1} = config?.layout?.avatar ?? {}
+    if(config?.layout?.avatar?.scale){
+      config.layout.avatar.scale = validateScaleWithDecimal(scale, "initializeSDK") as number | string;
+    }
+    const _config = { ...(config || {}), raw_audio: !isSupportMES() };
+
+    if(container && container instanceof HTMLElement){
+      this.el = container as HTMLElement;
+    } else {
+      const el = document.querySelector(containerId) as HTMLElement;
+      if (!el) {
+        this.onMessage({
+          code: EErrorCode.CONTAINER_NOT_FOUND,
+          message: `containerId: ${containerId} 不存在`,
+        })
+        return;
+      }
+      this.el = el;
+    }
+    const bgContainer = document.createElement("div");
+    bgContainer.setAttribute("id", "avatar-bg-container");
+    bgContainer.setAttribute("style", "position:absolute;top:0;left:0;width:100%;height:100%;z-index:0;opacity:0;");
+    this.el.appendChild(bgContainer);
+    const style = this.el.getAttribute("style");
+    if (style) {
+      this.el.setAttribute(
+        "style",
+        `position:relative;overflow:hidden;${style}`
+      );
+    } else {
+      this.el.setAttribute(
+        "style",
+        `position:relative;overflow:hidden;`
+      );
+    }
+    this.resourceManager = new ResourceManager({
+      sdkInstance: this,
+      headers: options.headers,
+      tag: options.tag,
+      gateway_type: options.gateway_type || 'default',
+      asr_id: options.asr_id,
+      llm_id: options.llm_id,
+      session_speak_req_id: options.session_speak_req_id,
+      sessionRequestData: internalOptions.sessionRequestData,
+      appId,
+      appSecret,
+      gatewayServer,
+      cacheServer,
+      config:_config,
+      onNetworkInfo(networkInfo) {
+        self.networkInfo = networkInfo;
+        options.onNetworkInfo?.(networkInfo);
+      },
+      onStartSessionWarning: (message: Object) => {
+        this.options.onStartSessionWarning?.(message);
+      },
+    });
+
+    this.renderScheduler = new RenderScheduler({
+      sdkInstance: this,
+      container: this.el,
+      resourceManager: this.resourceManager,
+      enableDebugger: options.enableDebugger,
+      hardwareAcceleration: options.hardwareAcceleration || "default",
+      enableClientInterrupt: this.enableClientInterrupt,
+      audioOnlyMode: options.audioOnlyMode || false,
+      onDownloadProgress: (progress: number) => {
+        this.onDownloadProgress?.(progress);
+        this.el?.setAttribute("style", this.el?.style.cssText + `opacity:${progress === 100 ? '1' : '0'};`);
+        // 标记初始化完成
+        this.isInitialized = progress === 100;
+        if(progress === 100) {
+          this.resourceManager._setOfflineCache();
+          this.ttsa?.sendSdkPoint('loadvideo_decode_time', {
+            timestamp: Date.now(),
+          });
+          setTimeout(() => {
+            this.ttsa?.sendDeviceInfo({
+              ...getDeviceInfo(),
+              ...(window as any).performanceTracker.getFirstInfo(),
+              // @ts-ignore
+              sdk_version: VERSION,
+              resolution: this.resourceManager.getConfig()?.resolution,
+              download_speed: self.networkInfo.downlink || 0,
+            })
+          }, 20);
+          // 初始化音频捕获（MSE 模式下，用于 ASR 回声消除）
+          void this.enableAudioPlaybackCapture();
+        }
+      },
+      onStateChange: (state: string) => {
+        if((this.getStatus() === AvatarStatus.offline && state !== 'idle') || state === "") {
+          return
+        }
+        options.onStateChange?.(state);
+      },
+      onRenderChange: (state: RenderState, oldState?: RenderState) => {
+        options.onRenderChange?.(state);
+        // 在如果数字人在恢复渲染态一会和数字人在线态的时候，数字人进入渲染中了，都应该认为是可见状态
+        if(state === RenderState.rendering && (oldState === RenderState.resumed || this.getStatus() === AvatarStatus.online) && this.isInitialized) {
+          (window as any).avatarSDKLogger.log(this.TAG, 'Status:===== 渲染中，状态: rendering', this.getSessionId());
+          this.onStatusChange(AvatarStatus.visible)
+        }
+      },
+      onVoiceStateChange: (state: string, duration?: number, client_speak_id?: string | number) => {
+        options.onVoiceStateChange?.(state, duration, client_speak_id);
+      },
+      onWalkStateChange: (state: string) => {
+        options.onWalkStateChange?.(state);
+      },
+      sendVideoInfo: (info: {name: string, body_id: number, id: number}) => {
+        this.debugOverlay?.setVideoInfo(info);
+      },
+      onSpeakStateChange: (state: string, client_speak_id: string | number) => {
+        options.onSpeakStateChange?.(state, client_speak_id);
+      },
+      setAudioInfo: (info: {
+        sf: number;
+        ef: number;
+        ad: Uint8Array;
+      }) => {
+        this.debugOverlay?.setAudioInfo(info);
+      },
+      setEventData: (info: {
+        sf: number;
+        ef: number;
+        event: Array<any>;
+      }) => {
+        this.debugOverlay?.setEventData(info);
+      },
+      renderFrameCallback: (frame: number) => {
+        this.renderFrameCallback(frame);
+        this.handleReplaySend(frame);
+      },
+      reportMessage: (message: {
+        code: EErrorCode;
+        message: string;
+        e?: object;
+      }) => {
+        this.onMessage(message);
+      },
+      sendSdkPoint: (type: string, data: any, extra?: any) => {
+        this.ttsa?.sendSdkPoint(type, data, extra);
+      },
+      sendMessage: (type: string, payload: any) => {
+        this.ttsa?.send(type, payload);
+      },
+      onFPSUpdate: (stats: FPSStats) => {
+        options.onFPSUpdate?.(stats);
+      },
+      onFrameDataUpdate: (data) => {
+        options.onFrameDataUpdate?.(data);
+      },
+    });
+    options.onStateRenderChange && (window as any).performanceTracker.setOnStateRenderChange(options.onStateRenderChange);
+
+    
+    if(config?.walk_config){
+      this.changeWalkConfig(config.walk_config)
+    }
+    if(config?.layout) {
+      this.changeLayout(config.layout);
+    }
+    WidgetDefaultRender.CUSTOM_WIDGET = options.onWidgetEvent;
+    WidgetDefaultRender.PROXY_WIDGET = options.proxyWidget || {};
+  }
+
+  /**
+   * 薄客户端模式初始化：创建容器、StreamingClient、VideoPlayer、EventDispatcher、APIForwarder
+   */
+  private initializeClient(options: IAvatarOptions) {
+    const { containerId, container } = options;
+
+    // 准备容器
+    if (container && container instanceof HTMLElement) {
+      this.el = container;
+    } else {
+      const el = document.querySelector(containerId) as HTMLElement;
+      if (!el) {
+        this.options.onMessage?.({ code: EErrorCode.CONTAINER_NOT_FOUND, message: `containerId: ${containerId} 不存在` } as any);
+        return;
+      }
+      this.el = el;
+    }
+    const style = this.el.getAttribute("style");
+    if (style) {
+      this.el.setAttribute("style", `position:relative;overflow:hidden;${style}`);
+    } else {
+      this.el.setAttribute("style", "position:relative;overflow:hidden;");
+    }
+
+    // 创建 EventDispatcher
+    this._eventDispatcher = new EventDispatcher({
+      onStateChange: options.onStateChange,
+      onSpeakStateChange: options.onSpeakStateChange,
+      onVoiceStateChange: options.onVoiceStateChange,
+      onStatusChange: options.onStatusChange,
+      onRenderChange: options.onRenderChange,
+      onWalkStateChange: options.onWalkStateChange,
+      onWidgetEvent: options.onWidgetEvent,
+      onMessage: options.onMessage,
+      onNetworkInfo: options.onNetworkInfo,
+      onFPSUpdate: options.onFPSUpdate,
+      onFrameDataUpdate: options.onFrameDataUpdate,
+      onDownloadProgress: (progress: number) => {
+        this._clientOnDownloadProgress?.(progress);
+        if (progress >= 100 && !this.isInitialized) {
+          this.isInitialized = true;
+        }
+      },
+      onSessionId: (sessionId: string) => {
+        this._clientSessionId = sessionId;
+        (window as any).avatarSDKLogger.log(this.TAG, '[client] 收到 session_id:', sessionId);
+      },
+    });
+
+    const streamingUrl = options.streamingServer || `ws://${location.hostname}:8080`;
+
+    // 创建 StreamingClient
+    this._streamingClient = new StreamingClient({
+      url: streamingUrl,
+      onReady: () => {
+        (window as any).avatarSDKLogger.log(this.TAG, '[client] 双方就绪，等待 Server 推流...');
+        // 如果 init() 在 WebSocket 连接前被调用，在此补发
+        if (this._pendingInit) {
+          this._pendingInit = false;
+          const config = this._pendingInitConfig;
+          this._pendingInitConfig = null;
+          (window as any).avatarSDKLogger.log(this.TAG, '[client] 补发 init 命令');
+          this._apiForwarder?.init(config);
+        }
+      },
+      onOffer: (sdp: string) => {
+        this._videoPlayer?.handleOffer(sdp);
+      },
+      onIce: (candidate: RTCIceCandidateInit) => {
+        this._videoPlayer?.addIceCandidate(candidate);
+      },
+      onEventProxy: (eventType: string, data: any, serverFrame?: number) => {
+        this._eventDispatcher?.dispatch(eventType, data, serverFrame);
+      },
+      onError: (error: string) => {
+        this.options.onMessage?.({ code: EErrorCode.NETWORK_DOWN, message: error } as any);
+      },
+      onDisconnect: () => {
+        this.onStatusChange(AvatarStatus.offline);
+      },
+    });
+
+    // 创建 VideoPlayer
+    this._videoPlayer = new VideoPlayer({
+      container: this.el,
+      streamingClient: this._streamingClient,
+      useAlphaMask: options.useAlphaMask,
+      onConnected: () => {
+        (window as any).avatarSDKLogger.log(this.TAG, '[client] WebRTC 已连接');
+        this.onStatusChange(AvatarStatus.online);
+      },
+      onDisconnected: () => {
+        this.onStatusChange(AvatarStatus.offline);
+      },
+    });
+
+    // 创建 APIForwarder
+    this._apiForwarder = new APIForwarder(this._streamingClient);
+
+    // 连接信令
+    this._streamingClient.connect();
+
+    window.addEventListener('beforeunload', this.handleBeforeUnload);
+  }
+
+  // async preCache() {
+  //   return this.resourceManager.preCache(this.options.appId, this.options.appSecret);
+  // }
+
+  private renderFrameCallback(frame: number) {
+    // 间隔24帧执行一次
+    if(!this.ttsa?.getStatus() && ![AvatarStatus.offline].includes(this.status as AvatarStatus) && frame % 24 === 0) {
+      this.offlineHandle()
+    }
+  }
+
+  async init(params: IInitParams): Promise<ISessionResponse | null | undefined> {
+    // 浏览器能力检查
+    const capabilityReport = await checkCapability(this.options.audioOnlyMode);
+    if (!capabilityReport.supported) {
+      const fatalItems = capabilityReport.items.filter(i => i.severity === 'fatal' && !i.supported);
+      const errorMsg = `浏览器能力检查失败: ${fatalItems.map(i => i.reason).join('; ')}`;
+      this.onMessage({
+        code: EErrorCode.INIT_ERROR,
+        message: errorMsg,
+      });
+      return;
+    }
+
+    this.destroyed = false;
+    this.isInitialized = false; // 重置初始化状态
+    this.incompleteInitializationCleanupPromise = null;
+    this.startConnectTime = Date.now();
+
+    // 薄客户端模式：保存进度回调，通知 server 端开始初始化，等待 server 的 download_progress 事件
+    if (this._isClientMode) {
+      this._clientOnDownloadProgress = params.onDownloadProgress || null;
+      // 构建发给 server 的配置（排除客户端专用字段）
+      const clientConfig = {
+        appId: this.options.appId,
+        appSecret: this.options.appSecret,
+        gatewayServer: this.options.gatewayServer,
+        cacheServer: this.options.cacheServer,
+        headers: this.options.headers,
+        tag: this.options.tag,
+        gateway_type: this.options.gateway_type,
+        env: this.options.env,
+        config: this.options.config,
+        hardwareAcceleration: this.options.hardwareAcceleration,
+        enableDebugger: this.options.enableDebugger,
+        initModel: params.initModel,
+        scaleDownBy: this.options.scaleDownBy || 1,
+        useAlphaMask: this.options.useAlphaMask,
+      };
+      // 发送 init 命令通知 server 端初始化数字人
+      // 如果 WebSocket 尚未连接，暂存等 onReady 时补发
+      if (this._streamingClient?.isConnected()) {
+        this._apiForwarder?.init(clientConfig);
+      } else {
+        this._pendingInit = true;
+        this._pendingInitConfig = clientConfig;
+        (window as any).avatarSDKLogger.log(this.TAG, '[client] WebSocket 未连接，init 命令暂存');
+      }
+      return;
+    }
+
+    const { onDownloadProgress, initModel } = params;
+    this.onDownloadProgress = (progress: number) => {
+      if(progress === 15) {
+        this.sessionResTime = Date.now();
+      }
+      if(progress === 80) {
+        this.charbinResTime = Date.now();
+      }
+      onDownloadProgress(progress);
+    };
+
+    // 如果初始化时指定了隐身模式，先标记待处理，等start时再真正应用
+    if(initModel === InitModel.invisible) {
+      this.pendingInvisibleMode = true;
+    }
+
+    // 加载资源
+    (window as any).performanceTracker.markStart(performanceConstant.load_resource);
+    (window as any).performanceTracker.markStart(performanceConstant.first_avatar_render);
+    (window as any).performanceTracker.markStart(performanceConstant.first_webgl_render);
+    const sessionInfo = await this.resourceManager.load(this.onDownloadProgress.bind(this));
+    // 如果在load过程中被销毁了，直接返回，避免继续初始化
+    if(this.destroyed) {
+      (window as any).avatarSDKLogger.warn(this.TAG, "sdk destroyed during load, aborting after resourceManager load");
+      return
+    };
+    if(!sessionInfo?.socket_io_url || !sessionInfo?.token) {
+      (window as any).avatarSDKLogger.error(this.TAG, "init error, socket_io_url or token is empty reload");
+      return
+    };
+    this.connectSuccessTime = Date.now();
+    (window as any).performanceTracker.markEnd(performanceConstant.load_resource);
+    this.debugOverlay = new DebugOverlay(this, sessionInfo);
+
+    this.ttsa = this.connectTtsa(sessionInfo)
+    this.renderScheduler.init();
+    // 同步初始canvas显隐状态
+    this.renderScheduler.setAvatarCanvasVisible(this.avatarCanvasVisible);
+    // 设置上报使用ttsa
+    (window as any).performanceTracker.setReportFunc(this.ttsa);
+
+    window.addEventListener('beforeunload', this.handleBeforeUnload);
+    document.addEventListener('visibilitychange', this.boundVisibilityChange);
+    return sessionInfo;
+  }
+
+  /**
+   * 初始化音频捕获（MSE 模式）
+   * 通过 AudioContext.createMediaElementSource 接管 <audio> 元素输出，
+   * 按 1600 samples 分桶后使用 WebCodecs 编码为 opus (WebM 容器)，
+   * 并回调给业务侧用于 ASR 回声消除（AEC）。
+   *
+   * 架构：
+   * - AudioWorklet 负责 100ms 分桶和静音检测
+   * - WebCodecs AudioEncoder + WebMMuxer 负责 opus/WebM 编码
+   * - 每次 speak 会话的首段音频自动包含 WebM 容器头（isFirstChunk=true）
+   *
+   * 注意：
+   * - createMediaElementSource 对同一个 audio 元素只能调用一次
+   * - 接管后必须手动 connect 到 destination，否则音频不会播放
+   * - MSE 播放器 stop 时只销毁 MediaSource，audio 元素不变，捕获绑定不受影响
+   */
+  protected setAudioPlaybackDataHandler(handler?: IAvatarOptions["onAudioPlaybackData"]) {
+    this.options.onAudioPlaybackData = handler;
+  }
+
+  protected restartAudioPlaybackCapture() {
+    this.restartPlaybackCaptureImpl?.();
+  }
+
+  protected enableAudioPlaybackCapture() {
+    if (!this.options.onAudioPlaybackData) {
+      return Promise.resolve();
+    }
+    if (!this.captureSetupPromise) {
+      if (this.resourceManager?.config.raw_audio) {
+        // PCM 模式：通过 capture worklet 捕获并编码
+        this.captureSetupPromise = this.setupPCMCapture().finally(() => {
+          this.captureSetupPromise = null;
+        });
+      } else {
+        // MSE/WebM 模式：通过 AudioWorklet 分桶并用 WebCodecs 编码
+        this.captureSetupPromise = this.setupAudioCapture().finally(() => {
+          this.captureSetupPromise = null;
+        });
+      }
+    }
+    return this.captureSetupPromise;
+  }
+
+  private async setupAudioCapture() {
+    const audioEl = document.getElementById('xmov-avatar-audio') as HTMLAudioElement;
+    if (!audioEl || !this.options.onAudioPlaybackData) return;
+    if (this.captureAudioCtx || this.captureSource) return;
+
+    // 检查 AudioWorkletNode 支持
+    if (typeof (window as any).AudioWorkletNode === 'undefined') {
+      this.onMessage({
+        code: EErrorCode.INIT_ERROR,
+        message: '当前浏览器不支持 AudioWorkletNode，无法启用音频捕获（ASR 回声消除）',
+      });
+      return;
+    }
+
+    try {
+      if (!await PcmWebMEncoder.isSupported()) {
+        this.onMessage({
+          code: EErrorCode.INIT_ERROR,
+          message: '当前浏览器不支持 WebCodecs AudioEncoder Opus，无法启用 100ms 双路音频',
+        });
+        return;
+      }
+      this.pcmWebMEncoder = new PcmWebMEncoder();
+      await this.pcmWebMEncoder.init();
+
+      // 创建 16kHz 采样率的 AudioContext（farend 协议要求）
+      this.captureAudioCtx = new AudioContext({ sampleRate: 16000 });
+      if (this.captureAudioCtx.sampleRate !== 16000) {
+        throw new Error(`浏览器无法创建 16000 Hz AudioContext: ${this.captureAudioCtx.sampleRate}`);
+      }
+      this.captureSource = this.captureAudioCtx.createMediaElementSource(audioEl);
+
+      // 路由到扬声器（必须连接，否则无声）
+      this.captureSource.connect(this.captureAudioCtx.destination);
+
+      let isRecording = false;
+      let isFirstEmit = true;
+      let captureStartedAt = 0;
+      let captureSequence = 0;
+      const startCapture = (sessionId: number) => {
+        const generation = ++this.captureGeneration;
+        isRecording = true;
+        isFirstEmit = true;
+        captureStartedAt = Date.now() - 100;
+        captureSequence = 0;
+        this.captureLastSpeechId = sessionId;
+        this.captureEncodeQueue = this.captureEncodeQueue.then(() => {
+          if (generation === this.captureGeneration) {
+            this.pcmWebMEncoder?.reset();
+          }
+        });
+      };
+
+      const stopCapture = () => {
+        const generation = ++this.captureGeneration;
+        isRecording = false;
+        this.captureLastSpeechId = -2;
+        this.captureEncodeQueue = this.captureEncodeQueue.then(() => {
+          if (generation === this.captureGeneration) {
+            this.pcmWebMEncoder?.reset();
+          }
+        });
+      };
+
+      this.restartPlaybackCaptureImpl = () => {
+        if (isRecording) {
+          startCapture(this.renderScheduler.getSpeechId());
+        }
+      };
+
+      // 创建 AudioWorkletProcessor 脚本（在音频线程中运行）
+      // 缓冲 1600 个采样点（100ms @ 16kHz），直接回传 S16LE PCM。
+      const processorCode = `
+        class AudioCaptureProcessor extends AudioWorkletProcessor {
+          constructor() {
+            super();
+            this.buffer = new Float32Array(1600); // 100ms @ 16kHz
+            this.bufferIndex = 0;
+          }
+
+          process(inputs, outputs) {
+            for (const output of outputs) {
+              for (const channel of output) channel.fill(0);
+            }
+            const input = inputs[0];
+            if (input && input.length > 0 && input[0] && input[0].length > 0) {
+              const frameCount = input[0].length;
+
+              for (let i = 0; i < frameCount; i++) {
+                let sample = 0;
+                for (let channel = 0; channel < input.length; channel++) {
+                  sample += input[channel][i] || 0;
+                }
+                this.buffer[this.bufferIndex++] = sample / input.length;
+
+                // 缓冲区满 1600 采样点时，检测静音并发送到主线程
+                if (this.bufferIndex >= 1600) {
+                  // 检测是否全是静音（全零或极低值）
+                  let hasAudio = false;
+                  for (let j = 0; j < 1600; j++) {
+                    if (Math.abs(this.buffer[j]) > 0.0001) {
+                      hasAudio = true;
+                      break;
+                    }
+                  }
+
+                  const pcm = new Int16Array(1600);
+                  for (let j = 0; j < 1600; j++) {
+                    const value = Math.max(-1, Math.min(1, this.buffer[j]));
+                    pcm[j] = value < 0 ? value * 0x8000 : value * 0x7fff;
+                  }
+                  this.port.postMessage(
+                    { hasAudio: hasAudio, pcmData: pcm.buffer },
+                    [pcm.buffer]
+                  );
+                  this.bufferIndex = 0;
+                }
+              }
+            }
+            return true;
+          }
+        }
+        registerProcessor('audio-capture-processor', AudioCaptureProcessor);
+      `;
+
+      // 通过 Blob URL 加载 processor
+      const blob = new Blob([processorCode], { type: 'application/javascript' });
+      const processorUrl = URL.createObjectURL(blob);
+      await this.captureAudioCtx.audioWorklet.addModule(processorUrl);
+      URL.revokeObjectURL(processorUrl);
+
+      // 创建 AudioWorkletNode（仅用于静音检测，不连接 destination）
+      this.captureWorklet = new AudioWorkletNode(
+        this.captureAudioCtx,
+        'audio-capture-processor'
+      );
+      this.captureSource.connect(this.captureWorklet);
+      this.captureWorklet.connect(this.captureAudioCtx.destination);
+
+      this.captureEncodeQueue = Promise.resolve();
+      this.captureWorklet.port.onmessage = (e) => {
+        if (!this.options.onAudioPlaybackData) return;
+
+        const { hasAudio, pcmData } = e.data as { hasAudio: boolean; pcmData: ArrayBuffer };
+        const speechId = this.renderScheduler.getSpeechId();
+
+        if (hasAudio && !isRecording) {
+          startCapture(speechId);
+        } else if (hasAudio && isRecording && speechId !== this.captureLastSpeechId) {
+          startCapture(speechId);
+        } else if (!hasAudio && isRecording) {
+          stopCapture();
+        }
+        if (!hasAudio || !isRecording || !(pcmData instanceof ArrayBuffer)) return;
+
+        const generation = this.captureGeneration;
+        const firstChunk = isFirstEmit;
+        isFirstEmit = false;
+        const blockStartedAt = captureStartedAt + captureSequence * 100;
+        captureSequence += 1;
+        this.captureEncodeQueue = this.captureEncodeQueue
+          .then(async () => {
+            const buffer = await this.pcmWebMEncoder?.encode(new Int16Array(pcmData));
+            if (!buffer || buffer.byteLength === 0 || generation !== this.captureGeneration) return;
+            this.options.onAudioPlaybackData?.({
+              data: buffer,
+              codec: 'opus',
+              isFirstChunk: firstChunk,
+              sampleRate: 16000,
+              samples: 1600,
+              timestamp: blockStartedAt,
+              speech_id: speechId,
+            });
+          })
+          .catch((error) => {
+            (window as any).avatarSDKLogger?.error(
+              this.TAG,
+              '[AudioCapture] PCM/WebCodecs 编码失败:',
+              error
+            );
+          });
+      };
+
+      // 处理 AudioContext 挂起（浏览器自动播放策略）
+      if (this.captureAudioCtx.state === 'suspended') {
+        await this.captureAudioCtx.resume();
+      }
+      if (this.captureAudioCtx.state !== 'running') {
+        throw new Error('AudioContext 未运行，无法启动 farend PCM 捕获');
+      }
+
+      (window as any).avatarSDKLogger?.log(
+        this.TAG,
+        '[AudioCapture] 初始化成功，采样率:',
+        this.captureAudioCtx.sampleRate,
+        'Hz，opus 编码 (WebM 容器)'
+      );
+    } catch (e) {
+      this.captureGeneration++;
+      this.restartPlaybackCaptureImpl = null;
+      if (this.captureWorklet) {
+        try {
+          this.captureWorklet.port.onmessage = null;
+          this.captureWorklet.disconnect();
+        } catch {}
+        this.captureWorklet = null;
+      }
+      try {
+        this.captureSource?.disconnect();
+      } catch {}
+      this.captureSource = null;
+      if (this.captureAudioCtx && this.captureAudioCtx.state !== 'closed') {
+        await this.captureAudioCtx.close().catch(() => undefined);
+      }
+      this.captureAudioCtx = null;
+      void this.pcmWebMEncoder?.destroy();
+      this.pcmWebMEncoder = null;
+      (window as any).avatarSDKLogger?.error(
+        this.TAG,
+        '[AudioCapture] 初始化失败:',
+        e
+      );
+    }
+  }
+
+  /**
+   * 初始化 PCM 模式音频捕获（raw_audio=true 时使用）
+   * 通过 PCMAudioPlayer 的 capture worklet 拦截音频输出，
+   * 经 WebCodecs 或 MediaRecorder 编码为 WebM/Opus 后回调给业务侧
+   */
+  private async setupPCMCapture() {
+    if (!this.options.onAudioPlaybackData) return;
+
+    const audioPlayer = this.renderScheduler.getAudioRenderer()?.getAudioPlayer();
+    if (!audioPlayer) {
+      (window as any).avatarSDKLogger?.error(
+        this.TAG, '[PCMCapture] PCMAudioPlayer 未就绪'
+      );
+      return;
+    }
+
+    // 运行时检测编码能力，选择编码路径
+    const webCodecsSupported = await PcmWebMEncoder.isSupported();
+    const mediaRecorderSupported = MediaRecorderEncoder.isSupported();
+
+    if (!webCodecsSupported && !mediaRecorderSupported) {
+      (window as any).avatarSDKLogger?.warn(
+        this.TAG, '[PCMCapture] 当前浏览器不支持 Opus 编码（WebCodecs 和 MediaRecorder 均不可用），跳过 PCM 捕获'
+      );
+      this.onMessage({
+        code: EErrorCode.INIT_ERROR,
+        message: '当前浏览器不支持 Opus 编码，PCM 模式下无法启用音频捕获（ASR 回声消除）',
+      });
+      return;
+    }
+
+    try {
+      if (webCodecsSupported) {
+        // 首选路径：WebCodecs AudioEncoder
+        this.pcmWebMEncoder = new PcmWebMEncoder();
+        await this.pcmWebMEncoder.init();
+        this.pcmCaptureMode = 'webcodec';
+      } else {
+        // 降级路径：MediaRecorder
+        this.mediaRecorderEncoder = new MediaRecorderEncoder();
+        await this.mediaRecorderEncoder.init();
+        this.pcmCaptureMode = 'mediarecorder';
+      }
+
+      this.restartPlaybackCaptureImpl = () => {
+        this.pcmCaptureFirstChunk = true;
+        this.pcmCaptureLastSpeechId = this.renderScheduler.getSpeechId();
+        this.pcmEncodeId++;
+        this.pcmWebMEncoder?.reset();
+        this.mediaRecorderEncoder?.reset();
+        audioPlayer.resetCaptureBuffer();
+      };
+
+      await audioPlayer.attachCapture(async ({ pcmData, hasAudio }) => {
+        try {
+          if (!this.options.onAudioPlaybackData) return;
+          const blockStartedAt = Date.now() - 100;
+
+          // 音频未播放时丢弃数据（speak_end 后 capture worklet 可能还有尾巴数据）
+          if (!audioPlayer.isPlaying) {
+            audioPlayer.resetCaptureBuffer();
+            return;
+          }
+
+          const speechId = this.renderScheduler.getSpeechId();
+
+          // 会话变化时重置
+          if (speechId !== this.pcmCaptureLastSpeechId) {
+            this.pcmCaptureFirstChunk = true;
+            this.pcmCaptureLastSpeechId = speechId;
+            this.pcmEncodeId++; // 递增编码会话 ID
+            this.pcmWebMEncoder?.reset();
+            this.mediaRecorderEncoder?.reset();
+            // 清空 capture worklet 内部缓冲区，避免打断后旧音频数据混入新 session
+            audioPlayer.resetCaptureBuffer();
+          }
+
+          // 静音时不发送
+          if (!hasAudio) return;
+
+          // 记录当前编码会话 ID（用于竞态检测）
+          const currentEncodeId = this.pcmEncodeId;
+
+          let webmData: ArrayBuffer | null = null;
+          const startTime = performance.now();
+
+          if (this.pcmCaptureMode === 'webcodec' && this.pcmWebMEncoder) {
+            // WebCodecs 路径：PCM → Opus → WebM
+            const pcm = new Int16Array(pcmData);
+            webmData = await this.pcmWebMEncoder.encode(pcm);
+            
+            // 竞态检测：如果 reset 已被调用，丢弃这个结果
+            if (currentEncodeId !== this.pcmEncodeId) {
+              (window as any).avatarSDKLogger?.log(
+                this.TAG, '[PCMCapture] 丢弃过期编码数据（编码会话已重置）'
+              );
+              return;
+            }
+            
+            if (webmData.byteLength === 0) return;
+            
+            // 性能监控
+            const encodeTime = performance.now() - startTime;
+            if (encodeTime > 10) {
+              (window as any).avatarSDKLogger?.warn(
+                this.TAG, `[PCMCapture] WebCodecs 编码耗时过长: ${encodeTime.toFixed(2)}ms`
+              );
+            }
+          } else if (this.pcmCaptureMode === 'mediarecorder' && this.mediaRecorderEncoder) {
+            // MediaRecorder 降级路径
+            webmData = await this.mediaRecorderEncoder.feedPCM(pcmData);
+            
+            // 竞态检测
+            if (currentEncodeId !== this.pcmEncodeId) {
+              (window as any).avatarSDKLogger?.log(
+                this.TAG, '[PCMCapture] 丢弃过期编码数据（编码会话已重置）'
+              );
+              return;
+            }
+            
+            if (!webmData) return; // 首次启动无数据
+            
+            // 性能监控
+            const encodeTime = performance.now() - startTime;
+            if (encodeTime > 10) {
+              (window as any).avatarSDKLogger?.warn(
+                this.TAG, `[PCMCapture] MediaRecorder 编码耗时过长: ${encodeTime.toFixed(2)}ms`
+              );
+            }
+          }
+
+          if (!webmData) return;
+
+          const firstChunk = this.pcmCaptureFirstChunk;
+          this.pcmCaptureFirstChunk = false;
+
+          // 回调（格式与 MSE 模式完全一致）
+          this.options.onAudioPlaybackData({
+            data: webmData,
+            codec: 'opus',
+            isFirstChunk: firstChunk,
+            sampleRate: 16000,
+            samples: 1600,
+            timestamp: blockStartedAt,
+            speech_id: speechId,
+          });
+        } catch (error) {
+          (window as any).avatarSDKLogger?.error(
+            this.TAG, '[PCMCapture] 捕获回调错误:', error
+          );
+        }
+      });
+
+      (window as any).avatarSDKLogger?.log(
+        this.TAG, `[PCMCapture] PCM 捕获初始化成功，编码路径: ${this.pcmCaptureMode}`
+      );
+    } catch (e) {
+      (window as any).avatarSDKLogger?.error(
+        this.TAG, '[PCMCapture] PCM 捕获初始化失败:', e
+      );
+      void this.pcmWebMEncoder?.destroy();
+      this.pcmWebMEncoder = null;
+      this.mediaRecorderEncoder?.destroy();
+      this.mediaRecorderEncoder = null;
+      this.pcmCaptureMode = 'none';
+    }
+  }
+
+  visibilitychange() {
+    if (document.hidden) {
+      // this.offlineMode()
+      // tab 回来时，强制同步解帧队列
+      // this.renderScheduler.forceSyncDecoder();
+    } else {
+      if (this.ttsa?.getStatus()) {
+        this.renderScheduler.forceSyncDecoder();
+      }
+      // tab 切换回来时，恢复音频捕获的 AudioContext
+      if (this.captureAudioCtx && this.captureAudioCtx.state === 'suspended') {
+        this.captureAudioCtx.resume().catch(() => {});
+      }
+    }
+  }
+
+  setReplayData(data: any) {
+    this.replayData = data;
+  }
+
+  handleReplaySend(frame: number) {
+    if(!this.replayData) {
+      return;
+    }
+    const frameReplayData = this.replayData.filter((item: any) => (Number(item.client_frame_number) === frame && item.event_type !== "sdk_burial_point"));
+    for(const item of frameReplayData) {
+      if(item.event_type === 'state_change') {
+        this.ttsa?.stateChange(item.event_data.state, item.event_data.params);
+      }else if(item.event_type === 'send_text') {
+        this.speak(item.event_data.ssml, item.event_data.is_start, item.event_data.is_end, item.event_data.extra);
+
+      }else {
+        (window as any).avatarSDKLogger.log(this.TAG, `[handleReplaySend] 未知事件类型: ${item}`);
+      }
+    }
+  }
+
+  // 初始化 ttsa
+  private connectTtsa(sessionInfo: ISessionResponse) {
+    (window as any).performanceTracker.markStart(performanceConstant.ttsa_connect);
+    (window as any).performanceTracker.markStart(performanceConstant.ttsa_ready);
+    return new Ttsa({
+      sdkInstance: this,
+      url: sessionInfo.socket_io_url,
+      room: sessionInfo.room,
+      session_id: sessionInfo.session_id,
+      token: sessionInfo.token,
+      framedata_proto_version: this.resourceManager.getConfig().framedata_proto_version,
+      reconnect_client_timeout: sessionInfo?.reconnect_client_timeout || 0,
+      appInfo: {
+        ...this.resourceManager.getAppInfo(),
+        env: this._env
+      },
+      onReady: () => {
+        this.ttsa?.sendSdkPoint('connect_sdk', {
+          timestamp: this.startConnectTime,
+        });
+        this.onDownloadProgress?.(85);
+        this.ttsa?.sendSdkPoint('connect_sdk_success', {
+          timestamp: this.connectSuccessTime,
+        });
+        this.ttsa?.sendSdkPoint('session_processing_time', {
+          timestamp: this.sessionResTime,
+        });
+        this.ttsa?.sendSdkPoint('Char_bin_download_time', {
+          timestamp: this.charbinResTime,
+        });
+        this.ttsa?.sendSdkPoint('socket_connect_time', {
+          timestamp: Date.now(),
+        });
+        this.onTtsaReady(sessionInfo)
+        this.ttsa?.syncTimestamp();
+      },
+      handleMessage: (type: EFrameDataType, data: IRawFrameData[] | SYNC_FRAME_DATA) => {
+        if(this.isfirstReceive && type === EFrameDataType.BODY) {
+          this.ttsa?.sendSdkPoint('body_completed_first_time', {
+            timestamp: Date.now(),
+          });
+          this.isfirstReceive = false;
+        }
+        // 处理下行数据
+        this.renderScheduler.handleData(type, data);
+      },
+      handleAAFrame: (data: any) => {
+        this.options.onAAFrameHandle?.(data);
+      },
+      runStartFrameIndex: (client_time: number) => {
+        this.renderScheduler.runStartFrameIndex();
+      },
+      ttsaStateChangeHandle: (state: StateChangeInfo) => {
+        this.renderScheduler.ttsaStateChangeHandle(state);
+      },
+      reloadSuccess: () => {
+        this.reloadSuccess()
+      },
+      enterOfflineMode: () => {
+        this.offlineHandle()
+      },
+      reStartSDK: () => {
+        this.reStartSession()
+      },
+      sendVoiceEnd: () => {
+        this.renderScheduler?.sendVoiceEnd();
+      },
+      getCurrentFrameIndex: () => {
+        return this.renderScheduler?.getCurrentFrameIndex()??0;
+      }
+    });
+  }
+
+  protected start() {
+    this.renderScheduler.render();
+    this.ttsa?.start();
+    
+    // 如果初始化时设置了隐身模式，则立即进入隐身状态
+    if (this.pendingInvisibleMode) {
+      this.pendingInvisibleMode = false;
+      this.setInvisibleMode()
+    } else {
+      this.onStatusChange(AvatarStatus.online);
+    }
+    
+  }
+
+  protected onTtsaReady(_sessionInfo?: ISessionResponse) {
+    this.start();
+  }
+
+  private async _reload() {
+    const res = await this.resourceManager._reload();
+    if (res && !this.destroyed) {
+      await this.onSessionReloaded(res);
+      if (this.destroyed) {
+        return null;
+      }
+      this.ttsa = this.connectTtsa(res);
+      this.ttsa._setResumeInfoCallback(
+        this.resourceManager._getSessionId(),
+        this.renderScheduler._getResumeInfo.bind(this.renderScheduler)
+      )
+    }
+    return res;
+  }
+
+  protected async onSessionReloaded(_sessionInfo: ISessionResponse): Promise<void> {}
+
+  protected onSessionReloadExhausted(_error?: unknown): void {}
+
+  protected async restartSessionForTransport(reason: string): Promise<void> {
+    this.renderScheduler.interrupt("in_offline_mode");
+    await this.resourceManager.stopSession(reason);
+    if (this.destroyed) {
+      return;
+    }
+    this.ttsa?.close();
+    if (this.status !== AvatarStatus.offline) {
+      this.offlineHandle();
+    }
+    this.reStartSession();
+  }
+
+  protected cancelSessionRestart(): void {
+    this.resetRetryState();
+    this.clearAllRetryTimers();
+  }
+
+  reloadSuccess() {
+    this.onStatusChange(AvatarStatus.online);
+    setTimeout(() => {
+      window.clearInterval(this._offlineTimer)
+    }, 1000)
+  }
+
+  protected async stop() {
+    await this.renderScheduler.stop();
+  }
+
+  private handleBeforeUnload = () => {
+    this.destroy("beforeunload");
+  };
+
+  public isDestroyed() {
+    return this.destroyed;
+  }
+
+  public async destroyClient() {
+    // 增加重复销毁检查，避免重复销毁导致的异常
+    if (this.destroyed) {
+      (window as any).avatarSDKLogger.warn(this.TAG, "SDK 已销毁，忽略重复销毁请求");
+      return;
+    }
+    this.destroyed = true;
+
+    // 薄客户端模式：清理薄客户端相关资源
+    if (this._isClientMode) {
+      if (this._streamingClient) {
+        this._streamingClient.destroy();
+        this._streamingClient = null;
+      }
+      if (this._videoPlayer) {
+        this._videoPlayer.destroy();
+        this._videoPlayer = null;
+      }
+      this._eventDispatcher = null;
+      this._apiForwarder = null;
+      this.el = null;
+      window.removeEventListener("beforeunload", this.handleBeforeUnload);
+      (window as any).avatarSDKLogger.log(this.TAG, "薄客户端 SDK 已销毁");
+      return;
+    }
+    
+    this.cancelSessionRestart();
+    
+    // 清理离线模式定时器
+    if (this._offlineTimer !== -1) {
+      clearInterval(this._offlineTimer);
+      this._offlineTimer = -1;
+    }
+
+    // 停止TTSA连接
+    if (this.ttsa) {
+      this.ttsa.close();
+      this.ttsa = null;
+    }
+
+    // 停止渲染调度器
+    if (this.renderScheduler) {
+      this.renderScheduler.destroy();
+    }
+
+    // 清理资源管理器（包括缓存）
+    if (this.resourceManager) {
+      this.resourceManager.destroy();
+    }
+
+    // 清理调试浮层
+    if (this.debugOverlay) {
+      this.debugOverlay.destroy();
+      this.debugOverlay = null;
+    }
+    // 主动断开需要销毁网络监听相关事件
+    // 增加状态检查和异常捕获，避免重复销毁 networkMonitor
+    if(this.networkMonitor) {
+      try {
+        this.networkMonitor.destroy();
+        this.networkMonitor = null; // 标记已销毁
+      } catch (e) {
+        (window as any).avatarSDKLogger.warn(this.TAG, '销毁 networkMonitor 时出错', e);
+      }
+    }
+
+    // 清理音频捕获资源
+    this.pcmEncodeId++;
+    this.captureGeneration++;
+    this.restartPlaybackCaptureImpl = null;
+    if (this.captureWorklet) {
+      try {
+        this.captureWorklet.port.onmessage = null;
+        this.captureWorklet.disconnect();
+      } catch {}
+      this.captureWorklet = null;
+    }
+    if (this.captureSource) {
+      try {
+        this.captureSource.disconnect();
+      } catch {}
+      this.captureSource = null;
+    }
+    if (this.captureAudioCtx) {
+      try {
+        this.captureAudioCtx.close();
+      } catch {}
+      this.captureAudioCtx = null;
+    }
+
+    // 清理 PCM 捕获资源
+    const audioPlayer = this.renderScheduler?.getAudioRenderer()?.getAudioPlayer();
+    if (audioPlayer) {
+      audioPlayer.detachCapture();
+    }
+    void this.pcmWebMEncoder?.destroy();
+    this.pcmWebMEncoder = null;
+    this.mediaRecorderEncoder?.destroy();
+    this.mediaRecorderEncoder = null;
+    this.pcmCaptureLastSpeechId = -2;
+    this.pcmCaptureFirstChunk = true;
+    this.pcmCaptureMode = 'none';
+
+    // 清理DOM元素
+    this.el = null;
+    this.startConnectTime = 0;
+    this.connectSuccessTime = 0;
+    this.sessionResTime = 0;
+    this.charbinResTime = 0;
+    this.isfirstReceive = true;
+    this.networkInfo = {
+      rtt: 0,
+      downlink: 0.0,
+      networkStatus: false,
+    };
+
+    window.removeEventListener("beforeunload", this.handleBeforeUnload);
+    document.removeEventListener("visibilitychange", this.boundVisibilityChange);
+
+    (window as any).avatarSDKLogger.log(this.TAG, "SDK 已销毁");
+  }
+
+  public async destroy(stop_reason: string = "user"): Promise<void> {
+    this.replayData = null;
+
+    // 薄客户端模式：通知 server 端销毁，然后清理本地资源
+    if (this._isClientMode) {
+      this._apiForwarder?.destroy(stop_reason);
+      this.destroyClient();
+      this.onStatusChange(AvatarStatus.close);
+      return;
+    }
+
+    this.ttsa?.sendSdkPoint('close_session', {
+      reason: stop_reason,
+    });
+    this.destroyClient();
+    const res = await this.resourceManager.stopSession(stop_reason);
+    if(res) {
+      this.onStatusChange(AvatarStatus.close);
+    }
+    return res
+  }
+
+  idle() {
+    if (this._isClientMode) { this._apiForwarder?.idle(); return; }
+    if(this.enableClientInterrupt) {
+      this.renderScheduler.interrupt("idle");
+    }
+    this.ttsa?.idle();
+  }
+
+  listen() {
+    if (this._isClientMode) { this._apiForwarder?.listen(); return; }
+    if(this.enableClientInterrupt) {    
+      this.renderScheduler.interrupt("listen");
+    }
+    this.ttsa?.listen();
+  }
+
+  think() {
+    if (this._isClientMode) { this._apiForwarder?.think(); return; }
+    if(this.enableClientInterrupt) {    
+      this.renderScheduler.interrupt("think");
+    }
+    this.ttsa?.think();
+  }
+  interactiveidle() {
+    if (this._isClientMode) { this._apiForwarder?.interactiveidle(); return; }
+    if(this.enableClientInterrupt) {    
+      this.renderScheduler.interrupt("interactiveidle");
+    }
+    this.ttsa?.interactiveidle();
+  }
+
+  speak(ssml: string, is_start: boolean = true, is_end: boolean = true, extra = {client_speak_id: '', client_frame: 0}): string | undefined{
+    if (this._isClientMode) { this._apiForwarder?.speak(ssml, is_start, is_end, extra); return; }
+    if(this.enableClientInterrupt && is_start) {
+      this.renderScheduler.interrupt("speak");
+    }
+    extra.client_frame = this.renderScheduler?.getCurrentFrameIndex()??0;
+    const uniqueSpeakId = this.ttsa?.sendText(ssml, is_start, is_end, extra);
+    this.renderScheduler.resume();
+    return uniqueSpeakId;
+  }
+
+  setOffsetFrame(offsetFrame: number) {
+    this.renderScheduler.setOffsetFrame(offsetFrame);
+  }
+
+  // 主动同步时间戳
+  syncTimestamp() {
+    this.ttsa?.sendSyncTimestamp(this.renderScheduler?.getCurrentFrameIndex()??0);
+  }
+
+  /**
+     * 通知后端进入隐身模式
+     */
+  private notifyEnterInvisibleMode(): void {
+    this.ttsa?.enterInvisibleMode();
+  }
+
+  /**
+   * 通知后端退出隐身模式
+   */
+  private notifyExitInvisibleMode(): void {
+    this.ttsa?.exitInvisibleMode();
+  }
+
+  setVolume(volume: number) {
+    if (this._isClientMode) { this._apiForwarder?.setVolume(volume); return; }
+    this.renderScheduler.setVolume(volume);
+  }
+
+  getSessionId() {
+    if (this._isClientMode) {
+      return this._clientSessionId;
+    }
+    return this.resourceManager?.session_id;
+  }
+
+  // 显示调试浮层
+  public showDebugInfo() {
+    if (!this.debugOverlay) {
+      return;
+    }
+    this.debugOverlay?.show();
+  }
+
+  // 隐藏调试浮层
+  public hideDebugInfo() {
+    this.debugOverlay?.hide();
+  }
+
+  // 改变数字人canvas的显隐状态
+  public changeAvatarVisible(visible: boolean) {
+    this.avatarCanvasVisible = visible;
+    if (this._isClientMode) { this._apiForwarder?.changeAvatarVisible(visible); return; }
+    this.renderScheduler?.setAvatarCanvasVisible(visible);
+  }
+
+  /**
+   * 在初始化未完成时清理所有已初始化的资源
+   * @param reason 清理原因
+   */
+  protected cleanupBeforeInitComplete(reason: string): Promise<void> {
+    if (this.incompleteInitializationCleanupPromise) {
+      return this.incompleteInitializationCleanupPromise;
+    }
+
+    (window as any).avatarSDKLogger.warn(this.TAG, `清理初始化未完成的资源，原因: ${reason}`);
+    this.isInitialized = false;
+    const stopSessionPromise = this.resourceManager?.stopSession(reason);
+    void stopSessionPromise?.catch((error) => {
+      (window as any).avatarSDKLogger.warn(this.TAG, '停止初始化未完成的会话时出错', error);
+    });
+    this.incompleteInitializationCleanupPromise = (async () => {
+      try {
+        await this.destroyClient();
+      } catch (error) {
+        (window as any).avatarSDKLogger.warn(this.TAG, '清理初始化未完成的本地资源时出错', error);
+      }
+    })();
+    return this.incompleteInitializationCleanupPromise;
+  }
+
+  protected reportInitializationFailure(message: string, cause?: unknown) {
+    this.onMessage({
+      code: EErrorCode.INIT_ERROR,
+      message,
+      e: cause as any,
+    });
+  }
+
+  private offlineHandle() {
+    this.onStatusChange(AvatarStatus.offline)
+    this.renderScheduler._offlineMode()
+    this._offlineTimer = window.setInterval(() => {
+      if(this.status !== AvatarStatus.offline) {
+        clearInterval(this._offlineTimer);
+        this._offlineTimer = -1;
+        return
+      }
+      this.renderScheduler._offlineRun()
+    }, this._offlineInterval)
+  }
+
+  public async stopSessionFromSocket(reason: string) {
+    await this.resourceManager.stopSession(reason)
+  }
+
+  offlineMode() {
+    // this.networkMonitor.setState(false)
+    this.renderScheduler.interrupt("in_offline_mode")
+    this.resourceManager.stopSession("offline_mode")
+    this.ttsa?.close()
+    this.offlineHandle()
+  }
+
+  onlineMode() {
+    if (!NetworkMonitor.ONLINE) {
+      return
+    }
+    // this.networkMonitor.setState(true)
+    this._reload()
+  }
+
+  onMessage(params: Parameters<typeof Errors>[0]) {
+    // 添加 session_id
+    try {
+      if (typeof params.e !== 'object' || params.e === null) {
+        params.e = { msg: params.e };
+      }
+      params.session_id = this.getSessionId();
+    } catch (e) {
+      (window as any).avatarSDKLogger.warn(this.TAG, '获取 session_id 时出错', e);
+    }
+    const e = Errors(params)
+    if(params.code !== EErrorCode.RENDER_BODY_ERROR && params.code !== EErrorCode.RENDER_FACE_ERROR && params.code !== EErrorCode.BODY_DATA_EXPIRED) {
+      this.options.onMessage(e)
+    }
+    this.ttsa?.send("client_error", params);
+    this.debugOverlay?.addError(e)
+  }
+
+  onStatusChange(status: AvatarStatus) {
+    if(status === this.status) {
+      return
+    }
+    this.status = status
+    this.options.onStatusChange?.(status)
+  }
+
+  /**
+   * 切换隐身模式（暂停/恢复音视频实时渲染）
+   */
+  public switchInvisibleMode(): void {
+    if (this._isClientMode) { this._apiForwarder?.switchInvisibleMode(); return; }
+    if (!this.renderScheduler) {
+      (window as any).avatarSDKLogger?.warn(
+        this.TAG,
+        'RenderScheduler 未初始化，无法切换隐身模式'
+      );
+      return;
+    }
+    
+      // 如果当前数字人状态是在线 或者 visible，切换到暂停时
+      if (this.status === AvatarStatus.visible || this.status === AvatarStatus.online ) {
+        this.setInvisibleMode()
+      } else {
+        this.notifyExitInvisibleMode();
+        this.renderScheduler.switchInvisibleMode();
+        this.listen();
+    }
+  }
+  private setInvisibleMode() {
+      // 先调用 interactiveidle()
+      this.interactiveidle();
+      this.renderScheduler.switchInvisibleMode();
+      this.notifyEnterInvisibleMode();
+      this.onStatusChange(AvatarStatus.invisible);
+  }
+  public getPendingInvisibleMode() {
+    return this.pendingInvisibleMode || false;
+  }
+  /**
+   * 获取当前渲染状态
+   */
+  public getRenderState(): RenderState {
+    if (!this.renderScheduler) {
+      return RenderState.init;
+    }
+    return this.renderScheduler.getRenderState();
+  }
+
+  changeLayout(layout: Layout) {
+    if (this._isClientMode) { this._apiForwarder?.changeLayout(layout); return; }
+    const {scale = 1} = layout.avatar || {}
+    layout.avatar.scale = validateScaleWithDecimal(scale, "changeLayout") as number | string;
+    this.ttsa?.changeLayout(layout);
+    this.renderScheduler.setCharacterCanvasLayout(layout);
+  }
+
+  changeWalkConfig(walkConfig: WalkConfig) {
+    if (this._isClientMode) { this._apiForwarder?.changeWalkConfig(walkConfig); return; }
+    this.ttsa?.changeWalkConfig(walkConfig)
+    this.renderScheduler.setWalkConfig(walkConfig);
+  }
+  
+  interrupt(type: string):number {
+    if (this._isClientMode) { this._apiForwarder?.interrupt(type); return 0; }
+    return this.renderScheduler.interrupt(type)
+  }
+
+  private triggerReconnect() {
+    // 如果已经在重连中，直接返回，避免重复触发
+    if (this.isRetrying) {
+      (window as any).avatarSDKLogger.warn(this.TAG, "正在重连中，跳过本次触发");
+      return;
+    }
+
+    if (this.reconnectDebounceTimer !== -1) {
+      clearTimeout(this.reconnectDebounceTimer);
+      this.reconnectDebounceTimer = -1;
+    }
+    if (this.retryTimer !== -1) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = -1;
+    }
+
+    this.reconnectDebounceTimer = window.setTimeout(() => {
+      this.isRetrying = false;
+      this.retryCount = 1;
+      this.retryRound = 1;
+      this.reStartSession();
+      this.reconnectDebounceTimer = -1;
+    }, 100);
+  }
+
+  reStartSession() {
+    if (this.isRetrying || this.retryRound > this.maxRetryRound) return;
+
+    this.clearAllRetryTimers();
+
+    // 标记重试状态
+    this.isStartRetry = true;
+    this.isRetrying = true;
+
+    // 使用非递归方式实现重试逻辑
+    this._retryImpl();
+  }
+
+  private async _retryImpl() {
+    if (this.retryRound > this.maxRetryRound || !this.isRetrying) {
+      return;
+    }
+
+    let delay = 1000;
+    if (this.retryCount > 1) {
+      delay = Math.pow(2, this.retryCount) * 1000;
+    }
+
+    // 使用setTimeout代替递归，避免调用栈溢出
+    setTimeout(async () => {
+      if (!this.isRetrying || this.destroyed) {
+        return;
+      }
+      try {
+        const result = await this._reload();
+        if (!this.isRetrying || this.destroyed) {
+          return;
+        }
+        if (result === null) {
+          // 重试失败：判断本轮是否达上限
+          if (this.retryCount >= this.maxRetryCount) {
+            // 本轮次数用尽，判断是否达最大轮次
+            if (this.retryRound >= this.maxRetryRound) {
+              // 总次数用尽（3*9=27次），停止重试
+              (window as any).avatarSDKLogger.warn(
+                this.TAG, 
+                `重试达最大轮次(${this.maxRetryRound})+每轮最大次数(${this.maxRetryCount})，总次数=${this.maxRetryRound*this.maxRetryCount}，停止重试`
+              );
+              this.onSessionReloadExhausted();
+              this.resetRetryState(); // 完全重置状态
+              return;
+            } else {
+              // 未达最大轮次：重置本轮计数，轮次+1
+              (window as any).avatarSDKLogger.warn(
+                this.TAG, 
+                `第${this.retryRound}轮重试次数达上限(${this.maxRetryCount})，进入第${this.retryRound+1}轮重试`
+              );
+              this.retryCount = 1; // 重置本轮计数
+              this.retryRound += 1; // 轮次+1
+            }
+          } else {
+            // 本轮未达上限：计数+1
+            this.retryCount += 1;
+          }
+          // 继续重试
+          this._retryImpl();
+        } else {
+          // 重试成功：完全重置所有状态
+          this.renderScheduler.stopAudio(-1);
+          (window as any).avatarSDKLogger.log(
+            this.TAG, 
+            `第${this.retryRound}轮第${this.retryCount}次重试成功，停止重试`
+          );
+          this.resetRetryState();
+        }
+      } catch (error) {
+        // 异常处理：逻辑同失败场景
+        (window as any).avatarSDKLogger.error(this.TAG, "重试过程异常", error);
+        if (this.retryCount >= this.maxRetryCount) {
+          if (this.retryRound >= this.maxRetryRound) {
+            (window as any).avatarSDKLogger.warn(
+              this.TAG, 
+              `重试异常且达总次数上限(${this.maxRetryRound*this.maxRetryCount})，停止重试`
+            );
+            this.onSessionReloadExhausted(error);
+            this.resetRetryState();
+            return;
+          } else {
+            this.retryCount = 1;
+            this.retryRound += 1;
+          }
+        } else {
+          this.retryCount += 1;
+        }
+        // 仅当未达最大轮次时，继续重试
+        if (this.retryRound <= this.maxRetryRound && this.isRetrying) {
+          this._retryImpl();
+        } else {
+          this.resetRetryState();
+        }
+      }
+    }, delay);
+  }
+  private clearAllRetryTimers() {
+    // 清理重连防抖定时器
+    if (this.reconnectDebounceTimer !== -1) {
+      clearTimeout(this.reconnectDebounceTimer);
+      this.reconnectDebounceTimer = -1;
+    }
+    // 清理重试定时器
+    if (this.retryTimer !== -1) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = -1;
+    }
+  }
+
+  // 统一重置重试状态
+  private resetRetryState() {
+    this.isRetrying = false;
+    this.isStartRetry = false;
+    this.retryCount = 1; // 重置每轮计数
+    this.retryRound = 1; // 重置轮次（关键）
+  }
+
+  public seekToFrame(frame: number) {
+    this.renderScheduler.seekToFrame(frame);
+    this.ttsa?.seekToFrame(frame);
+  }
+
+  public async startRecoder() {
+    try {
+      const canvas = this.el?.querySelector('canvas') as HTMLCanvasElement;
+      const audio = this.el?.querySelector('audio') as HTMLAudioElement;
+
+      if (!canvas || !audio) {
+        console.error('找不到 canvas 或 audio 元素');
+        return;
+      }
+
+      // 画面流
+      const canvasStream = canvas.captureStream(60);
+
+      // 获取音频流：
+      // 如果 setupAudioCapture 已调用 createMediaElementSource，audio 元素的输出
+      // 已被劫持到 Web Audio API，captureStream() 会拿到静音流。
+      // 此时复用已有的 captureSource 节点，追加 MediaStreamDestination 获取音频。
+      let audioTracks: MediaStreamTrack[] = [];
+
+      if (this.captureSource && this.captureAudioCtx) {
+        // 复用 setupAudioCapture 的音频图，追加录制专用输出节点
+        const recorderDestination = this.captureAudioCtx.createMediaStreamDestination();
+        this.captureSource.connect(recorderDestination);
+        audioTracks = recorderDestination.stream.getAudioTracks();
+      } else if (typeof (audio as any).captureStream === 'function') {
+        // audio 未被劫持，直接用 captureStream
+        audioTracks = (audio as any).captureStream().getAudioTracks();
+      } else if (typeof (audio as any).mozCaptureStream === 'function') {
+        audioTracks = (audio as any).mozCaptureStream().getAudioTracks();
+      } else {
+        (window as any).avatarSDKLogger.error('❌ 当前浏览器不支持 captureStream，无法录制音频');
+        return;
+      }
+
+      // 合并流
+      this.stream = new MediaStream([
+        ...canvasStream.getVideoTracks(),
+        ...audioTracks
+      ]);
+
+      // 清空上一次数据
+      this.recordedChunks = [];
+
+      // 创建录制器
+      this.mediaRecorder = new MediaRecorder(this.stream, {
+        mimeType: 'video/mp4',
+        videoBitsPerSecond: 12 * 1024 * 1024, // 12Mbps 超清
+      });
+
+      // 数据收集
+      this.mediaRecorder.ondataavailable = (e) => {
+        if (e.data && e.data.size > 0) {
+          this.recordedChunks.push(e.data);
+        }
+      };
+
+      // 开始录制
+      this.mediaRecorder.start(100); // 100ms 收集一次，避免丢数据
+
+      (window as any).avatarSDKLogger.log('✅ 开始录制');
+    } catch (err) {
+      (window as any).avatarSDKLogger.error('❌ 录制失败：', err);
+    }
+  }
+
+  public stopRecoder() {
+    if (!this.mediaRecorder) return;
+    this.mediaRecorder.stop();
+    this.stream?.getTracks().forEach(track => track.stop());
+    (window as any).avatarSDKLogger.log('⏹ 停止录制');
+  }
+
+  public exportVideo() {
+    // 关键：检查有没有数据
+    if (!this.recordedChunks.length) {
+      (window as any).avatarSDKLogger.error('没有录制到数据');
+      return;
+    }
+
+    const blob = new Blob(this.recordedChunks, { type: 'video/mp4' });
+    const url = URL.createObjectURL(blob);
+
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `录制_${new Date().getTime()}.mp4`;
+    a.click();
+    (window as any).avatarSDKLogger.log('✅ 下载成功，大小：', blob.size);
+  }
+
+  public getOptions() {
+    return this.options;
+  }
+
+  // ── 测试用方法：模拟 WebGL 上下文丢失 ─────────────────────────────
+
+  /**
+   * [测试用] 模拟 WebGL 上下文丢失
+   * 用于测试分阶段恢复策略是否正常工作
+   * 
+   * @param restoreAfterMs 自动恢复上下文的延迟时间（毫秒），默认 5000ms
+   * @param forceFail 强制恢复失败（用于测试 medium/full 阶段的升级逻辑）
+   * 
+   * @example
+   * // 在浏览器控制台执行：
+   * avatar.simulateContextLoss(5000);        // 模拟丢失，5秒后自动恢复
+   * avatar.simulateContextLoss(0, true);     // 模拟丢失，不自动恢复（测试升级逻辑）
+   */
+  public simulateContextLoss(restoreAfterMs: number = 5000, forceFail: boolean = false): void {
+    if (!this.renderScheduler) {
+      (window as any).avatarSDKLogger.warn("[Test] renderScheduler not initialized");
+      return;
+    }
+    this.renderScheduler.simulateContextLoss(restoreAfterMs, forceFail);
+  }
+
+  /**
+   * [测试用] 获取当前 WebGL 上下文恢复状态
+   */
+  public getRecoveryStatus() {
+    if (!this.renderScheduler) {
+      return null;
+    }
+    return this.renderScheduler.getRecoveryStatus();
+  }
+
+  /**
+   * [测试用] 批量测试分阶段恢复
+   * 依次触发多次上下文丢失，观察各阶段的恢复情况
+   */
+  public async testStagedRecovery(): Promise<void> {
+    if (!this.renderScheduler) {
+      (window as any).avatarSDKLogger.warn("[Test] renderScheduler not initialized");
+      return;
+    }
+    return this.renderScheduler.testStagedRecovery();
+  }
+
+  /**
+   * 手动重启 WebGL：创建新 canvas + 新 GLDevice + 新 GLPipeline
+   * 用于分阶段恢复全部失败后的手动恢复
+   * @returns 是否成功
+   *
+   * @example
+   * const ok = avatar.restartWebGL();
+   */
+  public restartWebGL(): boolean {
+    if (!this.renderScheduler) {
+      (window as any).avatarSDKLogger.warn("[restartWebGL] renderScheduler not initialized");
+      return false;
+    }
+    return this.renderScheduler.restartWebGL();
+  }
+}