@spatialwalk/avatarkit 1.0.0-beta.27 → 1.0.0-beta.29

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

@@ -2,11 +2,7 @@ export declare const APP_CONFIG: {
     testEnv: boolean;
     readonly debug: boolean;
     rendering: {
-        /**
-         * 排序模式
-         * - 'balance': 性能优先，首帧排序后复用（默认）
-         * - 'quality': 质量优先，每帧重新排序
-         */
+
         sortMode: "balance" | "quality";
     };
     camera: {

package/dist/config/constants.d.ts

@@ -1,8 +1,6 @@
 import { Environment } from '../types';
 export declare const CLS_TRACK_EVENTS: boolean;
-/**
- * 获取 CLS 配置（需要传入环境）
- */
+
 export declare function getCLSConfig(environment: Environment): {
     endpoint: string;
     topicId: string;
@@ -18,11 +16,5 @@ export declare const CLS_CONFIG: {
     token: string;
 };
 export declare const ENV_TEST: boolean;
-/**
- * Comprehensive debug mode check
- * Returns true if:
- * - VITE_ENV_TEST is 'true', OR
- * - Running in DEV mode, OR
- * - URL has debug=1 parameter
- */
+
 export declare function isDebugMode(): boolean;

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

@@ -1,11 +1,5 @@
 import { Environment } from '../types';
-/**
- * 从远程配置接口获取 SDK 配置
- * @param version SDK 版本号
- * @returns 解析后的配置映射
- */
+
 export declare function fetchSdkConfig(version: string): Promise<Partial<Record<Environment, string>>>;
-/**
- * 清除配置缓存（用于测试或重新加载）
- */
+
 export declare function clearSdkConfigCache(): void;

package/dist/core/Avatar.d.ts

@@ -4,11 +4,5 @@ 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);
 }

package/dist/core/AvatarController.d.ts

@@ -34,143 +34,32 @@ export declare class AvatarController {
     constructor(avatar: Avatar, options?: {
         playbackMode?: DrivingServiceMode;
     });
-    /**
-     * Get current conversation ID
-     * Returns the current conversation ID for the active audio session
-     * @returns Current conversation ID, or null if no active session
-     */
     getCurrentConversationId(): string | 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): string | null;
-    /**
-     * Close service (SDK mode only)
-     */
     close(): void;
-    /**
-     * Send audio data (host mode)
-     * Stream additional audio data after playback()
-     * @returns conversationId - Conversation ID for this audio session
-     */
     yieldAudioData(data: Uint8Array, isLast?: boolean): string | null;
-    /**
-     * Send animation keyframes (host mode or SDK mode)
-     * Stream additional animation data after playback()
-     * @param keyframes - Animation keyframes to send
-     * @param conversationId - Conversation ID (required). If conversationId doesn't match current conversationId, keyframes will be discarded.
-     *                Use getCurrentConversationId() to get the current conversationId.
-     */
     yieldFramesData(keyframes: Flame[], conversationId: string): void;
-    /**
-     * Pause playback (can be resumed later)
-     * Pause audio playback and stop render loop, but preserve all state (keyframes, audio buffers, etc.)
-     */
     pause(): void;
-    /**
-     * 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)
-     */
     resume(): Promise<void>;
-    /**
-     * Interrupt current playback
-     */
     interrupt(): void;
-    /**
-     * Clear all data and resources
-     */
     clear(): void;
-    /**
-     * Generate new conversation ID and log conversation started event
-     * @private
-     */
     private generateAndLogNewConversationId;
-    /**
-     * Clear playback data (keyframes, audio chunks, and playback state)
-     * @private
-     */
     private clearPlaybackData;
-    /**
-     * Reset conversation ID state (for both network and external modes)
-     * @private
-     */
     private resetConversationIdState;
-    /**
-     * Get effective conversation ID (handles both SDK and host modes)
-     * @private
-     */
     private getEffectiveConversationId;
-    /**
-     * 设置音频播放音量
-     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
-     */
     setVolume(volume: number): void;
-    /**
-     * 获取当前音频播放音量
-     * @returns 当前音量值 (0.0 - 1.0)
-     */
     getVolume(): number;
-    /**
-     * Start streaming playback (internal implementation)
-     */
     private startStreamingPlaybackInternal;
-    /**
-     * Playback loop: Calculate animation frame based on audio time, notify render layer to render
-     */
     private startPlaybackLoop;
-    /**
-     * Stop playback loop
-     */
     private stopPlaybackLoop;
-    /**
-     * 启用音频独立播放模式（当服务器错误或超时时调用）
-     * 此模式下，音频会独立播放，不依赖动画数据
-     * 一旦启用，本次会话后续的动画数据将被忽略
-     * @private
-     */
     private enableAudioOnlyMode;
-    /**
-     * 音频独立播放（完全独立的逻辑，不影响正常播放流程）
-     * @private
-     */
     private startAudioOnlyPlayback;
-    /**
-     * 音频监控循环（仅用于音频独立模式）
-     * 只检测音频是否结束，不进行动画渲染
-     * @private
-     */
     private startAudioMonitoringLoop;
-    /**
-     * Stop playback
-     */
     protected stopPlayback(): void;
-    /**
-     * Clean up players
-     */
     protected cleanupPlayers(): void;
-    /**
-     * Add audio chunk to buffer
-     */
     private addAudioChunkToBuffer;
-    /**
-     * Event system
-     */
     private registerEventListener;
-    /**
-     * Emit event
-     */
     protected emit(event: string, data?: any): void;
-    /**
-     * 上报 driving_latency 事件（Host 模式）
-     * @private
-     */
     private reportDrivingLatency;
 }

