@spatialwalk/avatarkit 1.0.0-beta.7 → 1.0.0-beta.71

package/dist/config/app-config.d.ts

@@ -3,9 +3,9 @@ export declare const APP_CONFIG: {
     readonly debug: boolean;
     rendering: {
         /**
-         * 排序模式
-         * - 'balance': 性能优先，首帧排序后复用（默认）
-         * - 'quality': 质量优先，每帧重新排序
+         * Sort mode
+         * - 'balance': Performance first, sort first frame then reuse (default)
+         * - 'quality': Quality first, re-sort every frame
          */
         sortMode: "balance" | "quality";
     };
@@ -41,4 +41,3 @@ export declare const APP_CONFIG: {
         enablePerformanceMetrics: boolean;
     };
 };
-//# sourceMappingURL=app-config.d.ts.map

package/dist/config/constants.d.ts

@@ -1,21 +1,14 @@
 import { Environment } from '../types';
-export declare const CLS_TRACK_EVENTS: boolean;
-/**
- * 获取 CLS 配置（需要传入环境）
- */
-export declare function getCLSConfig(environment: Environment): {
-    endpoint: string;
-    topicId: string;
-    secretId: string;
-    secretKey: string;
-    token: string;
-};
-export declare const CLS_CONFIG: {
-    endpoint: string;
-    topicId: string;
-    secretId: string;
-    secretKey: string;
-    token: string;
+export declare const POSTHOG_HOST_CN: string;
+export declare const POSTHOG_API_KEY_CN: string;
+export declare const POSTHOG_HOST_INTL: string;
+export declare const POSTHOG_API_KEY_INTL: string;
+export declare const POSTHOG_TRACK_EVENTS: boolean;
+export declare const POSTHOG_PROJECT_NAME: string;
+export declare function getPostHogConfig(_environment: Environment): {
+    host: string;
+    apiKey: string;
+    disableCompression: boolean;
 };
 export declare const ENV_TEST: boolean;
 /**
@@ -26,4 +19,3 @@ export declare const ENV_TEST: boolean;
  * - URL has debug=1 parameter
  */
 export declare function isDebugMode(): boolean;
-//# sourceMappingURL=constants.d.ts.map

package/dist/config/sdk-config-loader.d.ts

@@ -1,12 +1,6 @@
-import { Environment } from '../types';
 /**
- * 从远程配置接口获取 SDK 配置
- * @param version SDK 版本号
- * @returns 解析后的配置映射
+ * SDK configuration loader
+ * Fetch SDK endpoint configuration from remote config API
+ * @internal
  */
-export declare function fetchSdkConfig(version: string): Promise<Partial<Record<Environment, string>>>;
-/**
- * 清除配置缓存（用于测试或重新加载）
- */
-export declare function clearSdkConfigCache(): void;
-//# sourceMappingURL=sdk-config-loader.d.ts.map
+export {};

package/dist/core/Avatar.d.ts

@@ -1,23 +1,11 @@
 import { CharacterMeta } from '../types';
-import { PreloadResult } from './AvatarDownloader';
 export declare class Avatar {
     readonly id: string;
     private characterMeta;
     private resources;
     /**
-     * 构造函数（内部使用）
-     * @param id 数字人 ID
-     * @param characterMeta 角色元数据
-     * @param resources 资源数据
-     */
-    constructor(id: string, characterMeta: CharacterMeta, resources: PreloadResult);
-    /**
-     * 获取角色元数据（内部使用）
+     * Get character metadata
+     * @returns Character metadata, including all configuration information (version, resource URLs, camera config, etc.)
      */
     getCharacterMeta(): CharacterMeta;
-    /**
-     * 获取资源数据（内部使用）
-     */
-    getResources(): PreloadResult;
 }
-//# sourceMappingURL=Avatar.d.ts.map

package/dist/core/AvatarController.d.ts

@@ -1,10 +1,10 @@
 import { Flame } from '../generated/driveningress/v1/driveningress';
 import { Avatar } from './Avatar';
 import { AnimationPlayer } from '../audio/AnimationPlayer';
-import { AvatarState, ConnectionState, AvatarPlaybackMode } from '../types';
+import { AvatarState, ConnectionState, DrivingServiceMode, ConversationState, PostProcessingConfig, KeyframeData } from '../types';
 export declare class AvatarController {
     private networkLayer?;
-    readonly playbackMode: AvatarPlaybackMode;
+    private readonly playbackMode;
     protected avatar: Avatar;
     protected animationPlayer: AnimationPlayer | null;
     protected currentKeyframes: Flame[];
@@ -13,140 +13,150 @@ export declare class AvatarController {
         isLast: boolean;
     }>;
     protected isPlaying: boolean;
+    private isStartingPlayback;
     protected isConnected: boolean;
     protected currentState: AvatarState;
+    private currentConversationId;
+    private reqEnd;
     onConnectionState: ((state: ConnectionState) => void) | null;
-    onAvatarState: ((state: AvatarState) => void) | null;
+    onConversationState: ((state: ConversationState) => void) | null;
     onError: ((error: Error) => void) | null;
     private eventListeners;
     private renderCallback?;
-    private transitionCompleteCallback?;
+    private characterHandle;
+    private characterId;
+    private postProcessingConfig;
     private playbackLoopId;
     private lastRenderedFrameIndex;
+    private keyframesOffset;
+    private readonly MAX_KEYFRAMES;
+    private readonly KEYFRAMES_CLEANUP_THRESHOLD;
+    private lastSyncLogTime;
+    private lastOutOfBoundsState;
+    private isAudioOnlyMode;
+    private playbackStuckCheckState;
+    private readonly MAX_AUDIO_TIME_ZERO_COUNT;
+    private readonly MAX_AUDIO_TIME_STUCK_COUNT;
+    private readonly AUDIO_TIME_STUCK_THRESHOLD;
+    private hostModeMetrics;
+    private readonly audioBytesPerSecond;
     constructor(avatar: Avatar, options?: {
-        playbackMode?: AvatarPlaybackMode;
+        playbackMode?: DrivingServiceMode;
     });
     /**
-     * 获取 Avatar ID（供 NetworkLayer 使用）
+     * Get current conversation ID
+     * Returns the current conversation ID for the active audio session
+     * @returns Current conversation ID, or null if no active session
      */
-    getAvatarId(): string;
+    getCurrentConversationId(): string | null;
     /**
-     * 获取播放状态（供 NetworkLayer 使用）
+     * Initialize audio context (must be called in user gesture context)
+     *
+     * This method must be called before any audio operations (send, yieldAudioData, etc.)
+     * to ensure AudioContext is created and initialized in a user gesture context.
+     *
+     * @example
+     * // In user click handler
+     * button.addEventListener('click', async () => {
+     *   await avatarView.controller.initializeAudioContext()
+     *   // Now you can safely use send() or yieldAudioData()
+     * })
      */
-    getIsPlaying(): boolean;
+    initializeAudioContext(): Promise<void>;
     /**
-     * 设置连接状态（供 NetworkLayer 使用）
-     */
-    setConnected(connected: boolean): void;
-    /**
-     * 获取连接状态
-     */
-    get connected(): boolean;
-    /**
-     * 获取当前状态
-     */
-    get state(): AvatarState;
-    /**
-     * 获取动画播放器实例
-     * @internal
-     */
-    getAnimationPlayer(): AnimationPlayer | null;
-    /**
-     * 启动服务（仅网络模式）
+     * Start service (SDK mode only)
      */
     start(): Promise<void>;
     /**
-     * 发送音频到服务器（仅网络模式）
-     * 同时缓存到数据层用于播放
+     * Send audio to server (SDK mode only)
+     * Also cache to data layer for playback
+     * @returns conversationId - Conversation ID for this audio session
      */
-    send(audioData: ArrayBuffer, end?: boolean): void;
+    send(audioData: ArrayBuffer, end?: boolean): string | null;
     /**
-     * 关闭服务（仅网络模式）
+     * Close service (SDK mode only)
      */
     close(): void;
     /**
-     * 开始播放（外部数据模式）
-     * 必须先调用此方法，传入初始数据开始播放
-     */
-    play(initialAudioChunks?: Array<{
-        data: Uint8Array;
-        isLast: boolean;
-    }>, initialKeyframes?: Flame[]): Promise<void>;
-    /**
-     * 发送音频数据（外部数据模式）
-     * 在 play() 之后流式添加剩余音频数据
-     */
-    sendAudioChunk(data: Uint8Array, isLast?: boolean): void;
-    /**
-     * 发送动画关键帧（外部数据模式或网络模式）
-     * 在 play() 之后流式添加剩余动画数据
+     * Send audio data (host mode)
+     * Stream additional audio data after playback()
+     * @returns conversationId - Conversation ID for this audio session
      */
-    sendKeyframes(keyframes: Flame[]): void;
+    yieldAudioData(data: Uint8Array, isLast?: boolean): string | null;
     /**
-     * 打断当前播放
+     * Send animation keyframes (host mode or SDK mode)
+     * Stream additional animation data after playback()
+     *
+     * Public API: accepts binary data array (protobuf encoded Message array)
+     * @param keyframesDataArray - Animation keyframes binary data array (each element is a protobuf encoded Message) or empty array to trigger audio-only mode
+     * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
+     *                Use getCurrentConversationId() to get the current conversationId.
      */
-    interrupt(): void;
+    yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): void;
     /**
-     * 清理所有数据和资源
+     * Send animation keyframes (host mode)
+     * Stream animation keyframes data after yieldAudioData()
+     *
+     * ⚠️ **Not recommended**: Prefer using `yieldFramesData()` method, which accepts binary data (protobuf encoded Message) with better performance.
+     * This method is only for scenarios where you already have decoded KeyframeData arrays.
+     *
+     * Public API: accepts decoded keyframes
+     * @param keyframes - Animation keyframes array (KeyframeData[]) or empty array to trigger audio-only mode
+     * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
+     *                Use getCurrentConversationId() to get the current conversationId.
      */
-    clear(): void;
+    yieldKeyframes(keyframes: KeyframeData[], conversationId: string): void;
     /**
-     * 开始流式播放（内部方法，由 NetworkLayer 或 play() 调用）
+     * Pause playback (can be resumed later)
+     * Pause audio playback and stop render loop, but preserve all state (keyframes, audio buffers, etc.)
      */
-    startStreamingPlayback(): Promise<void>;
+    pause(): void;
     /**
-     * 设置渲染回调（由 AvatarView 调用）
+     * Resume playback (from paused state)
+     * Resume audio playback and restart render loop
+     * Animation will continue from paused frame (because animation time base comes from audio, will auto-sync)
      */
-    setRenderCallback(callback: (splatData: Float32Array, frameIndex: number) => void): void;
+    resume(): Promise<void>;
     /**
-     * 设置过渡完成回调（由 AvatarView 调用）
+     * Interrupt current playback
      */
-    setTransitionCompleteCallback(callback: () => void): void;
+    interrupt(): void;
     /**
-     * 过渡完成通知（由 AvatarView 调用）
+     * Clear all data and resources
      */
-    onTransitionComplete(): void;
+    clear(): void;
     /**
-     * 为 AvatarView 提供注册内部事件的接口
-     * @internal
+     * Get point cloud count of the current avatar
+     * @returns Point cloud count, or null if avatar is not loaded
      */
-    setupInternalEventListeners(callbacks: {
-        onKeyframesUpdate?: (keyframes: Flame[]) => void;
-        onStartRendering?: () => void;
-        onStopRendering?: () => void;
-        onInterrupt?: () => void;
-    }): void;
+    getPointCount(): number | null;
     /**
-     * 开始流式播放（内部实现）
+     * Set post-processing configuration
+     * These parameters will be applied in real-time to animation parameters returned by the server
+     * @param config Post-processing configuration, or null to clear
      */
-    private startStreamingPlaybackInternal;
+    setPostProcessingConfig(config: PostProcessingConfig | null): void;
     /**
-     * 播放循环：根据音频时间计算动画帧，通知渲染层渲染
+     * 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)
      */
-    private startPlaybackLoop;
+    setVolume(volume: number): void;
     /**
-     * 停止播放循环
+     * Get current audio playback volume
+     * @returns Current volume value (0.0 - 1.0)
      */
-    private stopPlaybackLoop;
+    getVolume(): number;
     /**
-     * 停止播放
+     * Stop playback
      */
     protected stopPlayback(): void;
     /**
-     * 清理播放器
+     * Clean up players
      */
     protected cleanupPlayers(): void;
     /**
-     * 添加音频块到缓冲区
-     */
-    private addAudioChunkToBuffer;
-    /**
-     * 事件系统
-     */
-    private registerEventListener;
-    /**
-     * 触发事件
+     * Emit event
      */
     protected emit(event: string, data?: any): void;
 }
