@spatius/avatarkit 0.5.0

package/dist/core/Avatar.d.ts

@@ -0,0 +1,13 @@
+import { CharacterMeta } from '../types';
+export declare class Avatar {
+    readonly id: string;
+    private characterMeta;
+    private resources;
+    /** Local-only field: tracks whether cached model is "standard" or "compressed". */
+    _cachedModelType: string;
+    /**
+     * Get character metadata
+     * @returns Character metadata, including all configuration information (version, resource URLs, camera config, etc.)
+     */
+    getCharacterMeta(): CharacterMeta;
+}

package/dist/core/AvatarController.d.ts

@@ -0,0 +1,140 @@
+import { Avatar } from './Avatar';
+import { ConnectionState, AvatarError, DrivingServiceMode, ConversationState, PostProcessingConfig } from '../types';
+import { FrameRateInfo } from '../performance/FrameRateMonitor';
+export declare class AvatarController {
+    private networkLayer?;
+    private readonly playbackMode;
+    private isStartingPlayback;
+    private currentConversationId;
+    private reqEnd;
+    onConnectionState: ((state: ConnectionState) => void) | null;
+    onConversationState: ((state: ConversationState) => void) | null;
+    onError: ((error: AvatarError) => void) | null;
+    private eventListeners;
+    private readonly frameRateMonitor;
+    /** Frame rate monitoring callback. Fires with aggregated metrics from a 2-second sliding window. */
+    get onFrameRateInfo(): ((info: FrameRateInfo) => void) | null;
+    set onFrameRateInfo(value: ((info: FrameRateInfo) => void) | null);
+    /** Whether frame rate monitoring is enabled. Default is false (zero overhead when disabled). */
+    get frameRateMonitorEnabled(): boolean;
+    set frameRateMonitorEnabled(value: boolean);
+    private renderCallback?;
+    private characterHandle;
+    private characterId;
+    private postProcessingConfig;
+    private playbackLoopId;
+    private playbackLoopGeneration;
+    private lastRenderedFrameIndex;
+    private keyframesOffset;
+    private readonly MAX_KEYFRAMES;
+    private readonly KEYFRAMES_CLEANUP_THRESHOLD;
+    private lastSyncLogTime;
+    private lastOutOfBoundsState;
+    private isFallbackMode;
+    private frameStarvationEvents;
+    private isFrameStarved;
+    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?: DrivingServiceMode;
+    });
+    private handleVisibilityChange;
+    private shouldReportPlaybackStats;
+    private _getDeviceScoreProps;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * @returns `true` if the server has sent all animation data for this conversation (end signal received), `false` otherwise.
+     */
+    yieldFramesData(keyframesDataArray: (Uint8Array | ArrayBuffer)[], conversationId: string): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/core/AvatarManager.d.ts

@@ -0,0 +1,46 @@
+import { LoadProgressInfo } from '../types';
+import { Avatar } from './Avatar';
+export declare class AvatarManager {
+    private static _instance;
+    private avatarDownloader;
+    private avatarCache;
+    /** 下载队列：FIFO 顺序 */
+    private downloadQueue;
+    /** 当前正在执行的任务 */
+    private currentTask;
+    /** 任务索引：快速查找 id 对应的任务 */
+    private taskIndex;
+    /**
+     * Access via global singleton
+     */
+    static get shared(): AvatarManager;
+    /**
+     * Load avatar
+     * @param id Avatar ID
+     * @param onProgress Progress callback
+     * @param useCompressedModel Use compressed model resource (~30% of original size, with minor quality degradation). Defaults to false.
+     * @returns Promise<Avatar>
+     */
+    load(id: string, onProgress?: (progress: LoadProgressInfo) => void, useCompressedModel?: boolean): Promise<Avatar>;
+    /**
+     * Cancel a pending or running download task
+     * @param id Avatar ID to cancel
+     * @returns true if task was found and cancelled
+     */
+    cancelLoad(id: string): boolean;
+    /**
+     * 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 cancel all tasks
+     */
+    clearAll(): void;
+}

package/dist/core/AvatarSDK.d.ts

@@ -0,0 +1,57 @@
+import { Configuration } from '../types';
+export declare class AvatarSDK {
+    private static _initializationState;
+    private static _initializingPromise;
+    private static _configuration;
+    private static readonly _version;
+    private static _avatarCore;
+    private static _cachedDeviceScore;
+    private static _rendererBackend;
+    /**
+     * 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>;
+    private static _initializeInternal;
+    /**
+     * 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;
+    /**
+     * Device performance score (CPU + GPU).
+     * CPU: matrix multiply throughput in Web Worker (warmup 1s + measure 1s).
+     * GPU: WebGPU compute shader throughput (warmup 1s + measure 1s).
+     * Returns 0 for GPU if WebGPU is not available.
+     */
+    static deviceScore(): Promise<{
+        cpuScore: number;
+        gpuScore: number;
+    }>;
+    private static readonly CPU_SCORE_THRESHOLD;
+    private static readonly GPU_SCORE_THRESHOLD;
+    /**
+     * Check if the current device can run the avatar.
+     * Runs a ~2s benchmark, reports device info and scores to PostHog.
+     * Currently always returns true — thresholds will be calibrated from production data.
+     */
+    static isDeviceSupported(): Promise<boolean>;
+    private static _getGPURenderer;
+}