package/dist/core/AvatarDownloader.d.ts

@@ -1,80 +1,5 @@
-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;
-}
-export interface PreloadResult {
-    templateResources: TemplateResources;
-    characterData: CharacterDataResult;
-    preloadCameraSettings?: PreloadCameraSettings;
-    characterSettings?: CharacterSettings;
-}
 export declare class AvatarDownloader {
     private baseAssetsPath;
     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 camera settings from CharacterMeta (optional)
-     */
-    loadCameraSettings(characterMeta: CharacterMeta): Promise<PreloadCameraSettings | undefined>;
-    /**
-     * Load character data from CharacterMeta (iOS compatible)
-     */
-    loadCharacterData(characterMeta: CharacterMeta, options?: {
-        progressCallback?: ProgressCallback | null;
-    }): Promise<CharacterDataResult>;
-    /**
-     * Preload all resources (template + character data + camera info + settings)
-     */
-    preloadResources(characterMeta: CharacterMeta, options?: {
-        progressCallback?: ProgressCallback | null;
-    }): Promise<PreloadResult>;
-    /**
-     * Clear cached assets (no-op, kept for API compatibility)
-     */
-    clear(): void;
-    /**
-     * Get SPAvatarKit SDK API Client (api.open.spatialwalk.top for cn, api.open.spatialwalk.cloud for intl)
-     * Used for: character details and resource URLs (public endpoints, no auth required)
-     */
     private getSdkApiClient;
-    /**
-     * Get single character by ID from SPAvatarKit SDK API (v2, iOS compatible)
-     * Domain: api.open.spatialwalk.top (cn) / api.open.spatialwalk.cloud (intl)
-     * Auth: Public endpoint, no authentication required
-     * Returns CharacterMeta with nested resource structure
-     */
-    getCharacterById(characterId: string): Promise<CharacterMeta>;
 }
-export {};

package/dist/core/AvatarManager.d.ts

@@ -3,20 +3,13 @@ import { Avatar } from './Avatar';
 export declare class AvatarManager {
     private static _instance;
     private avatarDownloader;
-    /**
-     * 通过全局单例来访问
-     */
+    private avatarCache;
+    private loadingPromises;
     static get shared(): AvatarManager;
-    /**
-     * 加载数字人
-     * @param id 数字人 ID
-     * @param onProgress 进度回调
-     * @param options 加载选项
-     * @returns Promise<Avatar>
-     */
     load(id: string, onProgress?: (progress: LoadProgressInfo) => void): Promise<Avatar>;
-    /**
-     * 清理资源加载器缓存
-     */
+    private doLoad;
+    retrieve(id: string): Avatar | undefined;
+    clear(id: string): void;
+    clearAll(): void;
     clearCache(): void;
 }

package/dist/core/AvatarSDK.d.ts

