@spatialwalk/avatarkit 1.0.0-beta.68 → 1.0.0-beta.69

package/dist/audio/AnimationPlayer.d.ts

@@ -7,23 +7,69 @@ export declare class AnimationPlayer {
     private onEndedCallback?;
     private static audioUnlocked;
     private useStreaming;
+    /**
+     * 解锁音频上下文（Safari 自动播放策略）
+     * 必须在用户交互事件（如 click）中调用
+     */
     static unlockAudioContext(): Promise<void>;
+    /**
+     * Initialize with HTMLAudioElement (traditional way)
+     */
     initialize(audioUrl: string, onEnded?: () => void): Promise<void>;
+    /**
+     * Initialize with StreamingAudioPlayer (streaming way)
+     * @deprecated 使用 prepareStreamingPlayer() 代替
+     */
     initializeStreaming(streamingPlayer: StreamingAudioPlayer, onEnded?: () => void): Promise<void>;
+    /**
+     * 检查流式播放器是否已准备好
+     */
     isStreamingReady(): boolean;
+    /**
+     * 获取流式播放器实例
+     */
     getStreamingPlayer(): StreamingAudioPlayer | null;
+    /**
+     * 创建并初始化流式播放器
+     * 在服务连接建立时调用
+     */
     createAndInitializeStreamingPlayer(): Promise<void>;
+    /**
+     * 准备流式播放器（如果未创建则创建并初始化）
+     * 停止之前的播放并更新结束回调
+     */
     prepareStreamingPlayer(onEnded?: () => void): Promise<void>;
     private setupEventListeners;
     play(): Promise<void>;
     stop(): void;
     isPlaying(): boolean;
     getCurrentFrameIndex(): number;
+    /**
+     * Get current playback time
+     */
     getCurrentTime(): number;
+    /**
+     * 添加音频块（仅用于流式播放）
+     */
     addAudioChunk(audio: Uint8Array, isLast?: boolean): void;
+    /**
+     * 暂停播放
+     */
     pause(): void;
+    /**
+     * 继续播放
+     */
     resume(): Promise<void>;
+    /**
+     * 设置音量 (0.0 - 1.0)
+     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
+     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+     */
     setVolume(volume: number): void;
+    /**
+     * 获取当前音量
+     * @returns 当前音量值 (0.0 - 1.0)
+     */
     getVolume(): number;
     dispose(): void;
 }

