@spatialwalk/avatarkit 1.0.0-beta.98 → 1.0.0-beta.99

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.0.0-beta.99]
+
+### ✨ Features
+
+- **Playback diagnostics** — Added telemetry events for audio buffer stall and frame starvation detection, improving visibility into playback interruption issues.
+
 ## [1.0.0-beta.98]
 
 ### 🐛 Bugfixes

package/README.md

@@ -716,8 +716,8 @@ const conversationId = avatarView.controller.getCurrentConversationId()
 // Returns: Current conversationId for the active audio session, or null if no active session
 
 // Volume control (affects only avatar audio player, not system volume)
-avatarView.controller.volume = 0.5  // Set volume to 50% (0.0 to 1.0)
-const currentVolume = avatarView.controller.volume  // Get current volume (0.0 to 1.0)
+avatarView.controller.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
+const currentVolume = avatarView.controller.getVolume()  // Get current volume (0.0 to 1.0)
 
 // Set event callbacks
 avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
@@ -745,7 +745,7 @@ avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 } // Right half, double
 **Important Notes:**
 - `start()` and `close()` are only available in SDK mode
 - `yieldAudioData()` and `yieldFramesData()` are only available in Host mode
-- `pause()`, `resume()`, `interrupt()`, `clear()`, `getCurrentConversationId()`, and `volume` property are available in both modes
+- `pause()`, `resume()`, `interrupt()`, `clear()`, `getCurrentConversationId()`, `setVolume()`, and `getVolume()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
 
 ## 🔧 Configuration

package/dist/{StreamingAudioPlayer-DEELveJ_.js → StreamingAudioPlayer-CLmftu1c.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-DfE9mnfH.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CnV_uOSq.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
@@ -305,6 +305,11 @@ class StreamingAudioPlayer {
           const lastChunk = this.audioChunks[this.scheduledChunks - 1];
           if (lastChunk && !lastChunk.isLast) {
             this.log("All audio chunks ended but end=false, pausing and setting autoContinue");
+            logEvent("character_player", "warning", {
+              event: "audio_buffer_stall",
+              scheduled_chunks: this.scheduledChunks,
+              audio_time: this.getCurrentTime()
+            });
             this.autoContinue = true;
             this.pause();
           } else if (isLast) {

package/dist/core/AvatarController.d.ts

@@ -31,6 +31,8 @@ export declare class AvatarController {
     private lastSyncLogTime;
     private lastOutOfBoundsState;
     private isFallbackMode;
+    private frameStarvationEvents;
+    private isFrameStarved;
     private playbackStuckCheckState;
     private readonly MAX_AUDIO_TIME_ZERO_COUNT;
     private readonly MAX_AUDIO_TIME_STUCK_COUNT;
@@ -138,12 +140,14 @@ export declare class AvatarController {
      */
     setPostProcessingConfig(config: PostProcessingConfig | null): void;
     /**
-     * Audio playback volume (0.0 - 1.0)
-     *
-     * @example
-     * avatarView.controller.volume = 0.5
-     * const current = avatarView.controller.volume
+     * Set audio playback volume
+     * Note: This only controls the avatar audio player volume, not the system volume
+     * @param volume Volume value, range from 0.0 to 1.0 (0.0 = mute, 1.0 = max volume)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Get current audio playback volume
+     * @returns Current volume value (0.0 - 1.0)
      */
-    get volume(): number;
-    set volume(value: number);
+    getVolume(): number;
 }

package/dist/{index-DfE9mnfH.js → index-CnV_uOSq.js}

@@ -9510,7 +9510,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DEELveJ_.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-CLmftu1c.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -11531,7 +11531,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.97");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.99");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
@@ -12626,6 +12626,9 @@ class AvatarController {
     // ========== Fallback Mode ==========
     __publicField(this, "isFallbackMode", false);
     // 降级模式标志
+    // ========== Frame Starvation Tracking ==========
+    __publicField(this, "frameStarvationEvents", []);
+    __publicField(this, "isFrameStarved", false);
     // ========== Playback Stuck Detection ==========
     __publicField(this, "playbackStuckCheckState", {
       audioTimeZeroCount: 0,
@@ -13426,29 +13429,31 @@ class AvatarController {
     }
   }
   /**
-   * Audio playback volume (0.0 - 1.0)
-   *
-   * @example
-   * avatarView.controller.volume = 0.5
-   * const current = avatarView.controller.volume
+   * Set audio playback volume
+   * Note: This only controls the avatar audio player volume, not the system volume
+   * @param volume Volume value, range from 0.0 to 1.0 (0.0 = mute, 1.0 = max volume)
    */
-  get volume() {
-    var _a;
-    return ((_a = this.animationPlayer) == null ? void 0 : _a.getVolume()) ?? 1;
-  }
-  set volume(value) {
+  setVolume(volume) {
     var _a;
-    if (value < 0 || value > 1) {
-      logger.warn(`[AvatarController] Volume out of range: ${value}, clamping to [0, 1]`);
-      value = Math.max(0, Math.min(1, value));
+    if (volume < 0 || volume > 1) {
+      logger.warn(`[AvatarController] Volume out of range: ${volume}, clamping to [0, 1]`);
+      volume = Math.max(0, Math.min(1, volume));
     }
-    (_a = this.animationPlayer) == null ? void 0 : _a.setVolume(value);
+    (_a = this.animationPlayer) == null ? void 0 : _a.setVolume(volume);
     logEvent("character_player", "info", {
       avatar_id: this.avatar.id,
       event: "volume_changed",
-      volume: value
+      volume
     });
   }
+  /**
+   * Get current audio playback volume
+   * @returns Current volume value (0.0 - 1.0)
+   */
+  getVolume() {
+    var _a;
+    return ((_a = this.animationPlayer) == null ? void 0 : _a.getVolume()) ?? 1;
+  }
   /**
    * Provide interface for AvatarView to register internal events
    * @internal
@@ -13493,11 +13498,27 @@ class AvatarController {
         throw new AvatarError("Animation player not initialized", ErrorCode.animationPlayerNotInitialized);
       }
       await this.animationPlayer.prepareStreamingPlayer(() => {
-        var _a2;
+        var _a2, _b2;
         this.isPlaying = false;
         this.currentState = AvatarState.idle;
         this.notifyConversationState(AvatarState.idle);
         this.emit("stopRendering");
+        if (this.frameStarvationEvents.length > 0) {
+          logEvent("character_player", "warning", {
+            event: "frame_starvation",
+            avatar_id: this.avatar.id,
+            conversationId: ((_a2 = this.networkLayer) == null ? void 0 : _a2.getCurrentConversationId()) || void 0,
+            starvation_count: this.frameStarvationEvents.length,
+            starvation_times: this.frameStarvationEvents.map((e2) => Number(e2.audioTime.toFixed(3)))
+          });
+        }
+        this.frameStarvationEvents = [];
+        this.isFrameStarved = false;
+        logEvent("character_player", "info", {
+          avatar_id: this.avatar.id,
+          event: "playback_ended",
+          conversationId: ((_b2 = this.networkLayer) == null ? void 0 : _b2.getCurrentConversationId()) || void 0
+        });
         this.clearPlaybackData();
         if (this.networkLayer) {
           this.networkLayer.resetConversationId();
@@ -13506,11 +13527,6 @@ class AvatarController {
         }
         this.reqEnd = false;
         this.isFallbackMode = false;
-        logEvent("character_player", "info", {
-          avatar_id: this.avatar.id,
-          event: "playback_ended",
-          conversationId: ((_a2 = this.networkLayer) == null ? void 0 : _a2.getCurrentConversationId()) || void 0
-        });
       });
       this.emit("startRendering");
       const streamingPlayer = this.animationPlayer.getStreamingPlayer();
@@ -13628,6 +13644,7 @@ class AvatarController {
    * @internal
    */
   async computeAndRenderFrame(frameIndex, loopGeneration) {
+    var _a;
     let arrayIndex = frameIndex - this.keyframesOffset;
     if (arrayIndex < 0) {
       arrayIndex = 0;
@@ -13643,8 +13660,16 @@ class AvatarController {
         this.lastSyncLogTime = now;
         this.lastOutOfBoundsState = isOutOfBounds;
       }
-    } else if (isOutOfBounds !== this.lastOutOfBoundsState) {
-      this.lastOutOfBoundsState = isOutOfBounds;
+      if (!this.isFrameStarved) {
+        this.isFrameStarved = true;
+        const audioTime = ((_a = this.animationPlayer) == null ? void 0 : _a.getCurrentTime()) ?? 0;
+        this.frameStarvationEvents.push({ audioTime });
+      }
+    } else {
+      this.isFrameStarved = false;
+      if (isOutOfBounds !== this.lastOutOfBoundsState) {
+        this.lastOutOfBoundsState = isOutOfBounds;
+      }
     }
     if (this.currentKeyframes.length > this.MAX_KEYFRAMES) {
       const framesToKeep = this.KEYFRAMES_CLEANUP_THRESHOLD;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-DfE9mnfH.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-CnV_uOSq.js";
 export {
   b as Avatar,
   c as AvatarController,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.98",
+  "version": "1.0.0-beta.99",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",