package/dist/core/AvatarView.d.ts

@@ -0,0 +1,170 @@
+import { CameraConfig } from '../types';
+import { Avatar } from './Avatar';
+import { AvatarController } from './AvatarController';
+export declare class AvatarView {
+    private readonly avatarController;
+    private readonly avatar;
+    onFirstRendering?: () => void;
+    private canvas;
+    private renderSystem;
+    private isInitialized;
+    private cameraConfig;
+    private renderingState;
+    private currentKeyframes;
+    private lastRenderedFrameIndex;
+    private lastRealtimeProtoFrame;
+    private idleAnimationLoopId;
+    private realtimeAnimationLoopId;
+    private resizeObserver;
+    private onWindowResize;
+    private frameCount;
+    private lastFpsUpdate;
+    private currentFPS;
+    private transitionKeyframes;
+    private transitionStartTime;
+    private readonly startTransitionDurationMs;
+    private readonly endTransitionDurationMs;
+    private cachedIdleFirstFrame;
+    private idleCurrentFrameIndex;
+    private currentPlayingFrame;
+    private characterHandle;
+    private characterId;
+    private isPureRenderingMode;
+    private _renderingEnabled;
+    private avatarActiveTimer;
+    private readonly AVATAR_ACTIVE_INTERVAL;
+    /**
+     * Constructor
+     * Creates a unified AvatarController, internally composes network layer based on configuration
+     * @param avatar - Avatar instance
+     * @param container - Canvas container element (required)
+     */
+    constructor(avatar: Avatar, container: HTMLElement);
+    /**
+     * Get controller (public interface)
+     */
+    get controller(): AvatarController;
+    /**
+     * Cleanup view resources
+     * Closes avatarController and cleans up all related resources
+     */
+    dispose(): void;
+    /**
+     * 获取相机配置
+     */
+    getCameraConfig(): CameraConfig | null;
+    /**
+     * 更新相机配置
+     */
+    updateCameraConfig(cameraConfig: CameraConfig): void;
+    /**
+     * Render a single animation frame from raw protobuf data.
+     *
+     * Decodes the protobuf Message internally and renders the first keyframe.
+     * This is the preferred method for RTC consumers that receive raw animation bytes.
+     *
+     * @param data - Raw protobuf bytes (a single Message containing ServerResponseAnimation)
+     */
+    renderFromProtobuf(data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Play a transition from idle to the target frame in the protobuf data,
+     * then resolve when the transition is complete.
+     *
+     * The transition frames are generated and played internally at 25fps.
+     * The caller should wait for the returned Promise before pushing streaming frames.
+     *
+     * @param data - Raw protobuf bytes containing the target frame
+     * @param frameCount - Number of transition frames to generate
+     * @returns Promise that resolves when the transition playback finishes
+     */
+    playTransitionFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number): Promise<void>;
+    /**
+     * Play a transition from current animation back to idle,
+     * then start the idle animation loop.
+     *
+     * Generates reverse transition frames from idle→lastFrame, reverses them,
+     * plays at 25fps, then starts idle.
+     *
+     * @param data - Raw protobuf bytes containing the last animation frame
+     * @param frameCount - Number of transition frames to generate
+     * @returns Promise that resolves when idle animation starts
+     */
+    playTransitionToIdleFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number): Promise<void>;
+    /**
+     * 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.
+     */
+    cancelFrameSequence(): void;
+    /**
+     * Pause rendering loop
+     *
+     * When called:
+     * - Rendering loop stops (no GPU/canvas updates)
+     * - Audio playback continues normally
+     * - Animation state machine continues running
+     *
+     * Use `resumeRendering()` to resume rendering.
+     *
+     * @example
+     * // Stop rendering to save GPU resources (audio continues)
+     * avatarView.pauseRendering()
+     */
+    pauseRendering(): void;
+    /**
+     * Resume rendering loop
+     *
+     * When called:
+     * - Rendering loop resumes from current state
+     * - If in Idle state, immediately renders current frame to restore display
+     *
+     * @example
+     * // Resume rendering
+     * avatarView.resumeRendering()
+     */
+    resumeRendering(): void;
+    /**
+     * Check if rendering is currently enabled
+     * @returns true if rendering is enabled, false if paused
+     */
+    isRenderingEnabled(): boolean;
+    /**
+     * Get or set avatar transform in canvas
+     *
+     * @example
+     * // Get current transform
+     * const current = avatarView.avatarTransform
+     *
+     * // Set transform
+     * avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 }
+     */
+    get avatarTransform(): {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    set avatarTransform(value: {
+        x: number;
+        y: number;
+        scale: number;
+    });
+}