@@ -0,0 +1,21 @@
+import { Configuration } from '../types';
+export declare class AvatarSDK {
+    private static _isInitialized;
+    private static _configuration;
+    private static readonly _version;
+    private static _avatarCore;
+    private static _dynamicSdkConfig;
+    static initialize(appId: string, configuration: Configuration): Promise<void>;
+    private static initializeWASMModule;
+    private static initializeTemplateResources;
+    static setSessionToken(token: string): void;
+    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;
+    static cleanup(): void;
+    private static _fetchSdkConfig;
+}

package/dist/core/AvatarView.d.ts

@@ -26,138 +26,39 @@ export declare class AvatarView {
     private idleCurrentFrameIndex;
     private characterHandle;
     private characterId;
-    /**
-     * 对齐两端 Flame 维度：标量统一长度，expression 取最大长度并零填充
-     */
+    private _isOpaque;
     private alignFlamePair;
-    /**
-     * 生成并对齐过渡帧，确保首尾帧与起止帧完全一致
-     */
     private generateAndAlignTransitionFrames;
-    /**
-     * 获取缓存的 Idle 首帧，如果未缓存则获取并缓存
-     */
     private getCachedIdleFirstFrame;
-    /**
-     * 构造函数
-     * 创建统一的 AvatarController，内部根据配置自动组合网络层
-     */
-    /**
-     * 构造函数
-     * 创建统一的 AvatarController，内部根据配置自动组合网络层
-     * @param avatar - Avatar 实例
-     * @param container - Canvas 容器元素（必选）
-     */
     constructor(avatar: Avatar, container: HTMLElement);
-    /**
-     * 获取控制器（公共接口）
-     */
     get controller(): AvatarController;
-    /**
-     * 创建canvas元素
-     */
     private createCanvas;
-    /**
-     * 初始化视图系统
-     */
     private initializeView;
-    /**
-     * 初始化渲染系统
-     */
     private initializeRenderSystem;
-    /**
-     * 获取默认相机配置
-     */
     private getDefaultCameraConfig;
-    /**
-     * 根据资源解析最终的相机配置，优先使用角色设置，其次 camera.json
-     */
     private resolveCameraConfig;
-    /**
-     * 从角色设置中推导相机配置
-     */
     private deriveCameraConfigFromSettings;
-    /**
-     * 渲染第一帧
-     */
     private renderFirstFrame;
-    /**
-     * 更新 FPS 统计（在 requestAnimationFrame 回调中调用）
-     */
     private updateFPS;
-    /**
-     * 初始化 FPS 计算
-     */
     private initFPS;
-    /**
-     * 开始idle动画循环
-     */
     private startIdleAnimationLoop;
-    /**
-     * 开始实时对话动画循环
-     */
     private startRealtimeAnimationLoop;
-    /**
-     * 停止idle动画循环
-     */
     private stopIdleAnimationLoop;
-    /**
-     * 停止实时对话动画循环
-     */
     private stopRealtimeAnimationLoop;
-    /**
-     * 停止所有动画循环
-     */
     private stopAllAnimationLoops;
-    /**
-     * 渲染实时帧（由播放层回调调用）
-     */
     private renderRealtimeFrame;
-    /**
-     * 状态转换方法
-     * 统一管理状态转换，确保状态一致性
-     */
     private setState;
-    /**
-     * 检查是否在实时播放状态（Speaking 或过渡到 Speaking）
-     */
     private get isRealtimePlaying();
-    /**
-     * 检查是否在过渡中
-     */
     private get isTransitioning();
-    /**
-     * 检查过渡结束后是否回到 Idle
-     */
     private get endToIdleAfterTransition();
-    /**
-     * 处理打断
-     * 打断时应该生成过渡动画，而不是直接跳回 Idle
-     */
     private handleInterrupt;
-    /**
-     * 设置 AvatarController 事件监听器
-     */
     private setupControllerEventListeners;
-    /**
-     * 准备实时渲染（生成 Idle -> Speaking 过渡）
-     */
     private prepareRealtimeRendering;
-    /**
-     * 开始实时渲染循环
-     */
     private startRealtimeRendering;
-    /**
-     * 停止实时对话渲染
-     */
     private stopRealtimeRendering;
-    /**
-     * 清理视图资源
-     * 关闭 avatarController 并清理所有相关资源
-     */
     dispose(): void;
-    /**
-     * 处理尺寸变化：通知渲染系统更新视口与投影
-     */
     private handleResize;
+    get isOpaque(): boolean;
+    set isOpaque(value: boolean);
+    setBackgroundImage(image: HTMLImageElement | string | null): void;
 }

