@spatius/avatarkit 1.1.0-beta.1 → 1.2.0-beta.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.2.0-beta.1] - 2026-06-19
+
+### Added
+- Configurable frame-starvation handling. New public API:
+  - `FrameStarvationMode` enum with `audioIndependent` (default) and `strictSync`.
+  - `AvatarController.frameStarvationMode: FrameStarvationMode` — choose how playback behaves when animation frames can't keep up with audio. `audioIndependent` keeps audio playing while animation catches up (previous behavior); `strictSync` pauses audio until frames arrive, keeping audio and animation strictly in sync.
+  - `AvatarController.onPlaybackStall: ((stalled: boolean) => void) | null` — fires when audio is paused/resumed due to frame starvation (only in `strictSync`).
+
+### Changed
+- Avatars now load via the latest avatar asset format.
+- CDN selection now adapts to the configured region.
+
 ## [1.1.0-beta.1] - 2026-06-08
 
 First 1.1 pre-release. Includes breaking changes — see below.

package/dist/{StreamingAudioPlayer-DrHXn-YA.js → StreamingAudioPlayer-Br8UrVgO.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-CVQn5uEB.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-DHCQ9wsL.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {

package/dist/core/AvatarController.d.ts

@@ -1,5 +1,5 @@
 import { Avatar } from './Avatar';
-import { ConnectionState, AvatarError, DrivingServiceMode, ConversationState, AnimationType, PostProcessingConfig } from '../types';
+import { ConnectionState, AvatarError, DrivingServiceMode, FrameStarvationMode, ConversationState, AnimationType, PostProcessingConfig } from '../types';
 import { FrameRateInfo } from '../performance/FrameRateMonitor';
 export declare class AvatarController {
     private networkLayer?;
@@ -12,6 +12,21 @@ export declare class AvatarController {
     onError: ((error: AvatarError) => void) | null;
     /** Callback for animation type changes (e.g., idle → mono in fallback mode). Aligned with iOS/Android AvatarController.onAnimationState. */
     onAnimationState: ((type: AnimationType) => void) | null;
+    /**
+     * Strategy for handling animation-frame starvation. Default is
+     * {@link FrameStarvationMode.audioIndependent} (audio keeps playing, starvation only
+     * reported as telemetry — historical behavior). Set to {@link FrameStarvationMode.strictSync}
+     * to pause audio when frames run out and resume on new frames, notified via {@link onPlaybackStall}.
+     * Aligned with iOS/Android AvatarController.frameStarvationMode.
+     */
+    frameStarvationMode: FrameStarvationMode;
+    /**
+     * Fires when audio is paused/resumed due to frame starvation. Only invoked in
+     * {@link FrameStarvationMode.strictSync}. `stalled=true` — frames ran out, audio paused;
+     * `stalled=false` — new frames arrived, audio resumed (or conversation ended / fell back).
+     * Aligned with iOS/Android AvatarController.onPlaybackStall.
+     */
+    onPlaybackStall: ((stalled: boolean) => void) | null;
     private eventListeners;
     private readonly frameRateMonitor;
     /** Frame rate monitoring callback. Fires with aggregated metrics from a 2-second sliding window. */
@@ -32,6 +47,18 @@ export declare class AvatarController {
     private isFallbackMode;
     private frameStarvationEvents;
     private isFrameStarved;
+    /**
+     * 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
+     * audio tail is normal end-of-round, not starvation, so audio must keep playing to idle
+     * and must never be paused (matters most in strictSync). Reset per conversation.
+     */
+    private animationEnded;
+    /**
+     * Whether audio is currently paused because of frame starvation (strictSync only).
+     * Orthogonal to user pause — user pause/resume does not change it; only frame arrival does.
+     */
+    private isAudioStalledForStarvation;
     private playbackStuckCheckState;
     private readonly MAX_AUDIO_TIME_ZERO_COUNT;
     private readonly MAX_AUDIO_TIME_STUCK_COUNT;

package/dist/{index-CVQn5uEB.js → index-DHCQ9wsL.js}

@@ -1257,6 +1257,7 @@ function messageTypeToJSON(object) {
 }
 var AudioFormat = /* @__PURE__ */ ((AudioFormat2) => {
   AudioFormat2[AudioFormat2["AUDIO_FORMAT_PCM_S16LE"] = 0] = "AUDIO_FORMAT_PCM_S16LE";
+  AudioFormat2[AudioFormat2["AUDIO_FORMAT_OGG_OPUS"] = 1] = "AUDIO_FORMAT_OGG_OPUS";
   AudioFormat2[AudioFormat2["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
   return AudioFormat2;
 })(AudioFormat || {});
@@ -1265,6 +1266,9 @@ function audioFormatFromJSON(object) {
     case 0:
     case "AUDIO_FORMAT_PCM_S16LE":
       return 0;
+    case 1:
+    case "AUDIO_FORMAT_OGG_OPUS":
+      return 1;
     case -1:
     case "UNRECOGNIZED":
     default:
@@ -1275,6 +1279,8 @@ function audioFormatToJSON(object) {
   switch (object) {
     case 0:
       return "AUDIO_FORMAT_PCM_S16LE";
+    case 1:
+      return "AUDIO_FORMAT_OGG_OPUS";
     case -1:
     default:
       return "UNRECOGNIZED";
@@ -1343,7 +1349,16 @@ function egressTypeToJSON(object) {
   }
 }
 function createBaseLiveKitEgressConfig() {
-  return { url: "", apiKey: "", apiSecret: "", roomName: "", publisherId: "" };
+  return {
+    url: "",
+    apiKey: "",
+    apiSecret: "",
+    roomName: "",
+    publisherId: "",
+    extraAttributes: {},
+    idleTimeout: 0,
+    apiToken: ""
+  };
 }
 const LiveKitEgressConfig = {
   encode(message, writer = new BinaryWriter()) {
@@ -1362,6 +1377,15 @@ const LiveKitEgressConfig = {
     if (message.publisherId !== "") {
       writer.uint32(42).string(message.publisherId);
     }
+    globalThis.Object.entries(message.extraAttributes).forEach(([key, value]) => {
+      LiveKitEgressConfig_ExtraAttributesEntry.encode({ key, value }, writer.uint32(50).fork()).join();
+    });
+    if (message.idleTimeout !== 0) {
+      writer.uint32(56).int32(message.idleTimeout);
+    }
+    if (message.apiToken !== "") {
+      writer.uint32(66).string(message.apiToken);
+    }
     return writer;
   },
   decode(input, length) {
@@ -1406,6 +1430,30 @@ const LiveKitEgressConfig = {
           message.publisherId = reader.string();
           continue;
         }
+        case 6: {
+          if (tag !== 50) {
+            break;
+          }
+          const entry6 = LiveKitEgressConfig_ExtraAttributesEntry.decode(reader, reader.uint32());
+          if (entry6.value !== void 0) {
+            message.extraAttributes[entry6.key] = entry6.value;
+          }
+          continue;
+        }
+        case 7: {
+          if (tag !== 56) {
+            break;
+          }
+          message.idleTimeout = reader.int32();
+          continue;
+        }
+        case 8: {
+          if (tag !== 66) {
+            break;
+          }
+          message.apiToken = reader.string();
+          continue;
+        }
       }
       if ((tag & 7) === 4 || tag === 0) {
         break;
@@ -1420,7 +1468,22 @@ const LiveKitEgressConfig = {
       apiKey: isSet(object.apiKey) ? globalThis.String(object.apiKey) : isSet(object.api_key) ? globalThis.String(object.api_key) : "",
       apiSecret: isSet(object.apiSecret) ? globalThis.String(object.apiSecret) : isSet(object.api_secret) ? globalThis.String(object.api_secret) : "",
       roomName: isSet(object.roomName) ? globalThis.String(object.roomName) : isSet(object.room_name) ? globalThis.String(object.room_name) : "",
-      publisherId: isSet(object.publisherId) ? globalThis.String(object.publisherId) : isSet(object.publisher_id) ? globalThis.String(object.publisher_id) : ""
+      publisherId: isSet(object.publisherId) ? globalThis.String(object.publisherId) : isSet(object.publisher_id) ? globalThis.String(object.publisher_id) : "",
+      extraAttributes: isObject(object.extraAttributes) ? globalThis.Object.entries(object.extraAttributes).reduce(
+        (acc, [key, value]) => {
+          acc[key] = globalThis.String(value);
+          return acc;
+        },
+        {}
+      ) : isObject(object.extra_attributes) ? globalThis.Object.entries(object.extra_attributes).reduce(
+        (acc, [key, value]) => {
+          acc[key] = globalThis.String(value);
+          return acc;
+        },
+        {}
+      ) : {},
+      idleTimeout: isSet(object.idleTimeout) ? globalThis.Number(object.idleTimeout) : isSet(object.idle_timeout) ? globalThis.Number(object.idle_timeout) : 0,
+      apiToken: isSet(object.apiToken) ? globalThis.String(object.apiToken) : isSet(object.api_token) ? globalThis.String(object.api_token) : ""
     };
   },
   toJSON(message) {
@@ -1440,6 +1503,21 @@ const LiveKitEgressConfig = {
     if (message.publisherId !== "") {
       obj.publisherId = message.publisherId;
     }
+    if (message.extraAttributes) {
+      const entries = globalThis.Object.entries(message.extraAttributes);
+      if (entries.length > 0) {
+        obj.extraAttributes = {};
+        entries.forEach(([k2, v2]) => {
+          obj.extraAttributes[k2] = v2;
+        });
+      }
+    }
+    if (message.idleTimeout !== 0) {
+      obj.idleTimeout = Math.round(message.idleTimeout);
+    }
+    if (message.apiToken !== "") {
+      obj.apiToken = message.apiToken;
+    }
     return obj;
   },
   create(base) {
@@ -1452,6 +1530,85 @@ const LiveKitEgressConfig = {
     message.apiSecret = object.apiSecret ?? "";
     message.roomName = object.roomName ?? "";
     message.publisherId = object.publisherId ?? "";
+    message.extraAttributes = globalThis.Object.entries(object.extraAttributes ?? {}).reduce(
+      (acc, [key, value]) => {
+        if (value !== void 0) {
+          acc[key] = globalThis.String(value);
+        }
+        return acc;
+      },
+      {}
+    );
+    message.idleTimeout = object.idleTimeout ?? 0;
+    message.apiToken = object.apiToken ?? "";
+    return message;
+  }
+};
+function createBaseLiveKitEgressConfig_ExtraAttributesEntry() {
+  return { key: "", value: "" };
+}
+const LiveKitEgressConfig_ExtraAttributesEntry = {
+  encode(message, writer = new BinaryWriter()) {
+    if (message.key !== "") {
+      writer.uint32(10).string(message.key);
+    }
+    if (message.value !== "") {
+      writer.uint32(18).string(message.value);
+    }
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    const end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseLiveKitEgressConfig_ExtraAttributesEntry();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+          message.key = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+          message.value = reader.string();
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(object) {
+    return {
+      key: isSet(object.key) ? globalThis.String(object.key) : "",
+      value: isSet(object.value) ? globalThis.String(object.value) : ""
+    };
+  },
+  toJSON(message) {
+    const obj = {};
+    if (message.key !== "") {
+      obj.key = message.key;
+    }
+    if (message.value !== "") {
+      obj.value = message.value;
+    }
+    return obj;
+  },
+  create(base) {
+    return LiveKitEgressConfig_ExtraAttributesEntry.fromPartial(base ?? {});
+  },
+  fromPartial(object) {
+    const message = createBaseLiveKitEgressConfig_ExtraAttributesEntry();
+    message.key = object.key ?? "";
+    message.value = object.value ?? "";
     return message;
   }
 };
@@ -3999,6 +4156,11 @@ var DrivingServiceMode = /* @__PURE__ */ ((DrivingServiceMode2) => {
   DrivingServiceMode2["backend"] = "backend";
   return DrivingServiceMode2;
 })(DrivingServiceMode || {});
+var FrameStarvationMode = /* @__PURE__ */ ((FrameStarvationMode2) => {
+  FrameStarvationMode2["audioIndependent"] = "audioIndependent";
+  FrameStarvationMode2["strictSync"] = "strictSync";
+  return FrameStarvationMode2;
+})(FrameStarvationMode || {});
 var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
   LogLevel2["off"] = "off";
   LogLevel2["error"] = "error";
@@ -12349,6 +12511,11 @@ function convertWasmParamsToProtoFlame(wasmParams) {
     expression: wasmParams.expr_params || []
   };
 }
+const GLOBAL_FLAME_CDN_BASE = "https://cdn.spatialwalk.cloud/public";
+const CN_FLAME_CDN_BASE = "https://cdn.spatialwalk.top/public";
+function getFlameCdnBase(region) {
+  return region.startsWith("cn-") ? CN_FLAME_CDN_BASE : GLOBAL_FLAME_CDN_BASE;
+}
 const APP_CONFIG = {
   // Dynamic debug mode check (includes URL parameter)
   get debug() {
@@ -12371,7 +12538,6 @@ const APP_CONFIG = {
   },
   // Unified template model CDN (single compressed model shared by all characters)
   flame: {
-    cdnBase: "https://cdn.spatialwalk.cloud/public",
     unifiedModelPath: "base_model.pb.gz"
   }
 };
@@ -12465,7 +12631,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DrHXn-YA.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-Br8UrVgO.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -14525,7 +14691,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.1.0-beta.1");
+__publicField(AvatarSDK, "_version", "1.2.0-beta.1");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
 __publicField(AvatarSDK, "_rendererBackend", null);
@@ -14576,6 +14742,40 @@ class EventEmitter {
     }
   }
 }
+class PendingAudioBuffer {
+  constructor() {
+    __publicField(this, "items", []);
+  }
+  get isEmpty() {
+    return this.items.length === 0;
+  }
+  get count() {
+    return this.items.length;
+  }
+  /** Buffer a chunk sent while not yet able to reach the server. */
+  enqueue(item) {
+    this.items.push(item);
+  }
+  /**
+   * Drain the buffer, returning only the latest conversation's chunks (in
+   * arrival order) for replay and dropping anything from earlier conversations.
+   * The buffer is empty afterwards.
+   */
+  flush() {
+    const buffered = this.items;
+    this.items = [];
+    if (buffered.length === 0) {
+      return { toReplay: [], dropped: 0 };
+    }
+    const currentId = buffered[buffered.length - 1].conversationId;
+    const toReplay = buffered.filter((it2) => it2.conversationId === currentId);
+    return { toReplay, dropped: buffered.length - toReplay.length };
+  }
+  /** Drop everything (conversation ended / explicit disconnect). */
+  clear() {
+    this.items = [];
+  }
+}
 class AnimationWebSocketClient extends EventEmitter {
   constructor(options) {
     super();
@@ -14593,6 +14793,13 @@ class AnimationWebSocketClient extends EventEmitter {
     __publicField(this, "sessionConfigured", false);
     // v2 protocol: mark if session is configured
     __publicField(this, "connectionStartTime", 0);
+    /**
+     * Direct mode: audio sent before the session is confirmed is buffered here and
+     * replayed (in order) the moment the session is confirmed, so the server's
+     * audio stream stays identical to what played locally. See PendingAudioBuffer
+     * for the rationale and conversation-boundary handling.
+     */
+    __publicField(this, "pendingAudioBuffer", new PendingAudioBuffer());
     this.wsUrl = options.wsUrl;
     this.reconnectAttempts = options.reconnectAttempts ?? 5;
     this.jwtToken = options.jwtToken;
@@ -14637,6 +14844,7 @@ class AnimationWebSocketClient extends EventEmitter {
       this.ws.close(1e3, "Normal closure");
       this.ws = null;
     }
+    this.pendingAudioBuffer.clear();
     idManager.clearConnectionId();
     this.removeAllListeners();
     this.currentRetryCount = 0;
@@ -14655,14 +14863,18 @@ class AnimationWebSocketClient extends EventEmitter {
    * @internal
    */
   sendAudioData(conversationId, audioData, end) {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-      logger.warn("[AnimationWebSocketClient] WebSocket not connected, skipping audio send");
-      return false;
-    }
-    if (!this.sessionConfigured) {
-      logger.warn("[AnimationWebSocketClient] Session not configured yet, skipping audio send");
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.sessionConfigured) {
+      logger.warn("[AnimationWebSocketClient] Not ready (socket/session), buffering audio for replay on connect");
+      this.pendingAudioBuffer.enqueue({ conversationId, audioData, end });
       return false;
     }
+    return this.encodeAndSendAudio(conversationId, audioData, end);
+  }
+  /**
+   * Encode and write one audio chunk to the open socket. Caller must ensure the
+   * socket is open and the session is configured.
+   */
+  encodeAndSendAudio(conversationId, audioData, end) {
     try {
       const message = {
         type: MessageType.MESSAGE_CLIENT_AUDIO_INPUT,
@@ -14689,6 +14901,23 @@ class AnimationWebSocketClient extends EventEmitter {
       return false;
     }
   }
+  /**
+   * Replay audio buffered before the session was confirmed, in arrival order,
+   * now that it's confirmed. Only the latest conversation's audio is replayed so
+   * the server's audio stream matches what played locally; earlier conversations
+   * are dropped. Aligned with iOS / Android flushPendingAudioMessages.
+   */
+  flushPendingAudio() {
+    if (this.pendingAudioBuffer.isEmpty) return;
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.sessionConfigured) return;
+    const { toReplay, dropped } = this.pendingAudioBuffer.flush();
+    logger.log(
+      `[AnimationWebSocketClient] Flushing ${toReplay.length} buffered audio chunk(s) to driving service.` + (dropped > 0 ? ` Dropped ${dropped} from earlier conversation(s).` : "")
+    );
+    for (const item of toReplay) {
+      this.encodeAndSendAudio(item.conversationId, item.audioData, item.end);
+    }
+  }
   /**
    * Generate conversation ID
    * Uses unified conversation ID generation rule: YYYYMMDDHHmmss_nanoid
@@ -14937,6 +15166,7 @@ class AnimationWebSocketClient extends EventEmitter {
           } else {
             logger.log("[AnimationWebSocketClient] Session confirmed by server");
           }
+          this.flushPendingAudio();
           this.emit("sessionConfirmed", connectionId);
           return;
         }
@@ -15212,7 +15442,7 @@ class NetworkLayer {
       logger.error("[NetworkLayer] Invalid animation message");
       return;
     }
-    const { reqId, animation, avatarId } = message.serverResponseAnimation;
+    const { reqId, animation, avatarId, end } = message.serverResponseAnimation;
     const conversationId = reqId;
     if (avatarId && avatarId !== this.dataController.getAvatarId()) {
       logger.error(`[NetworkLayer] Ignoring animation data for mismatched avatar - expected: ${this.dataController.getAvatarId()}, received: ${avatarId}`);
@@ -15239,7 +15469,7 @@ class NetworkLayer {
     if ((animation == null ? void 0 : animation.keyframes) && animation.keyframes.length > 0) {
       const keyframes = animation.keyframes;
       try {
-        this.dataController.yieldKeyframes(keyframes, conversationId);
+        this.dataController.yieldKeyframes(keyframes, conversationId, end);
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logger.error(`[NetworkLayer] Failed to yield animation data: ${errorMessage}`);
@@ -15606,6 +15836,21 @@ class AvatarController {
     __publicField(this, "onError", null);
     /** Callback for animation type changes (e.g., idle → mono in fallback mode). Aligned with iOS/Android AvatarController.onAnimationState. */
     __publicField(this, "onAnimationState", null);
+    /**
+     * Strategy for handling animation-frame starvation. Default is
+     * {@link FrameStarvationMode.audioIndependent} (audio keeps playing, starvation only
+     * reported as telemetry — historical behavior). Set to {@link FrameStarvationMode.strictSync}
+     * to pause audio when frames run out and resume on new frames, notified via {@link onPlaybackStall}.
+     * Aligned with iOS/Android AvatarController.frameStarvationMode.
+     */
+    __publicField(this, "frameStarvationMode", FrameStarvationMode.audioIndependent);
+    /**
+     * Fires when audio is paused/resumed due to frame starvation. Only invoked in
+     * {@link FrameStarvationMode.strictSync}. `stalled=true` — frames ran out, audio paused;
+     * `stalled=false` — new frames arrived, audio resumed (or conversation ended / fell back).
+     * Aligned with iOS/Android AvatarController.onPlaybackStall.
+     */
+    __publicField(this, "onPlaybackStall", null);
     __publicField(this, "eventListeners", /* @__PURE__ */ new Map());
     // ========== Performance Monitoring ==========
     __publicField(this, "frameRateMonitor", new FrameRateMonitor());
@@ -15634,6 +15879,18 @@ class AvatarController {
     // ========== Frame Starvation Tracking ==========
     __publicField(this, "frameStarvationEvents", []);
     __publicField(this, "isFrameStarved", false);
+    /**
+     * 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
+     * audio tail is normal end-of-round, not starvation, so audio must keep playing to idle
+     * and must never be paused (matters most in strictSync). Reset per conversation.
+     */
+    __publicField(this, "animationEnded", false);
+    /**
+     * Whether audio is currently paused because of frame starvation (strictSync only).
+     * Orthogonal to user pause — user pause/resume does not change it; only frame arrival does.
+     */
+    __publicField(this, "isAudioStalledForStarvation", false);
     // ========== Playback Stuck Detection ==========
     __publicField(this, "playbackStuckCheckState", {
       audioTimeZeroCount: 0,
@@ -16151,7 +16408,7 @@ class AvatarController {
     if (allKeyframes.length === 0) {
       logger.warn(`[AvatarController] No keyframes decoded from ${keyframesDataArray.length} message chunks`);
     }
-    this.yieldKeyframes(allKeyframes, conversationId);
+    this.yieldKeyframes(allKeyframes, conversationId, isEnd);
     return isEnd;
   }
   /**
@@ -16159,12 +16416,15 @@ class AvatarController {
    * External consumers should use `yieldFramesData()` instead.
    * @internal
    */
-  yieldKeyframes(keyframes, conversationId) {
-    var _a;
+  yieldKeyframes(keyframes, conversationId, isEnd = false) {
+    var _a, _b;
     if (!conversationId || typeof conversationId !== "string") {
       logger.error(`[AvatarController] yieldKeyframes requires a valid conversationId. The conversationId is returned by yieldAudioData().`);
       return;
     }
+    if (isEnd) {
+      this.animationEnded = true;
+    }
     const expectedConversationId = this.getEffectiveConversationId();
     if (!expectedConversationId || conversationId !== expectedConversationId) {
       logger.warn(`[AvatarController] Ignoring mismatched animation data - expected conversationId: ${expectedConversationId}, received conversationId: ${conversationId}`);
@@ -16194,6 +16454,14 @@ class AvatarController {
       this.currentKeyframes.push(...flameKeyframes);
     }
     this.emit("keyframesUpdate", this.currentKeyframes);
+    if (this.isAudioStalledForStarvation) {
+      const audioTime = ((_b = this.animationPlayer) == null ? void 0 : _b.getCurrentTime()) ?? 0;
+      const frameIndex = Math.round(audioTime * FLAME_FRAME_RATE);
+      const arrayIndex = frameIndex - this.keyframesOffset;
+      if (arrayIndex >= 0 && arrayIndex < this.currentKeyframes.length) {
+        this.resumeAudioFromStarvation();
+      }
+    }
     if (!this.isPlaying && !this.isStartingPlayback && this.pendingAudioChunks.length > 0 && this.currentKeyframes.length > 0) {
       this.startStreamingPlayback().catch((error) => {
         var _a2;
@@ -16230,7 +16498,9 @@ class AvatarController {
       return;
     }
     logger.log("[AvatarController] Resuming playback");
-    await ((_a = this.animationPlayer) == null ? void 0 : _a.resume());
+    if (!this.isAudioStalledForStarvation) {
+      await ((_a = this.animationPlayer) == null ? void 0 : _a.resume());
+    }
     this.currentState = AvatarState.playing;
     this.notifyConversationState(AvatarState.playing);
     logger.log("[AvatarController] Playback resumed");
@@ -16305,6 +16575,7 @@ class AvatarController {
    * @internal
    */
   clearPlaybackData() {
+    var _a;
     this.currentKeyframes = [];
     this.pendingAudioChunks = [];
     this.lastRenderedFrameIndex = -1;
@@ -16312,6 +16583,11 @@ class AvatarController {
     this.isFallbackMode = false;
     this.lastSyncLogTime = 0;
     this.lastOutOfBoundsState = false;
+    this.animationEnded = false;
+    if (this.isAudioStalledForStarvation) {
+      this.isAudioStalledForStarvation = false;
+      (_a = this.onPlaybackStall) == null ? void 0 : _a.call(this, false);
+    }
     if (this.playbackMode === DrivingServiceMode.backend) {
       this.hostModeMetrics = {
         accumulatedBytes: 0,
@@ -16574,6 +16850,13 @@ class AvatarController {
     const hasAnimationData = this.currentKeyframes.length > 0;
     const hasAudioData = ((_b = streamingPlayer.audioChunks) == null ? void 0 : _b.length) > 0;
     const isNotPaused = this.currentState !== AvatarState.paused;
+    if (this.isAudioStalledForStarvation) {
+      state.audioTimeZeroCount = 0;
+      state.audioTimeStuckCount = 0;
+      state.lastAudioTime = 0;
+      state.reported = false;
+      return false;
+    }
     if (!hasAnimationData || !hasAudioData || this.currentState === AvatarState.paused) {
       state.audioTimeZeroCount = 0;
       state.audioTimeStuckCount = 0;
@@ -16677,13 +16960,49 @@ class AvatarController {
           this.frameStarvationEvents.push({ audioTime, reqEnd: this.reqEnd });
         }
       }
+      if (!this.animationEnded) {
+        this.pauseAudioForStarvation();
+      }
     } else {
       this.isFrameStarved = false;
       if (isOutOfBounds !== this.lastOutOfBoundsState) {
         this.lastOutOfBoundsState = isOutOfBounds;
       }
+      this.resumeAudioFromStarvation();
     }
   }
+  /**
+   * strictSync: pause audio on frame starvation, waiting for new frames.
+   *
+   * The default (audioIndependent) keeps audio running and lets animation catch up;
+   * strictSync instead pauses audio so audio/video stay strictly in sync. Idempotent;
+   * only fires onPlaybackStall once. No-op unless mode is strictSync.
+   * @internal
+   */
+  pauseAudioForStarvation() {
+    var _a, _b;
+    if (this.frameStarvationMode !== FrameStarvationMode.strictSync) return;
+    if (this.isAudioStalledForStarvation) return;
+    if (!this.isPlaying) return;
+    (_a = this.animationPlayer) == null ? void 0 : _a.pause();
+    this.isAudioStalledForStarvation = true;
+    logger.log("[AvatarController] Frame starvation: paused audio, waiting for frames.");
+    (_b = this.onPlaybackStall) == null ? void 0 : _b.call(this, true);
+  }
+  /**
+   * strictSync: frame starvation resolved (new frames arrived). Resumes audio and fires
+   * onPlaybackStall(false). Idempotent — returns immediately if not stalled (so it is a
+   * no-op in audioIndependent, where isAudioStalledForStarvation stays false).
+   * @internal
+   */
+  resumeAudioFromStarvation() {
+    var _a, _b;
+    if (!this.isAudioStalledForStarvation) return;
+    this.isAudioStalledForStarvation = false;
+    void ((_a = this.animationPlayer) == null ? void 0 : _a.resume());
+    logger.log("[AvatarController] Frame starvation recovered: resumed audio.");
+    (_b = this.onPlaybackStall) == null ? void 0 : _b.call(this, false);
+  }
   /**
    * Start playback loop
    * @internal
@@ -16729,6 +17048,7 @@ class AvatarController {
     }
     logger.warn("[AvatarController] Enabling fallback mode");
     this.isFallbackMode = true;
+    this.resumeAudioFromStarvation();
     logEvent("fallback_mode_entered", "warning", {
       avatar_id: this.avatar.id,
       reason,
@@ -17253,9 +17573,12 @@ class AvatarDownloader {
    * @internal
    */
   async loadUnifiedTemplate() {
+    var _a;
     await PwaCacheManager.checkTemplateCacheVersion();
     const startTime = Date.now();
-    const { cdnBase, unifiedModelPath } = APP_CONFIG.flame;
+    const region = ((_a = AvatarSDK.configuration) == null ? void 0 : _a.region) || DEFAULT_REGION;
+    const cdnBase = getFlameCdnBase(region);
+    const { unifiedModelPath } = APP_CONFIG.flame;
     const url = `${cdnBase}/${unifiedModelPath}`;
     logger.log(`📥 Loading unified template from: ${url}`);
     const cached = await PwaCacheManager.getTemplateResource(url);
@@ -17526,7 +17849,7 @@ class AvatarDownloader {
             }
             let error;
             if (response.status === 404) {
-              const urlMatch = url.match(/\/v2\/character\/([^/?]+)/);
+              const urlMatch = url.match(/\/v2\/(?:character|avatar)\/([^/?]+)/);
               const extractedCharacterId = urlMatch ? urlMatch[1] : "unknown";
               const callerHeaders = options.headers || {};
               const callerTraceId = callerHeaders["x-sp-trace-id"];
@@ -17562,10 +17885,50 @@ class AvatarDownloader {
     };
   }
   /**
-   * Get single character by ID from AvatarKit SDK API (v2, iOS compatible)
+   * Map the new `/v2/avatar/{id}` `AvatarAsset` payload onto the internal
+   * `CharacterMeta` shape used by the existing download / render pipeline.
+   *
+   * The backend (grpc-gateway) serialises proto fields as camelCase JSON, so the
+   * runtime object is loosely shaped like the generated `AvatarAsset`. We:
+   * - lift `models.gs` into `models.gsStandard` (downloader/asset-count read gsStandard)
+   * - rename `animations.frameFallback` → `animations.frameMono`
+   * - fold the inline `camera` / `transform` into `characterSettings` so the
+   *   renderer's `resolveCameraConfig` reads structured values and no camera
+   *   resource is downloaded (top-level `camera` is intentionally left unset)
+   * @internal
+   */
+  mapAvatarAssetToCharacterMeta(asset, avatarId) {
+    var _a, _b, _c, _d, _e2;
+    const characterSettings = {
+      ...asset.camera ? { camera: { ...asset.camera } } : {},
+      ...asset.transform ? { transform: { ...asset.transform } } : {}
+    };
+    return {
+      characterId: avatarId,
+      version: asset.version ?? "",
+      updatedAt: asset.updatedAt,
+      models: {
+        shape: (_a = asset.models) == null ? void 0 : _a.shape,
+        gsStandard: (_b = asset.models) == null ? void 0 : _b.gs
+      },
+      animations: {
+        frameIdle: (_c = asset.animations) == null ? void 0 : _c.frameIdle,
+        frameMono: (_d = asset.animations) == null ? void 0 : _d.frameFallback
+      },
+      customAnimations: ((_e2 = asset.animations) == null ? void 0 : _e2.customAnimations) ?? [],
+      characterSettings
+    };
+  }
+  /**
+   * Get single avatar by ID from AvatarKit SDK API (v2 driven-ingress avatar API).
    * Domain: composed from region as api.${region}.spatius.ai
    * Auth: Public endpoint, no authentication required
-   * Returns CharacterMeta with nested resource structure
+   * Fetches the new `AvatarAsset` payload from `/v2/avatar/{id}` and maps it onto
+   * the internal `CharacterMeta` shape consumed by the download / render pipeline:
+   * - `models.gs` → `models.gsStandard`
+   * - `animations.frameFallback` → `animations.frameMono`
+   * - inline `camera` / `transform` → `characterSettings.{camera,transform}`
+   *   (so the renderer reads structured values directly and no camera resource is downloaded)
    * @internal
    */
   async getCharacterById(characterId, options) {
@@ -17578,7 +17941,7 @@ class AvatarDownloader {
         throw new Error("Request cancelled");
       }
       const client = this.getSdkApiClient();
-      const response = await client.request(`/v2/character/${characterId}`, {
+      const response = await client.request(`/v2/avatar/${characterId}`, {
         method: "GET",
         headers: { "x-sp-trace-id": traceId },
         signal
@@ -17597,7 +17960,7 @@ class AvatarDownloader {
         duration,
         trace_id: traceId
       });
-      return response;
+      return this.mapAvatarAssetToCharacterMeta(response, characterId);
     } catch (error) {
       if (error instanceof Error && (error.name === "AbortError" || error.message === "Request cancelled")) {
         logEvent("fetch_avatar_metadata_cancelled", "info", {
@@ -20793,6 +21156,10 @@ class AvatarView {
       },
       onPlayFallback: () => {
         this.playAnimation(AnimationType.idle, true);
+        if (!this.cachedIdleFirstFrame) {
+          this.getCachedIdleFirstFrame().catch(() => {
+          });
+        }
         this.isConversationActive = true;
         this.lastRenderedFrameIndex = -1;
       },
@@ -21465,6 +21832,7 @@ export {
   ConnectionState as C,
   DrivingServiceMode as D,
   ErrorCode as E,
+  FrameStarvationMode as F,
   LogLevel as L,
   RenderQuality as R,
   TransitionType as T,

package/dist/index.js

@@ -1,4 +1,4 @@
-import { k, b, c, o, f, d, n, g, C, m, i, D, E, j, L, h, R, p, T, q } from "./index-CVQn5uEB.js";
+import { k, b, c, o, f, d, n, g, C, m, i, D, E, F, j, L, h, R, p, T, q } from "./index-DHCQ9wsL.js";
 export {
   k as AnimationType,
   b as Avatar,
@@ -13,6 +13,7 @@ export {
   i as DEFAULT_REGION,
   D as DrivingServiceMode,
   E as ErrorCode,
+  F as FrameStarvationMode,
   j as LoadProgress,
   L as LogLevel,
   h as RENDER_QUALITY_PARAMS,

package/dist/types/index.d.ts

@@ -7,6 +7,19 @@ export declare enum DrivingServiceMode {
     /** Driven by host application */
     backend = "backend"
 }
+/**
+ * Strategy for handling animation-frame starvation (animation frames can't keep up
+ * with the audio clock).
+ *
+ * - `audioIndependent` (default): audio keeps playing, animation catches up; starvation
+ *   is only reported as telemetry. This is the historical default behavior.
+ * - `strictSync`: pause audio and wait when frames run out, resume once new frames
+ *   arrive, notifying via `AvatarController.onPlaybackStall`.
+ */
+export declare enum FrameStarvationMode {
+    audioIndependent = "audioIndependent",
+    strictSync = "strictSync"
+}
 export declare enum LogLevel {
     /** Disable all logs */
     off = "off",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatius/avatarkit",
   "type": "module",
-  "version": "1.1.0-beta.1",
+  "version": "1.2.0-beta.1",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",
@@ -48,6 +48,7 @@
     "build": "SDK_BUILD=true vite build --mode library && npm run build:vite-plugin && npm run build:next-plugin",
     "build:vite-plugin": "tsc vite.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
     "build:next-plugin": "tsc next.ts --outDir . --module esnext --target es2020 --moduleResolution bundler --esModuleInterop --skipLibCheck --declaration --declarationMap",
+    "prepare": "npm run build",
     "dev": "vite build --mode library --watch",
     "demo": "vite --config demo/vite.config.mjs",
     "demo:benchmark": "vite --config benchmark-demo/vite.config.mjs",