-//# sourceMappingURL=AvatarController.d.ts.map

package/dist/core/AvatarDownloader.d.ts

@@ -1,100 +1,15 @@
-import { CharacterMeta, PreloadCameraSettings } from '../types/character';
-import { CharacterSettings } from '../types/character-settings';
-interface ProgressInfo {
-    stage: string;
-    filename: string;
-    loaded: number;
-    total: number;
-    progress: number;
-}
-type ProgressCallback = (info: ProgressInfo) => void;
-interface TemplateResources {
-    [key: string]: ArrayBuffer;
-}
-interface FlameResources {
-    flameModel?: {
-        remote?: string;
-    };
-    flameTemplate?: {
-        remote?: string;
-    };
-    teethPb?: {
-        remote?: string;
-    };
-    teethNpz?: {
-        remote?: string;
-    };
-}
-interface CharacterDataResult {
-    shape: ArrayBuffer;
-    pointCloud: ArrayBuffer;
-    idleAnimation?: ArrayBuffer;
-    monoAnimation?: ArrayBuffer;
-    monoAudioUrl?: string;
-}
-export interface PreloadResult {
-    templateResources: TemplateResources;
-    characterData: CharacterDataResult;
-    preloadCameraSettings?: PreloadCameraSettings;
-    characterSettings?: CharacterSettings;
-}
+/**
+ * Avatar Downloader (iOS Compatible)
+ * Downloads character resources from CharacterMeta structure
+ */
 export declare class AvatarDownloader {
     private baseAssetsPath;
-    private characterAssets;
     constructor(baseAssetsPath?: string);
     /**
-     * Load template resources from CharacterMeta flame CDN URLs
-     * Falls back to global CDN config if not provided by API
-     */
-    loadTemplateResources(flameResources?: FlameResources, progressCallback?: ProgressCallback | null): Promise<TemplateResources>;
-    /**
-     * Load global FLAME template resources from CDN
-     * Uses centralized FLAME CDN config (shared across all characters)
-     */
-    private loadGlobalFlameResources;
-    /**
-     * Load camera settings from CharacterMeta (optional)
-     */
-    loadCameraSettings(characterMeta: CharacterMeta): Promise<PreloadCameraSettings | undefined>;
-    /**
-     * Load character data from CharacterMeta (iOS compatible)
-     */
-    loadCharacterData(characterMeta: CharacterMeta, options?: {
-        loadMonologue?: boolean;
-        progressCallback?: ProgressCallback | null;
-    }): Promise<CharacterDataResult>;
-    /**
-     * Preload all resources (template + character data + camera info + settings)
-     */
-    preloadResources(characterMeta: CharacterMeta, options?: {
-        loadMonologue?: boolean;
-        progressCallback?: ProgressCallback | null;
-    }): Promise<PreloadResult>;
-    /**
-     * Get loaded character asset by key
-     */
-    getCharacterAsset(key: string): ArrayBuffer | undefined;
-    /**
-     * Clear cached assets
-     */
-    clear(): void;
-    /**
-     * Get Main App API Client (enjoi.spatialwalk.top)
-     * Used for: character list, auth, customization, etc.
-     */
-    private getMainAppClient;
-    /**
-     * Get SPAvatarKit SDK API Client (api.spatialwalk.top)
+     * Get AvatarKit SDK API Client (api.open.spatialwalk.top for cn, api.intl.spatialwalk.cloud for intl)
      * Used for: character details and resource URLs (public endpoints, no auth required)
+     * Note: This endpoint does not require authentication, so we don't add X-App-Id or Authorization headers
+     * to avoid CORS preflight requests for simple GET requests
      */
     private getSdkApiClient;
-    /**
-     * Get single character by ID from SPAvatarKit SDK API (v2, iOS compatible)
-     * Domain: api.spatialwalk.top
-     * Auth: Public endpoint, no authentication required
-     * Returns CharacterMeta with nested resource structure
-     */
-    getCharacterById(characterId: string): Promise<CharacterMeta>;
 }
