@spatialwalk/avatarkit 1.0.0-beta.101 → 1.0.0-beta.103

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.0.0-beta.103]
+
+### 🔧 Internal
+
+- Optimize internal type exports
+
+## [1.0.0-beta.102]
+
+### 🐛 Bugfixes
+
+- **Template loading telemetry** — Fixed `template_resources_load_measure` event not being reported when loading the unified template model. Added PWA caching support for the unified model to enable faster subsequent loads.
+
 ## [1.0.0-beta.101]
 
 ### ⚡ Performance

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

package/dist/core/AvatarView.d.ts

@@ -1,4 +1,4 @@
-import { CameraConfig, KeyframeData } from '../types';
+import { CameraConfig } from '../types';
 import { Avatar } from './Avatar';
 import { AvatarController } from './AvatarController';
 export declare class AvatarView {
@@ -57,19 +57,6 @@ export declare class AvatarView {
      * 更新相机配置
      */
     updateCameraConfig(cameraConfig: CameraConfig): void;
-    /**
-     * Render specified keyframe (pure rendering mode, no audio-animation synchronization)
-     * Suitable for scenarios where external application controls audio playback and animation playback
-     * @param keyframeData - Keyframe data
-     * @param enableIdleRendering - Whether to enable idle loop rendering. true: Enable idle rendering and return immediately (skip this keyframe); false: Disable idle rendering and process keyframe (default)
-     */
-    renderFlame(keyframeData: KeyframeData, enableIdleRendering?: boolean): Promise<void>;
-    generateTransition(options: {
-        from?: KeyframeData;
-        to?: KeyframeData;
-        frameCount: number;
-        useLinear?: boolean;
-    }): Promise<KeyframeData[]>;
     /**
      * Render a single animation frame from raw protobuf data.
      *
@@ -107,6 +94,22 @@ export declare class AvatarView {
      * Start idle animation (stop pure rendering mode, resume idle loop).
      */
     startIdle(): void;
+    /**
+     * Generate transition frames from protobuf data.
+     *
+     * Decodes the protobuf, extracts the target keyframe, and generates
+     * transition frames from the current idle position to the target.
+     * The caller is responsible for playing the returned frames at the desired cadence.
+     *
+     * @param data - Raw protobuf bytes containing the target frame
+     * @param frameCount - Number of transition frames to generate
+     * @param options - Additional options
+     * @param options.useLinear - Use linear interpolation (default: true)
+     * @returns Array of opaque keyframe data for sequential playback
+     */
+    generateTransitionFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number, options?: {
+        useLinear?: boolean;
+    }): Promise<unknown[]>;
     /**
      * Cancel any in-progress frame sequence playback.
      * Called by renderFromProtobuf when streaming frames arrive during transition.

package/dist/{index-C0A1HA8M.js → index-BqX6ubaV.js}

@@ -2718,16 +2718,14 @@ const APP_CONFIG = {
     sampleRate: 16e3
     // Audio sample rate (backend requires 16kHz)
   },
-  // FLAME global template resource CDN
-  // These resources are base templates shared by all characters
+  // FLAME unified template model CDN
+  // Single compressed model shared by all characters
   flame: {
-    cdnBaseUrl: "https://cdn.spatialwalk.top/public",
-    resources: {
-      flameModel: "model.pb",
-      flameTemplate: "fm/template.pb",
-      teethPb: "fm/teeth.pb",
-      teethNpz: "teeth.npz"
-    }
+    cdn: {
+      default: "https://cdn.spatialwalk.top/public",
+      intl: "https://cdn.spatialwalk.cloud/public"
+    },
+    unifiedModelPath: "base_model.pb.gz"
   }
 };
 var t = "undefined" != typeof window ? window : void 0, i = "undefined" != typeof globalThis ? globalThis : t;
@@ -9510,7 +9508,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-BULgPjpe.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-CxtOBEsC.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -11312,24 +11310,8 @@ class AvatarSDK {
     try {
       const { AvatarDownloader: AvatarDownloader2 } = await Promise.resolve().then(() => AvatarDownloader$1);
       const downloader = new AvatarDownloader2();
-      let templateResources;
-      const cdnBase = ((_a = this._configuration) == null ? void 0 : _a.environment) === Environment.intl ? "https://cdn.spatialwalk.cloud/public" : "https://cdn.spatialwalk.top/public";
-      const unifiedModelUrl = `${cdnBase}/base_model.pb.gz`;
-      try {
-        const response = await fetch(unifiedModelUrl);
-        if (response.ok) {
-          const decompressedStream = response.body.pipeThrough(new DecompressionStream("gzip"));
-          const decompressedResponse = new Response(decompressedStream);
-          const buffer = await decompressedResponse.arrayBuffer();
-          templateResources = { unifiedModel: buffer };
-          logger.log(`[AvatarSDK] Using unified model (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`);
-        } else {
-          logger.log("[AvatarSDK] Unified model not available, falling back to multi-file mode");
-          templateResources = await downloader.loadGlobalFlameResources();
-        }
-      } catch {
-        templateResources = await downloader.loadGlobalFlameResources();
-      }
+      const environment = ((_a = this._configuration) == null ? void 0 : _a.environment) === Environment.intl ? "intl" : "cn";
+      const templateResources = await downloader.loadUnifiedTemplate(environment);
       const success = await this._avatarCore.loadTemplateResourcesFromBuffers(templateResources);
       if (success) {
         logger.log("[AvatarSDK] Template resources initialized successfully");
@@ -11566,7 +11548,7 @@ class AvatarSDK {
 __publicField(AvatarSDK, "_initializationState", "uninitialized");
 __publicField(AvatarSDK, "_initializingPromise", null);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.101");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.103");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 __publicField(AvatarSDK, "_cachedDeviceScore", null);
@@ -13532,12 +13514,14 @@ class AvatarController {
         this.notifyConversationState(AvatarState.idle);
         this.emit("stopRendering");
         if (this.frameStarvationEvents.length > 0) {
+          const hasReqEnd = this.frameStarvationEvents.some((e2) => e2.reqEnd);
           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)))
+            starvation_times: this.frameStarvationEvents.map((e2) => Number(e2.audioTime.toFixed(3))),
+            ...hasReqEnd ? { req_end: true } : {}
           });
         }
         this.frameStarvationEvents = [];
@@ -13691,7 +13675,11 @@ class AvatarController {
       if (!this.isFrameStarved) {
         this.isFrameStarved = true;
         const audioTime = ((_a = this.animationPlayer) == null ? void 0 : _a.getCurrentTime()) ?? 0;
-        this.frameStarvationEvents.push({ audioTime });
+        const totalKeyframes = this.currentKeyframes.length + this.keyframesOffset;
+        const frameDiff = frameIndex - totalKeyframes;
+        if (!(this.reqEnd && frameDiff <= 1)) {
+          this.frameStarvationEvents.push({ audioTime, reqEnd: this.reqEnd });
+        }
       }
     } else {
       this.isFrameStarved = false;
@@ -14395,136 +14383,60 @@ class AvatarDownloader {
     this.baseAssetsPath = baseAssetsPath;
   }
   /**
-   * Load template resources from CharacterMeta flame CDN URLs
-   * Falls back to global CDN config if not provided by API
+   * Load unified template model (single gzip-compressed file)
+   * Includes PWA cache, retry, integrity check, and telemetry
    * @internal
    */
-  async loadTemplateResources(flameResources, progressCallback = null) {
-    var _a, _b, _c, _d;
-    await PwaCacheManager.checkTemplateCacheVersion();
-    const useApiResources = flameResources && Object.keys(flameResources).length > 0;
-    if (!useApiResources) {
-      logger.log("Template resources not provided in CharacterMeta, using global CDN config");
-      return this.loadGlobalFlameResources(progressCallback);
-    }
-    logger.log("Using template resources from CharacterMeta API");
-    const templateFiles = {
-      flameModel: {
-        url: (_a = flameResources.flameModel) == null ? void 0 : _a.remote,
-        resourceName: "model.pb"
-      },
-      flameTemplate: {
-        url: (_b = flameResources.flameTemplate) == null ? void 0 : _b.remote,
-        resourceName: "flame_template.pb"
-      },
-      teethPb: {
-        url: (_c = flameResources.teethPb) == null ? void 0 : _c.remote,
-        resourceName: "teeth.pb"
-      },
-      teethNpz: {
-        url: (_d = flameResources.teethNpz) == null ? void 0 : _d.remote,
-        resourceName: "teeth.npz"
-      }
-    };
-    const totalFiles = Object.keys(templateFiles).length;
-    let loadedFiles = 0;
-    const updateProgress = (filename, loaded) => {
-      if (progressCallback) {
-        if (loaded)
-          loadedFiles++;
-        progressCallback({
-          stage: "template",
-          filename,
-          loaded: loadedFiles,
-          total: totalFiles,
-          progress: Math.round(loadedFiles / totalFiles * 100)
-        });
-      }
-    };
-    const templateResources = {};
-    const promises = Object.entries(templateFiles).map(async ([key, { url, resourceName }]) => {
-      if (!url) {
-        throw new Error(`[loadTemplateResources] Missing CDN URL for ${key} (${resourceName})`);
-      }
-      updateProgress(resourceName, false);
-      logger.log(`📥 Loading ${key} from API CDN: ${url}`);
-      const { data: buffer } = await downloadResource(url, { resourceType: "template" });
-      logger.log(`✅ ${key} loaded: ${buffer.byteLength} bytes`);
-      templateResources[key] = buffer;
-      updateProgress(resourceName, true);
-    });
-    await Promise.all(promises);
-    return templateResources;
-  }
-  /**
-   * Load global FLAME template resources from CDN
-   * Uses centralized FLAME CDN config (shared across all characters)
-   * @internal 供内部使用（测试、调试等场景），SDK 初始化默认使用本地打包的资源
-   */
-  async loadGlobalFlameResources(progressCallback = null) {
-    var _a;
+  async loadUnifiedTemplate(environment) {
     await PwaCacheManager.checkTemplateCacheVersion();
     const startTime = Date.now();
-    const { cdnBaseUrl, resources } = APP_CONFIG.flame;
-    const templateFiles = {
-      flameModel: {
-        url: `${cdnBaseUrl}/${resources.flameModel}`,
-        resourceName: resources.flameModel
-      },
-      flameTemplate: {
-        url: `${cdnBaseUrl}/${resources.flameTemplate}`,
-        resourceName: resources.flameTemplate
-      },
-      teethPb: {
-        url: `${cdnBaseUrl}/${resources.teethPb}`,
-        resourceName: resources.teethPb
-      },
-      teethNpz: {
-        url: `${cdnBaseUrl}/${resources.teethNpz}`,
-        resourceName: resources.teethNpz
-      }
-    };
-    const totalFiles = Object.keys(templateFiles).length;
-    let loadedFiles = 0;
-    const updateProgress = (filename, loaded) => {
-      if (progressCallback) {
-        if (loaded)
-          loadedFiles++;
-        progressCallback({
-          stage: "template",
-          filename,
-          loaded: loadedFiles,
-          total: totalFiles,
-          progress: Math.round(loadedFiles / totalFiles * 100)
-        });
-      }
-    };
-    const templateResources = {};
-    const cacheInfos = [];
-    try {
-      const promises = Object.entries(templateFiles).map(async ([key, { url, resourceName }]) => {
-        updateProgress(resourceName, false);
-        logger.log(`📥 Loading ${key} from global CDN: ${url}`);
-        const { data: buffer, cacheInfo } = await downloadResource(url, { resourceType: "template" });
-        logger.log(`✅ ${key} loaded: ${buffer.byteLength} bytes`);
-        templateResources[key] = buffer;
-        cacheInfos.push(cacheInfo);
-        updateProgress(resourceName, true);
-      });
-      await Promise.all(promises);
-      const cacheHit = cacheInfos.length > 0 && cacheInfos.every((info) => info.cacheHit);
-      const cacheType = ((_a = cacheInfos[0]) == null ? void 0 : _a.cacheType) || "none";
+    const { cdn, unifiedModelPath } = APP_CONFIG.flame;
+    const cdnBase = environment === "intl" ? cdn.intl : cdn.default;
+    const url = `${cdnBase}/${unifiedModelPath}`;
+    logger.log(`📥 Loading unified template from: ${url}`);
+    const cached = await PwaCacheManager.getTemplateResource(url);
+    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", {
         duration,
-        file_count: totalFiles,
-        cache_hit: cacheHit,
-        cache_type: cacheType
+        file_count: 1,
+        cache_hit: true,
+        cache_type: "pwa"
       });
-      return templateResources;
-    } catch (error) {
-      throw error;
+      return { unifiedModel: cached };
+    }
+    const maxRetries = 3;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        }
+        const decompressedStream = response.body.pipeThrough(new DecompressionStream("gzip"));
+        const decompressedResponse = new Response(decompressedStream);
+        const buffer = await decompressedResponse.arrayBuffer();
+        logger.log(`✅ Unified template loaded (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+        PwaCacheManager.putTemplateResource(url, buffer).catch((err) => {
+          logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
+        });
+        const duration = Date.now() - startTime;
+        logEvent("template_resources_load_measure", "info", {
+          duration,
+          file_count: 1,
+          cache_hit: false,
+          cache_type: "none"
+        });
+        return { unifiedModel: buffer };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxRetries) {
+          logger.warn(`[loadUnifiedTemplate] Attempt ${attempt}/${maxRetries} failed, retrying...`);
+        }
+      }
     }
+    throw lastError || new Error(`Failed to download unified template after ${maxRetries} attempts`);
   }
   /**
    * Load camera settings from CharacterMeta (optional)
@@ -14598,7 +14510,7 @@ class AvatarDownloader {
           filename,
           loaded: loadedFiles,
           total: totalFiles,
-          progress: Math.round(loadedFiles / totalFiles * 100)
+          progress: loadedFiles / totalFiles
         });
       }
     };
@@ -14999,7 +14911,7 @@ const _AvatarManager = class _AvatarManager {
       if (cachedVersion === newVersion && cachedModelType === requestedModelType) {
         logger.log(`[AvatarManager] Avatar ${id} found in cache with same version (${cachedVersion}) and model type (${cachedModelType}), returning cached`);
         cached.updateCharacterMeta(characterMeta);
-        this.notifyAllRequests(task, { type: LoadProgress.downloading, progress: 100 });
+        this.notifyAllRequests(task, { type: LoadProgress.downloading, progress: 1 });
         return cached;
       } else {
         logger.log(`[AvatarManager] Avatar ${id} cache invalid: version=${cachedVersion}->${newVersion}, modelType=${cachedModelType}->${requestedModelType}, reloading...`);
@@ -15009,7 +14921,7 @@ const _AvatarManager = class _AvatarManager {
       }
     }
     const totalAssets = this.countTotalAssets(characterMeta);
-    const metaProgress = Math.round(1 / (1 + totalAssets) * 100);
+    const metaProgress = 1 / (1 + totalAssets);
     this.notifyAllRequests(task, { type: LoadProgress.downloading, progress: metaProgress });
     if (signal.aborted) {
       throw new Error("Task cancelled");
@@ -15023,7 +14935,7 @@ const _AvatarManager = class _AvatarManager {
       progressCallback: (info) => {
         if (info.loaded > downloadedCount) {
           downloadedCount = info.loaded;
-          const progress = Math.round((1 + downloadedCount) / (1 + totalAssets) * 100);
+          const progress = (1 + downloadedCount) / (1 + totalAssets);
           this.notifyAllRequests(task, { type: LoadProgress.downloading, progress });
         }
       }
@@ -18042,9 +17954,9 @@ class AvatarView {
   }
   /**
    * Render specified keyframe (pure rendering mode, no audio-animation synchronization)
-   * Suitable for scenarios where external application controls audio playback and animation playback
    * @param keyframeData - Keyframe data
-   * @param enableIdleRendering - Whether to enable idle loop rendering. true: Enable idle rendering and return immediately (skip this keyframe); false: Disable idle rendering and process keyframe (default)
+   * @param enableIdleRendering - Whether to enable idle loop rendering
+   * @internal
    */
   async renderFlame(keyframeData, enableIdleRendering) {
     if (!this.isInitialized || !this.renderSystem) {
@@ -18075,6 +17987,7 @@ class AvatarView {
       throw error;
     }
   }
+  /** @internal */
   async generateTransition(options) {
     if (!this.isInitialized) {
       throw new Error("AvatarView not initialized");
@@ -18186,6 +18099,30 @@ class AvatarView {
   startIdle() {
     this.renderFlame(void 0, true);
   }
+  /**
+   * Generate transition frames from protobuf data.
+   *
+   * Decodes the protobuf, extracts the target keyframe, and generates
+   * transition frames from the current idle position to the target.
+   * The caller is responsible for playing the returned frames at the desired cadence.
+   *
+   * @param data - Raw protobuf bytes containing the target frame
+   * @param frameCount - Number of transition frames to generate
+   * @param options - Additional options
+   * @param options.useLinear - Use linear interpolation (default: true)
+   * @returns Array of opaque keyframe data for sequential playback
+   */
+  async generateTransitionFromProtobuf(data, frameCount, options) {
+    const keyframes = decodeAnimationKeyframes(data);
+    if (!keyframes || keyframes.length === 0) {
+      return [];
+    }
+    return this.generateTransition({
+      to: keyframes[0],
+      frameCount,
+      useLinear: (options == null ? void 0 : options.useLinear) ?? true
+    });
+  }
   /**
    * Cancel any in-progress frame sequence playback.
    * Called by renderFromProtobuf when streaming frames arrive during transition.

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-C0A1HA8M.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-BqX6ubaV.js";
 export {
   b as Avatar,
   c as AvatarController,

package/dist/types/index.d.ts

@@ -119,26 +119,6 @@ export interface CameraConfig {
     up?: [number, number, number];
     aspect?: number;
 }
-/**
- * Animation keyframe data
- * Used to represent avatar pose and expression parameters
- */
-export interface KeyframeData {
-    /** Translation [x, y, z] */
-    translation: number[];
-    /** Rotation [x, y, z] (Euler angles, in radians) */
-    rotation: number[];
-    /** Neck pose [x, y, z] (in radians) */
-    neckPose: number[];
-    /** Jaw pose [x, y, z] (in radians) */
-    jawPose: number[];
-    /** Eye pose [x, y, z, x, y, z] (3 parameters for each eye) */
-    eyePose: number[];
-    /** Eyelid [x, y] */
-    eyeLid: number[];
-    /** Expression parameters array */
-    expression: number[];
-}
 /**
  * Post-processing parameter configuration
  * Used to overlay in real-time on animation parameters returned by the server

package/package.json

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