@spatius/avatarkit 1.3.1-beta.1 → 1.3.1-beta.3

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1-beta.2] - 2026-07-17
+
+### Fixed
+- Fixed playback getting stuck when audio was sent while the connection was still being established and the session later reconnected: the audio clock could freeze, leaving the avatar frozen on a single frame instead of animating in sync with the audio.
+- Fixed the avatar not returning to idle after a playback round finished in that same send-then-connect scenario; it now correctly transitions back to idle when playback ends.
+
 ## [1.3.1-beta.1] - 2026-07-16
 
 ### Changed

package/dist/{StreamingAudioPlayer-BQawYU25.js → StreamingAudioPlayer-CF0Yrsmz.js}

@@ -1,7 +1,7 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-C54v6mHz.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CFPt9NwR.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
@@ -46,6 +46,8 @@ class StreamingAudioPlayer {
     // Default volume 1.0 (0.0 - 1.0)
     // Event callbacks
     __publicField(this, "onEndedCallback");
+    // 音频缓冲卡顿（缓冲耗尽自动暂停 / 有数据自动恢复）通知：true=进入卡顿，false=恢复。
+    __publicField(this, "onAudioStallCallback");
     // AudioContext state management
     __publicField(this, "stateChangeHandler");
     __publicField(this, "isResuming", false);
@@ -156,6 +158,7 @@ class StreamingAudioPlayer {
    * Add audio chunk (16-bit PCM)
    */
   addChunk(pcmData, isLast = false) {
+    var _a;
     if (!this.audioContext) {
       logger.error("AudioContext not initialized");
       return;
@@ -176,6 +179,7 @@ class StreamingAudioPlayer {
     if (this.autoContinue && this.isPaused) {
       this.log("[StreamingAudioPlayer] autoContinue=true, auto-resuming playback");
       this.autoContinue = false;
+      (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, false);
       this.resume().catch((err) => {
         logger.error("Failed to auto-resume playback:", err);
       });
@@ -229,13 +233,13 @@ class StreamingAudioPlayer {
       this.log("[StreamingAudioPlayer] Cannot start playback: Already playing");
       return;
     }
-    await this.ensureAudioContextRunning();
     this.isPlaying = true;
     this.sessionStartTime = this.audioContext.currentTime;
     this.scheduledTime = this.sessionStartTime;
     this.lastScheduledChunkEndTime = 0;
     this.scheduledChunkInfo = [];
     this.autoContinue = false;
+    await this.ensureAudioContextRunning();
     this.log("[StreamingAudioPlayer] Starting playback", {
       sessionStartTime: this.sessionStartTime,
       bufferedChunks: this.audioChunks.length,
@@ -304,18 +308,17 @@ class StreamingAudioPlayer {
       });
       this.activeSources.add(source);
       source.onended = () => {
+        var _a;
         this.activeSources.delete(source);
         if (this.activeSources.size === 0) {
           const lastChunk = this.audioChunks[this.scheduledChunks - 1];
-          if (lastChunk && !lastChunk.isLast) {
+          const sessionEnded = !!(lastChunk == null ? void 0 : lastChunk.isLast);
+          if (!sessionEnded) {
             this.log("All audio chunks ended but end=false, pausing and setting autoContinue");
-            logEvent("audio_buffer_stall", "warning", {
-              scheduled_chunks: this.scheduledChunks,
-              audio_time: this.getCurrentTime()
-            });
+            (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, true);
             this.autoContinue = true;
             this.pause();
-          } else if (isLast) {
+          } else {
             this.log("Last audio chunk ended, marking playback as ended");
             this.markEnded();
           }
@@ -557,6 +560,12 @@ class StreamingAudioPlayer {
   onEnded(callback) {
     this.onEndedCallback = callback;
   }
+  /**
+   * 设置音频缓冲卡顿回调：缓冲耗尽自动暂停时 stalled=true，有数据自动恢复时 stalled=false。
+   */
+  onAudioStall(callback) {
+    this.onAudioStallCallback = callback;
+  }
   /**
    * Check if playing
    */

package/dist/core/AvatarController.d.ts

@@ -46,6 +46,11 @@ export declare class AvatarController {
     private isFallbackMode;
     private frameStarvationEvents;
     private isFrameStarved;
+    private audioStallEvents;
+    private isAudioBufferStalled;
+    private playbackEndReason;
+    private receivedAudioBytes;
+    private receivedAnimationFrames;
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
      * Frame starvation is only possible BEFORE this — once all frames are in, any remaining

package/dist/{index-C54v6mHz.js → index-CFPt9NwR.js}

@@ -11739,7 +11739,7 @@ class ClockSync {
         this.monoAtCalibrate = best.monoAtCalibrate;
         this.calibrated = true;
         if (firstCalibration) this.fireReady();
-        logEvent("time_calibrated", "info", {
+        logMetric("time_calibrated", "info", {
           has_server: true,
           rtt_ms: Math.round(best.rttNet)
         });
@@ -11754,7 +11754,7 @@ class ClockSync {
       this.serverBase = null;
       this.calibrated = true;
       this.fireReady();
-      logEvent("time_calibrated", "info", { has_server: false });
+      logMetric("time_calibrated", "info", { has_server: false });
     } finally {
       this.syncing = false;
     }
@@ -11811,6 +11811,14 @@ class ClockSync {
   }
 }
 const clockSync = new ClockSync();
+const FILTERED_HOSTNAMES = ["localhost", "127.0.0.1", "0.0.0.0"];
+function shouldFilterHostname() {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const hostname = window.location.hostname;
+  return FILTERED_HOSTNAMES.includes(hostname);
+}
 const MARK_KEY = "__mark";
 function monoTimestamp() {
   return { [MARK_KEY]: "mono", value: performance.now() };
@@ -11825,14 +11833,34 @@ function resolveMark(mark) {
   }
 }
 function resolveMarks(contents) {
-  let out = null;
-  for (const [k2, v2] of Object.entries(contents)) {
-    if (isMark(v2)) {
-      if (!out) out = { ...contents };
-      out[k2] = resolveMark(v2);
+  return resolveValue(contents);
+}
+function resolveValue(value) {
+  if (isMark(value)) return resolveMark(value);
+  if (Array.isArray(value)) {
+    let out = null;
+    for (let i2 = 0; i2 < value.length; i2++) {
+      const resolved = resolveValue(value[i2]);
+      if (resolved !== value[i2]) {
+        if (!out) out = [...value];
+        out[i2] = resolved;
+      }
     }
+    return out ?? value;
   }
-  return out ?? contents;
+  if (typeof value === "object" && value !== null) {
+    const obj = value;
+    let out = null;
+    for (const [k2, v2] of Object.entries(obj)) {
+      const resolved = resolveValue(v2);
+      if (resolved !== v2) {
+        if (!out) out = { ...obj };
+        out[k2] = resolved;
+      }
+    }
+    return out ?? value;
+  }
+  return value;
 }
 const OTEL_LOGGER_NAME = "spatius-avatarkit";
 let sdkVersion$1 = "1.0.0";
@@ -11954,6 +11982,7 @@ function flushEventQueue$1() {
   eventQueue$1.length = 0;
 }
 function trackEventOtel(event, level = "info", contents = {}) {
+  if (shouldFilterHostname()) return;
   if (!clockSync.isReady()) {
     preCalibrationQueue.push({ event, level, contents, enqueueMono: performance.now() });
     return;
@@ -12095,14 +12124,6 @@ function isPostHogEnabled() {
 const SDK_POSTHOG_INSTANCE_NAME = "spatius-posthog";
 let sdkPosthogInstance = null;
 const eventQueue = [];
-const FILTERED_HOSTNAMES = ["localhost", "127.0.0.1", "0.0.0.0"];
-function shouldFilterHostname() {
-  if (typeof window === "undefined") {
-    return false;
-  }
-  const hostname = window.location.hostname;
-  return FILTERED_HOSTNAMES.includes(hostname);
-}
 function getCommonFields() {
   const logContext = idManager.getLogContext();
   return {
@@ -12300,28 +12321,39 @@ function cleanupPostHog() {
     sdkPosthogInstance = null;
   }
 }
-function logEvent(event, level = "info", contents = {}) {
+const TELEMETRY_LOG_METHOD = {
+  debug: "log",
+  info: "log",
+  warning: "warn",
+  error: "error"
+};
+function buildTelemetryContext(event, level, contents) {
   const sessionToken = idManager.getSessionToken() ?? "";
   const context2 = {
     session_token_suffix: sessionToken ? sessionToken.slice(-8) : "",
     ...contents
   };
-  const logLevels = {
-    debug: "log",
-    info: "log",
-    warning: "warn",
-    error: "error"
-  };
-  const logMethod = logLevels[level] ?? "log";
+  const logMethod = TELEMETRY_LOG_METHOD[level] ?? "log";
   const propsDescription = Object.entries(contents).map(([k2, v2]) => `${k2}=${v2}`).join(", ");
   logger[logMethod](`[Telemetry] ${event} [${propsDescription}]`);
-  trackEvent(event, level, context2);
+  return context2;
+}
+function emitToOtel(event, level, context2) {
   try {
     trackEventOtel(event, level, context2);
   } catch (error) {
     logger.warn("[OTel] Dual-send failed:", error instanceof Error ? error.message : String(error));
   }
 }
+function logEvent(event, level = "info", contents = {}) {
+  const context2 = buildTelemetryContext(event, level, contents);
+  trackEvent(event, level, context2);
+  emitToOtel(event, level, context2);
+}
+function logMetric(event, level = "info", contents = {}) {
+  const context2 = buildTelemetryContext(event, level, contents);
+  emitToOtel(event, level, context2);
+}
 const _LogSink = class _LogSink {
   constructor() {
     __publicField(this, "db", null);
@@ -12823,6 +12855,8 @@ const _AnimationPlayer = class _AnimationPlayer {
     __publicField(this, "_isPlaying", false);
     __publicField(this, "fps", APP_CONFIG.animation.fps);
     __publicField(this, "onEndedCallback");
+    // 音频缓冲卡顿回调（透传给 streamingPlayer；控制器注册，用于并入 playback_quality）
+    __publicField(this, "onAudioStallCallback");
     __publicField(this, "useStreaming", false);
   }
   /**
@@ -12906,7 +12940,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-BQawYU25.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-CF0Yrsmz.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -12945,6 +12979,22 @@ const _AnimationPlayer = class _AnimationPlayer {
       this._isPlaying = false;
       (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
     });
+    this.streamingPlayer.onAudioStall((stalled) => {
+      var _a;
+      (_a = this.onAudioStallCallback) == null ? void 0 : _a.call(this, stalled);
+    });
+  }
+  /**
+   * 注册音频缓冲卡顿回调，透传给底层 streamingPlayer（若已就绪则立即接上）。
+   * @internal
+   */
+  onAudioStall(callback) {
+    var _a;
+    this.onAudioStallCallback = callback;
+    (_a = this.streamingPlayer) == null ? void 0 : _a.onAudioStall((stalled) => {
+      var _a2;
+      (_a2 = this.onAudioStallCallback) == null ? void 0 : _a2.call(this, stalled);
+    });
   }
   setupEventListeners() {
     if (!this.audio)
@@ -15030,7 +15080,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.3.1-beta.1");
+__publicField(AvatarSDK, "_version", "1.3.1-beta.3");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
 __publicField(AvatarSDK, "_rendererBackend", null);
@@ -15671,7 +15721,6 @@ class NetworkLayer {
     }
     if (this.isFallbackMode) {
       if (this.currentConversationId) {
-        logger.warn("[NetworkLayer] Fallback mode: skipping WebSocket send, triggering fallback");
         this.dataController.yieldKeyframes([], this.currentConversationId);
       }
       return;
@@ -15899,26 +15948,24 @@ class NetworkLayer {
     this.audioMetrics = this.createAudioMetrics();
   }
   /**
-   * 上报 driving_service_latency 事件
-   * 整轮播放结束(进入 idle)时由 AvatarController 调用,覆盖自然结束与中途打断两条路径
+   * 取本轮端到端延迟打点（tap_N=第N秒音频送入时刻，anim_N=第N组动画到达时刻）。
+   * 整轮播放结束(进入 idle)时由 AvatarController 读取，并入 playback_quality 的
+   * latency 成员统一上报（不再单发 driving_service_latency）。
+   * 无打点数据（如未走 direct 驱动）时返回 null，playback_quality 不带 latency。
    * @internal
    */
-  reportDrivingServiceLatency() {
-    const conversationId = this.currentConversationId;
-    if (!conversationId) return;
+  getDrivingServiceLatency() {
+    if (!this.currentConversationId) return null;
     const metrics = this.audioMetrics;
-    if (metrics.taps.size === 0 || metrics.anims.size === 0) return;
-    const props = {
-      conversation_id: conversationId,
-      dsm: "direct"
-    };
+    if (metrics.taps.size === 0 || metrics.anims.size === 0) return null;
+    const props = {};
     for (const [n2, t2] of metrics.taps) {
       props[`tap_${n2}`] = t2;
     }
     for (const [n2, t2] of metrics.anims) {
       props[`anim_${n2}`] = t2;
     }
-    logEvent("driving_service_latency", "info", props);
+    return props;
   }
   /**
    * Start driving service heartbeat check (check connection status every 2 minutes)
@@ -16215,8 +16262,23 @@ class AvatarController {
     __publicField(this, "isFallbackMode", false);
     // 降级模式标志
     // ========== Frame Starvation Tracking ==========
+    // enterMono：进入卡顿那刻的单调读数（performance.now()），恢复时用来算 durationMs。
+    // durationMs：这次卡顿持续多久（ms），帧恢复时回填；卡到播放结束都没恢复则为 null。
+    // startTs：卡顿开始的时间线时刻（clockSync.timelineNow()，优先后台、退本地，与 tap/anim 同轴）。
+    // framesAtEnter / framesAtRecover：卡顿开始/恢复时本轮已收到的服务端动画帧数
+    // （差值 = 卡顿期间到帧量，区分"服务端没发"与"发了但不够消费"）。未恢复则 framesAtRecover=null。
     __publicField(this, "frameStarvationEvents", []);
     __publicField(this, "isFrameStarved", false);
+    // ========== Audio Buffer Stall Tracking ==========
+    // 音频缓冲卡顿（缓冲耗尽自动暂停、有数据自动恢复），与帧饥饿对称记录。字段同义。
+    __publicField(this, "audioStallEvents", []);
+    __publicField(this, "isAudioBufferStalled", false);
+    // 本轮播放的结束原因（供 playback_quality 上报）：completed=正常播完，interrupted=中途打断。
+    __publicField(this, "playbackEndReason", "completed");
+    // 本轮已接收的音频总字节数（两模式统一累计）。总时长 = /audioBytesPerSecond。每轮重置。
+    __publicField(this, "receivedAudioBytes", 0);
+    // 本轮已接收的服务端下发动画帧总数（不含本地起播过渡帧）。每轮重置。
+    __publicField(this, "receivedAnimationFrames", 0);
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
      * Frame starvation is only possible BEFORE this — once all frames are in, any remaining
@@ -16397,42 +16459,100 @@ class AvatarController {
   /**
    * Notify conversation state change and handle telemetry
    * @internal
-   * @param isFallback - true when entering fallback mode (suppresses playback stats)
    */
-  notifyConversationState(avatarState, isFallback = false) {
-    var _a, _b;
+  notifyConversationState(avatarState) {
+    var _a;
     switch (avatarState) {
       case AvatarState.playing:
         this.frameRateMonitor.resetPlaybackStats();
-        this.shouldReportPlaybackStats = !isFallback;
+        this.shouldReportPlaybackStats = true;
         break;
       case AvatarState.paused:
         this.shouldReportPlaybackStats = false;
         break;
       case AvatarState.idle:
-        (_a = this.networkLayer) == null ? void 0 : _a.reportDrivingServiceLatency();
         if (this.shouldReportPlaybackStats) {
-          const stats = this.frameRateMonitor.getPlaybackStats();
-          const bypassSampling = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("integration") === "1";
-          if (stats.durationMs >= 2e3 && stats.frameCount > 0 && (bypassSampling || Math.random() < 0.3)) {
-            const props = {
-              avg_fps: Number(stats.avgFps.toFixed(1)),
-              frame_count: stats.frameCount,
-              duration_ms: stats.durationMs,
-              jank_ratio: Number(stats.jankRatio.toFixed(2)),
-              fps_cv: Number(stats.fpsCv.toFixed(3)),
-              ...this._getDeviceScoreProps()
-            };
-            if (AvatarSDK.getRendererBackend()) {
-              props.renderer_backend = AvatarSDK.getRendererBackend();
-            }
-            logEvent("avatar_playback_fps", "info", props);
-          }
+          this.reportPlaybackQuality();
         }
         this.shouldReportPlaybackStats = false;
         break;
     }
-    (_b = this.onConversationState) == null ? void 0 : _b.call(this, this.mapToConversationState(avatarState));
+    (_a = this.onConversationState) == null ? void 0 : _a.call(this, this.mapToConversationState(avatarState));
+  }
+  /**
+   * 上报本轮播放质量（playback_quality）。每轮播放结束都发一次（不采样、不设时长门槛），
+   * 把帧率与卡顿两块合并为嵌套成员。end_reason 区分完整播完 / 中途打断。
+   * 有卡顿时用 warning，否则 info（保留卡顿的告警语义）。
+   * @internal
+   */
+  reportPlaybackQuality() {
+    var _a, _b;
+    const stats = this.frameRateMonitor.getPlaybackStats();
+    const settled = this.frameStarvationEvents.map((e2) => e2.durationMs).filter((d2) => d2 !== null);
+    const totalStallMs = settled.reduce((a2, b2) => a2 + b2, 0);
+    const stall = {
+      count: this.frameStarvationEvents.length,
+      max_ms: settled.length > 0 ? Math.max(...settled) : 0,
+      total_ms: totalStallMs,
+      // 卡顿率 = 卡顿总时长 / 已播放时长（fps.duration_ms；打断轮即播到打断那刻，上限音频时长）
+      ratio: stats.durationMs > 0 ? Number((totalStallMs / stats.durationMs).toFixed(4)) : 0,
+      req_end: this.frameStarvationEvents.some((e2) => e2.reqEnd),
+      // 每次卡顿明细：开始时间戳 / 卡顿时的音频时刻(ms) / 等了多久(null=没恢复) / 卡顿开始与恢复时的动画帧数
+      events: this.frameStarvationEvents.map((e2) => ({
+        start_ts: Math.round(e2.startTs),
+        audio_time_ms: Math.round(e2.audioTime * 1e3),
+        duration_ms: e2.durationMs,
+        frames_at_enter: e2.framesAtEnter,
+        frames_at_recover: e2.framesAtRecover
+      }))
+    };
+    const audioSettled = this.audioStallEvents.map((e2) => e2.durationMs).filter((d2) => d2 !== null);
+    const audioStall = {
+      count: this.audioStallEvents.length,
+      max_ms: audioSettled.length > 0 ? Math.max(...audioSettled) : 0,
+      total_ms: audioSettled.reduce((a2, b2) => a2 + b2, 0),
+      events: this.audioStallEvents.map((e2) => ({
+        start_ts: Math.round(e2.startTs),
+        duration_ms: e2.durationMs,
+        frames_at_enter: e2.framesAtEnter,
+        frames_at_recover: e2.framesAtRecover
+      }))
+    };
+    const fps = {
+      avg_fps: Number(stats.avgFps.toFixed(1)),
+      frame_count: stats.frameCount,
+      duration_ms: stats.durationMs,
+      jank_ratio: Number(stats.jankRatio.toFixed(2)),
+      fps_cv: Number(stats.fpsCv.toFixed(3)),
+      ...this._getDeviceScoreProps()
+    };
+    if (AvatarSDK.getRendererBackend()) {
+      fps.renderer_backend = AvatarSDK.getRendererBackend();
+    }
+    const latency = ((_a = this.networkLayer) == null ? void 0 : _a.getDrivingServiceLatency()) ?? null;
+    logMetric("playback_quality", stall.count > 0 || audioStall.count > 0 ? "warning" : "info", {
+      avatar_id: this.avatar.id,
+      // backend 模式无 networkLayer，conversation_id 存于本地 currentConversationId；
+      // 对齐 playback_ended 的兜底顺序，避免 backend 上报 conversation_id=undefined。
+      conversation_id: this.currentConversationId || ((_b = this.networkLayer) == null ? void 0 : _b.getCurrentConversationId()) || void 0,
+      end_reason: this.playbackEndReason,
+      // 是否降级模式（audio-only 无动画帧）：为 true 时 fps/animation_frame_count 空是预期
+      is_fallback: this.isFallbackMode,
+      // 本轮接收情况：总音频时长(ms) / 是否收到最后音频(end=true) /
+      // 服务端下发总动画帧数(不含过渡帧) / 是否收到最后动画包(end=true)
+      audio_duration_ms: Math.round(this.receivedAudioBytes / this.audioBytesPerSecond * 1e3),
+      audio_ended: this.reqEnd,
+      animation_frame_count: this.receivedAnimationFrames,
+      animation_ended: this.animationEnded,
+      fps: JSON.stringify(fps),
+      stall: JSON.stringify(stall),
+      audio_stall: JSON.stringify(audioStall),
+      ...latency ? { latency: JSON.stringify(resolveMarks(latency)) } : {}
+    });
+    this.frameStarvationEvents = [];
+    this.isFrameStarved = false;
+    this.audioStallEvents = [];
+    this.isAudioBufferStalled = false;
   }
   /**
    * Get animation player instance
@@ -16552,6 +16672,7 @@ class AvatarController {
     if (this.reqEnd && this.isPlaying && networkConversationId) {
       this.interrupt();
     }
+    this.receivedAudioBytes += audioData.byteLength;
     this.addAudioChunkToBuffer(new Uint8Array(audioData), end);
     this.networkLayer.sendAudioData(audioData, end);
     if (end) {
@@ -16651,6 +16772,7 @@ class AvatarController {
     if (isLast) {
       this.reqEnd = true;
     }
+    this.receivedAudioBytes += data.length;
     if (this.playbackMode === DrivingServiceMode.backend) {
       const metrics = this.hostModeMetrics;
       if (metrics.startTimestamp === 0) {
@@ -16779,6 +16901,7 @@ class AvatarController {
       return;
     }
     const flameKeyframes = keyframes;
+    this.receivedAnimationFrames += flameKeyframes.length;
     if (this.currentKeyframes.length === 0) {
       this.currentKeyframes = flameKeyframes;
       if (this.playbackMode === DrivingServiceMode.backend && !this.hostModeMetrics.didRecvFirstFlame) {
@@ -16919,6 +17042,8 @@ class AvatarController {
     this.lastSyncLogTime = 0;
     this.lastOutOfBoundsState = false;
     this.animationEnded = false;
+    this.receivedAudioBytes = 0;
+    this.receivedAnimationFrames = 0;
     if (this.isAudioStalledForStarvation) {
       this.isAudioStalledForStarvation = false;
       (_a = this.onPlaybackStall) == null ? void 0 : _a.call(this, false);
@@ -17111,6 +17236,9 @@ class AvatarController {
       await this.animationPlayer.prepareStreamingPlayer(() => {
         this.onPlaybackEnded();
       });
+      this.animationPlayer.onAudioStall((stalled) => {
+        this.trackAudioBufferStall(stalled);
+      });
       if (!this.isFallbackMode) {
         this.emit("startRendering");
       }
@@ -17128,11 +17256,12 @@ class AvatarController {
       this.pendingAudioChunks = [];
       this.isPlaying = true;
       this.currentState = AvatarState.playing;
-      this.notifyConversationState(AvatarState.playing, this.isFallbackMode);
+      this.notifyConversationState(AvatarState.playing);
       this.isStartingPlayback = false;
       logEvent("playback_started", "info", {
         avatar_id: this.avatar.id,
-        conversation_id: ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0
+        // backend 模式无 networkLayer，取本地 currentConversationId 兜底（同 playback_ended/quality）
+        conversation_id: this.currentConversationId || ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -17201,7 +17330,7 @@ class AvatarController {
       state.reported = true;
       logEvent("playback_stuck_after_transition", "error", {
         avatar_id: this.avatar.id,
-        conversation_id: ((_e2 = this.networkLayer) == null ? void 0 : _e2.getCurrentConversationId()) || void 0,
+        conversation_id: this.currentConversationId || ((_e2 = this.networkLayer) == null ? void 0 : _e2.getCurrentConversationId()) || void 0,
         // 诊断信息（包含 audio_context_state 用于诊断，但不作为触发条件）
         audio_context_state: audioContextState,
         audio_time: audioTime,
@@ -17271,13 +17400,28 @@ class AvatarController {
         const totalKeyframes = this.currentKeyframes.length + this.keyframesOffset;
         const frameDiff = frameIndex - totalKeyframes;
         if (!(this.reqEnd && frameDiff <= 1)) {
-          this.frameStarvationEvents.push({ audioTime, reqEnd: this.reqEnd });
+          this.frameStarvationEvents.push({
+            audioTime,
+            reqEnd: this.reqEnd,
+            enterMono: performance.now(),
+            durationMs: null,
+            startTs: clockSync.timelineNow(),
+            framesAtEnter: this.receivedAnimationFrames,
+            framesAtRecover: null
+          });
         }
       }
       if (!this.animationEnded) {
         this.pauseAudioForStarvation();
       }
     } else {
+      if (this.isFrameStarved) {
+        const last = this.frameStarvationEvents[this.frameStarvationEvents.length - 1];
+        if (last && last.durationMs === null) {
+          last.durationMs = Math.round(performance.now() - last.enterMono);
+          last.framesAtRecover = this.receivedAnimationFrames;
+        }
+      }
       this.isFrameStarved = false;
       if (isOutOfBounds !== this.lastOutOfBoundsState) {
         this.lastOutOfBoundsState = isOutOfBounds;
@@ -17285,6 +17429,33 @@ class AvatarController {
       this.resumeAudioFromStarvation();
     }
   }
+  /**
+   * 记录音频缓冲卡顿（缓冲耗尽自动暂停 / 有数据自动恢复），并入 playback_quality.audio_stall。
+   * 与 trackFrameStarvation 对称：进入 push 事件、恢复回填时长与动画帧数。
+   * @param stalled true=进入卡顿，false=恢复
+   * @internal
+   */
+  trackAudioBufferStall(stalled) {
+    if (stalled) {
+      if (this.isAudioBufferStalled) return;
+      this.isAudioBufferStalled = true;
+      this.audioStallEvents.push({
+        enterMono: performance.now(),
+        durationMs: null,
+        startTs: clockSync.timelineNow(),
+        framesAtEnter: this.receivedAnimationFrames,
+        framesAtRecover: null
+      });
+    } else {
+      if (!this.isAudioBufferStalled) return;
+      this.isAudioBufferStalled = false;
+      const last = this.audioStallEvents[this.audioStallEvents.length - 1];
+      if (last && last.durationMs === null) {
+        last.durationMs = Math.round(performance.now() - last.enterMono);
+        last.framesAtRecover = this.receivedAnimationFrames;
+      }
+    }
+  }
   /**
    * strictSync: pause audio on frame starvation, waiting for new frames.
    *
@@ -17360,7 +17531,6 @@ class AvatarController {
     if (this.isFallbackMode) {
       return;
     }
-    logger.warn("[AvatarController] Enabling fallback mode");
     this.isFallbackMode = true;
     this.resumeAudioFromStarvation();
     logEvent("fallback_mode_entered", "warning", {
@@ -17394,26 +17564,15 @@ class AvatarController {
    * @internal
    */
   onPlaybackEnded() {
-    var _a, _b;
-    if (this.frameStarvationEvents.length > 0) {
-      const hasReqEnd = this.frameStarvationEvents.some((e2) => e2.reqEnd);
-      logEvent("frame_starvation", "warning", {
-        avatar_id: this.avatar.id,
-        conversation_id: ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0,
-        starvation_count: this.frameStarvationEvents.length,
-        starvation_times: this.frameStarvationEvents.map((e2) => Number(e2.audioTime.toFixed(3))),
-        ...hasReqEnd ? { req_end: true } : {}
-      });
-    }
-    this.frameStarvationEvents = [];
-    this.isFrameStarved = false;
+    var _a;
     logEvent("playback_ended", "info", {
       avatar_id: this.avatar.id,
-      conversation_id: this.currentConversationId || ((_b = this.networkLayer) == null ? void 0 : _b.getCurrentConversationId()) || void 0,
+      conversation_id: this.currentConversationId || ((_a = this.networkLayer) == null ? void 0 : _a.getCurrentConversationId()) || void 0,
       source: this.isFallbackMode ? "fallback" : "streaming"
     });
     this.isPlaying = false;
     this.currentState = AvatarState.idle;
+    this.playbackEndReason = "completed";
     this.notifyConversationState(AvatarState.idle);
     this.emit("stopRendering");
     this.emit("stopFallback");
@@ -17431,6 +17590,7 @@ class AvatarController {
     this.emit("stopRendering");
     this.isPlaying = false;
     this.currentState = AvatarState.idle;
+    this.playbackEndReason = "interrupted";
     this.notifyConversationState(AvatarState.idle);
   }
   /**
@@ -17808,7 +17968,7 @@ class AvatarDownloader {
     if (cached) {
       const duration = Date.now() - startTime;
       logger.log(`✅ Unified template loaded from cache (${(cached.byteLength / 1024 / 1024).toFixed(1)} MB)`);
-      logEvent("template_resources_load_measure", "info", {
+      logMetric("template_resources_load_measure", "info", {
         duration,
         file_count: 1,
         cache_hit: true,
@@ -17837,7 +17997,7 @@ class AvatarDownloader {
           logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
         });
         const duration = Date.now() - startTime;
-        logEvent("template_resources_load_measure", "info", {
+        logMetric("template_resources_load_measure", "info", {
           duration,
           file_count: 1,
           cache_hit: false,
@@ -17990,7 +18150,7 @@ class AvatarDownloader {
     const totalSize = Object.values(characterData).reduce((sum, buffer) => {
       return sum + (buffer ? buffer.byteLength : 0);
     }, 0);
-    logEvent("download_avatar_assets_latency", "info", {
+    logMetric("download_avatar_assets_latency", "info", {
       resolution: "default",
       // 目前写死 default
       avatar_id: characterMeta.characterId ?? "unknown",
@@ -18184,7 +18344,7 @@ class AvatarDownloader {
         );
       }
       const duration = Date.now() - startTime;
-      logEvent("fetch_avatar_metadata_latency", "info", {
+      logMetric("fetch_avatar_metadata_latency", "info", {
         avatar_id: characterId,
         duration,
         trace_id: traceId
@@ -18426,7 +18586,7 @@ const _AvatarManager = class _AvatarManager {
     this.avatarCache.set(id, avatar);
     logger.log("[AvatarManager] Avatar loaded successfully");
     const totalDuration = Date.now() - startTime;
-    logEvent("fetch_avatar_latency", "info", {
+    logMetric("fetch_avatar_latency", "info", {
       resolution: "default",
       // 目前写死 default
       avatar_id: id,

package/dist/index.js

@@ -1,4 +1,4 @@
-import { m, b, c, p, f, d, o, g, C, n, i, j, D, E, F, k, L, h, R, q, T, r } from "./index-C54v6mHz.js";
+import { m, b, c, p, f, d, o, g, C, n, i, j, D, E, F, k, L, h, R, q, T, r } from "./index-CFPt9NwR.js";
 export {
   m as AnimationType,
   b as Avatar,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatius/avatarkit",
   "type": "module",
-  "version": "1.3.1-beta.1",
+  "version": "1.3.1-beta.3",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - Real-time Avatar Rendering SDK for Web",
   "author": "AvatarKit Team",