package/dist/audio/StreamingAudioPlayer.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Streaming Audio Player
+ * Implements real-time audio playback using Web Audio API
+ * Supports dynamic PCM chunk addition without Workers
+ */
 export interface StreamingAudioPlayerOptions {
     sampleRate?: number;
     channelCount?: number;
@@ -30,33 +35,121 @@ export declare class StreamingAudioPlayer {
     private stateChangeHandler?;
     private isResuming;
     constructor(options?: StreamingAudioPlayerOptions);
+    /**
+     * Initialize audio context (create and ensure it's ready)
+     */
     initialize(): Promise<void>;
+    /**
+     * 确保 AudioContext 正在运行（如果被暂停则自动恢复）
+     * 只在正在播放且未暂停时自动恢复，避免干扰正常的暂停/恢复逻辑
+     *
+     * 优化：
+     * - 快速路径：如果已经是 running 状态，直接返回
+     * - 避免并发恢复：使用 isResuming 标志防止重复恢复请求
+     * - 处理 closed 状态：如果 AudioContext 已关闭，无法恢复
+     */
     private ensureAudioContextRunning;
+    /**
+     * Add audio chunk (16-bit PCM)
+     */
     addChunk(pcmData: Uint8Array, isLast?: boolean): void;
+    /**
+     * Start new session (stop current and start fresh)
+     */
     startNewSession(audioChunks: Array<{
         data: Uint8Array;
         isLast: boolean;
     }>): Promise<void>;
+    /**
+     * Start playback
+     */
     private startPlayback;
+    /**
+     * Schedule all pending chunks
+     */
     private scheduleAllChunks;
+    /**
+     * Schedule next audio chunk
+     */
     private scheduleNextChunk;
+    /**
+     * Convert PCM data to AudioBuffer
+     * Input: 16-bit PCM (int16), Output: AudioBuffer (float32 [-1, 1])
+     */
     private pcmToAudioBuffer;
+    /**
+     * Get current playback time (seconds)
+     * 返回实际播放的音频总时长
+     */
     getCurrentTime(): number;
+    /**
+     * Get total duration of buffered audio (seconds)
+     * 计算所有已缓冲 chunk 的总时长
+     */
     getBufferedDuration(): number;
+    /**
+     * Get current AudioContext time
+     * @returns Current AudioContext time in seconds, or 0 if AudioContext is not initialized
+     */
     getAudioContextTime(): number;
+    /**
+     * Pause playback
+     */
     pause(): void;
+    /**
+     * Resume playback
+     */
     resume(): Promise<void>;
+    /**
+     * Stop playback
+     */
     stop(): void;
+    /**
+     * Enable or disable auto-start (for delayed start scenarios)
+     */
     setAutoStart(enabled: boolean): void;
+    /**
+     * Start playback manually (for delayed start scenarios)
+     * This allows starting playback after transition animation completes
+     */
     play(): void;
+    /**
+     * Mark playback as ended
+     */
     markEnded(): void;
+    /**
+     * Set ended callback
+     */
     onEnded(callback: () => void): void;
+    /**
+     * Check if playing
+     */
     isPlayingNow(): boolean;
+    /**
+     * Dispose and cleanup
+     */
     dispose(): void;
+    /**
+     * Flush buffered audio
+     * - hard: stops all playing sources and clears all chunks
+     * - soft (default): clears UNSCHEDULED chunks only
+     */
     flush(options?: {
         hard?: boolean;
     }): void;
+    /**
+     * 设置音量 (0.0 - 1.0)
+     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
+     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+     */
     setVolume(volume: number): void;
+    /**
+     * 获取当前音量
+     * @returns 当前音量值 (0.0 - 1.0)
+     */
     getVolume(): number;
+    /**
+     * Debug logging
+     */
     private log;
 }

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

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

package/dist/config/constants.d.ts

@@ -11,5 +11,11 @@ export declare function getPostHogConfig(_environment: Environment): {
     disableCompression: boolean;
 };
 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,7 +1,15 @@
 import { Environment } from '../types';
-
+/**
+ * 默认 SDK 配置（当远程配置接口失败时使用）
+ */
 export declare const DEFAULT_SDK_CONFIG: Partial<Record<Environment, string>>;
-
+/**
+ * 从远程配置接口获取 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,6 +4,16 @@ 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;
 }

package/dist/core/AvatarController.d.ts

@@ -1,7 +1,7 @@
 import { Flame } from '../generated/driveningress/v1/driveningress';
 import { Avatar } from './Avatar';
 import { AnimationPlayer } from '../audio/AnimationPlayer';
-import { AvatarState, ConnectionState, DrivingServiceMode, ConversationState, PostProcessingConfig } from '../types';
+import { AvatarState, ConnectionState, DrivingServiceMode, ConversationState, PostProcessingConfig, KeyframeData } from '../types';
 export declare class AvatarController {
     private networkLayer?;
     private readonly playbackMode;
@@ -43,40 +43,202 @@ 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;
+    /**
+     * 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()
+     * })
+     */
     initializeAudioContext(): Promise<void>;
+    /**
+     * Check if audio context is initialized
+     * @throws AvatarError if audio context is not initialized
+     */
     private checkAudioContextInitialized;
+    /**
+     * 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()
+     *
+     * 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.
+     */
     yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): void;