-export {};
-//# sourceMappingURL=AvatarDownloader.d.ts.map

package/dist/core/AvatarManager.d.ts

@@ -3,24 +3,34 @@ import { Avatar } from './Avatar';
 export declare class AvatarManager {
     private static _instance;
     private avatarDownloader;
-    private _templateInitialized;
+    private avatarCache;
+    private loadingPromises;
+    private downloadQueue;
+    private isDownloading;
     /**
-     * 通过全局单例来访问
+     * Access via global singleton
      */
     static get shared(): AvatarManager;
     /**
-     * 加载数字人
-     * @param id 数字人 ID
-     * @param onProgress 进度回调
-     * @param options 加载选项
+     * Load avatar
+     * @param id Avatar ID
+     * @param onProgress Progress callback
      * @returns Promise<Avatar>
      */
-    load(id: string, onProgress?: (progress: LoadProgressInfo) => void, options?: {
-        enableMonologue?: boolean;
-    }): Promise<Avatar>;
+    load(id: string, onProgress?: (progress: LoadProgressInfo) => void): Promise<Avatar>;
     /**
-     * 清理资源加载器缓存
+     * Get cached avatar
+     * @param id Avatar ID
+     * @returns Avatar instance, or undefined if not in cache
      */
-    clearCache(): void;
+    retrieve(id: string): Avatar | undefined;
+    /**
+     * Clear cached avatar for specified ID
+     * @param id Avatar ID
+     */
+    clear(id: string): void;
+    /**
+     * Clear all avatar cache and resource loader cache
+     */
+    clearAll(): void;
 }