package/dist/core/NetworkLayer.d.ts

@@ -1,7 +1 @@
-/**
- * NetworkLayer - Network communication layer
- * Responsible for WebSocket connections, protocol handling, and data retrieval
- * Automatically calls AvatarController (playback layer) interfaces after obtaining data
- * @internal Not part of public API
- */
 export {};

package/dist/generated/driveningress/v1/driveningress.d.ts

@@ -9,29 +9,19 @@ export declare enum MessageType {
 }
 export declare function messageTypeFromJSON(object: any): MessageType;
 export declare function messageTypeToJSON(object: MessageType): string;
-/**
- * 兼容流式传输，只要 req_id 相同，客户端可以将音频分段发若干个 ClientAudioInputData
- * 新 req_id 出现后，老 req_id 的请求将被忽略
- */
+
 export interface ClientAudioInputData {
     reqId: string;
     audio: Uint8Array;
     end: boolean;
 }
 export interface Flame {
-    /** 平移 */
     translation: number[];
-    /** 旋转 */
     rotation: number[];
-    /** 脖子 */
     neckPose: number[];
-    /** 下巴 */
     jawPose: number[];
-    /** 眼睛 */
     eyePose: number[];
-    /** 眼皮 */
     eyeLid: number[];
-    /** 表情参数 */
     expression: number[];
 }
 export interface FlameAnimation {

package/dist/generated/driveningress/v2/driveningress.d.ts

@@ -5,9 +5,7 @@ export interface GetCharacterInfoRequest {
     characterId: string;
 }
 export interface CharacterAsset {
-    /** 资产ID，例如 "v1/xxx" */
     characterId: string;
-    /** 资产版本，例如 "1.0.0" */
     version: string;
     createdAt?: Timestamp | undefined;
     updatedAt?: Timestamp | undefined;

package/dist/generated/google/protobuf/struct.d.ts

@@ -1,30 +1,15 @@
 import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
 export declare const protobufPackage = "google.protobuf";
-/**
- * `NullValue` is a singleton enumeration to represent the null value for the
- * `Value` type union.
- *
- * The JSON representation for `NullValue` is JSON `null`.
- */
+
 export declare enum NullValue {
-    /** NULL_VALUE - Null value. */
+
     NULL_VALUE = 0,
     UNRECOGNIZED = -1
 }
 export declare function nullValueFromJSON(object: any): NullValue;
 export declare function nullValueToJSON(object: NullValue): string;
-/**
- * `Struct` represents a structured data value, consisting of fields
- * which map to dynamically typed values. In some languages, `Struct`
- * might be supported by a native representation. For example, in
- * scripting languages like JS a struct is represented as an
- * object. The details of that representation are described together
- * with the proto support for the language.
- *
- * The JSON representation for `Struct` is JSON object.
- */
+
 export interface Struct {
-    /** Unordered map of dynamically typed values. */
     fields: {
         [key: string]: any | undefined;
     };
@@ -33,37 +18,19 @@ export interface Struct_FieldsEntry {
     key: string;
     value?: any | undefined;
 }
-/**
- * `Value` represents a dynamically typed value which can be either
- * null, a number, a string, a boolean, a recursive struct value, or a
- * list of values. A producer of value is expected to set one of these
- * variants. Absence of any variant indicates an error.
- *
- * The JSON representation for `Value` is JSON value.
- */
+
 export interface Value {
-    /** Represents a null value. */
     nullValue?: NullValue | undefined;
-    /** Represents a double value. */
     numberValue?: number | undefined;
-    /** Represents a string value. */
     stringValue?: string | undefined;
-    /** Represents a boolean value. */
     boolValue?: boolean | undefined;
-    /** Represents a structured value. */
     structValue?: {
         [key: string]: any;
     } | undefined;
-    /** Represents a repeated `Value`. */
     listValue?: Array<any> | undefined;
 }
-/**
- * `ListValue` is a wrapper around a repeated field of values.
- *
- * The JSON representation for `ListValue` is JSON array.
- */
+
 export interface ListValue {
-    /** Repeated field of dynamically typed values. */
     values: any[];
 }
 export declare const Struct: MessageFns<Struct> & StructWrapperFns;