-    yieldKeyframes(keyframes: Flame[], 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.
+     */
+    yieldKeyframes(keyframes: KeyframeData[], 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;
+    /**
+     * Get point cloud count of the current avatar
+     * @returns Point cloud count, or null if avatar is not loaded
+     */
     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
+     */
     setPostProcessingConfig(config: PostProcessingConfig | null): void;
+    /**
+     * 设置完整的 eye tracking 配置到 C++
+     * @private
+     */
     private setEyeTrackingConfig;
+    /**
+     * 重新渲染当前帧（用于暂停状态下更新后处理参数）
+     * @private
+     */
     private rerenderCurrentFrame;
+    /**
+     * Set audio playback volume
+     * Note: This only controls the avatar audio player volume, not the system volume
+     * @param volume Volume value, range from 0.0 to 1.0 (0.0 = mute, 1.0 = max volume)
+     */
     setVolume(volume: number): void;
+    /**
+     * Get current audio playback volume
+     * @returns Current volume value (0.0 - 1.0)
+     */
     getVolume(): number;
+    /**
+     * Start streaming playback (internal implementation)
+     */
     private startStreamingPlaybackInternal;
     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
+     * Note: animationPlayer should already be initialized before calling this method
+     */
     private addAudioChunkToBuffer;
+    /**
+     * Event system
+     */
     private registerEventListener;
+    /**
+     * Emit event
+     */
     protected emit(event: string, data?: any): void;
+    /**
+     * Apply post-processing parameters to animation parameters
+     * @private
+     */
     private applyPostProcessingToParams;
+    /**
+     * 上报 driving_service_latency 事件（Host 模式）
+     * 每轮会话只上报一次（在收到首帧时）
+     * @private
+     */
     private reportDrivingServiceLatency;
 }

package/dist/core/AvatarDownloader.d.ts

@@ -1,5 +1,15 @@
+/**
+ * Avatar Downloader (iOS Compatible)
+ * Downloads character resources from CharacterMeta structure
+ */
 export declare class AvatarDownloader {
     private baseAssetsPath;
     constructor(baseAssetsPath?: string);
+    /**
+     * 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;
 }

package/dist/core/AvatarManager.d.ts

@@ -7,12 +7,38 @@ export declare class AvatarManager {
     private loadingPromises;
     private downloadQueue;
     private isDownloading;
+    /**
+     * Access via global singleton
+     */
     static get shared(): AvatarManager;
+    /**
+     * Load avatar
+     * @param id Avatar ID
+     * @param onProgress Progress callback
+     * @returns Promise<Avatar>
+     */
     load(id: string, onProgress?: (progress: LoadProgressInfo) => void): Promise<Avatar>;
+    /**
+     * 处理下载队列（确保串行执行）
+     */
     private processDownloadQueue;
+    /**
+     * 执行实际的加载逻辑（私有方法）
+     */
     private doLoad;
+    /**
+     * Get cached avatar
+     * @param id Avatar ID
+     * @returns Avatar instance, or undefined if not in cache
+     */
     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;
-    clearCache(): void;
 }

package/dist/core/AvatarSDK.d.ts

@@ -5,10 +5,31 @@ export declare class AvatarSDK {
     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>;
+    /**
+     * 初始化WASM模块（跟随整个SDK生命周期）
+     */
     private static initializeWASMModule;
+    /**
+     * 初始化模板资源（在SDK初始化时加载）
+     * 从全局 CDN 加载模板资源，失败时直接抛出错误，阻止SDK初始化
+     */
     private static initializeTemplateResources;
+    /**
+     * 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;
@@ -16,6 +37,12 @@ export declare class AvatarSDK {
     static get sessionToken(): string | null;
     static get userId(): string | null;
     static get version(): string;
+    /**
+     * Cleanup resources
+     */
     static cleanup(): void;
+    /**
+     * 从远程配置接口获取SDK配置（已简化，逻辑移到 config/sdk-config-loader.ts）
+     */
     private static _fetchSdkConfig;
 }