-//# sourceMappingURL=AvatarManager.d.ts.map

package/dist/core/AvatarSDK.d.ts

@@ -0,0 +1,35 @@
+import { Configuration } from '../types';
+export declare class AvatarSDK {
+    private static _isInitialized;
+    private static _configuration;
+    private static readonly _version;
+    private static _avatarCore;
+    private static _dynamicSdkConfig;
+    /**
+     * Initialize SDK
+     * @param appId Application ID to be included in both HTTP Headers and WebSocket Headers
+     * @param configuration Configuration parameters
+     */
+    static initialize(appId: string, configuration: Configuration): Promise<void>;
+    /**
+     * Set sessionToken
+     * Developer Client -> Developer Server -> AvatarKit Server -> return sessionToken (max 1 hour validity)
+     * Include in WebSocket Headers for avatar WebSocket service authentication
+     */
+    static setSessionToken(token: string): void;
+    /**
+     * Set userId
+     * Optional interface for developers, SDK includes this in telemetry logs
+     */
+    static setUserId(userId: string): void;
+    static get isInitialized(): boolean;
+    static get appId(): string | null;
+    static get configuration(): Configuration | null;
+    static get sessionToken(): string | null;
+    static get userId(): string | null;
+    static get version(): string;
+    /**
+     * Cleanup resources
+     */
+    static cleanup(): void;
+}