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

package/dist/core/AvatarView.d.ts

@@ -1,10 +1,10 @@
-import { CameraConfig, RenderPerformanceStats, AvatarViewOptions, AvatarPlaybackMode } from '../types';
+import { KeyframeData } from '../types';
 import { Avatar } from './Avatar';
 import { AvatarController } from './AvatarController';
 export declare class AvatarView {
     private readonly avatarController;
-    readonly playbackMode: AvatarPlaybackMode;
     private readonly avatar;
+    onFirstRendering?: () => void;
     private canvas;
     private renderSystem;
     private isInitialized;
@@ -17,155 +17,70 @@ export declare class AvatarView {
     private realtimeAnimationLoopId;
     private resizeObserver;
     private onWindowResize;
+    private frameCount;
+    private lastFpsUpdate;
+    private currentFPS;
     private transitionKeyframes;
     private transitionStartTime;
-    private readonly transitionDurationMs;
+    private readonly startTransitionDurationMs;
+    private readonly endTransitionDurationMs;
     private cachedIdleFirstFrame;
     private idleCurrentFrameIndex;
+    private currentPlayingFrame;
+    private characterHandle;
+    private characterId;
+    private isPureRenderingMode;
+    private avatarActiveTimer;
+    private readonly AVATAR_ACTIVE_INTERVAL;
     /**
-     * 对齐两端 Flame 维度：标量统一长度，expression 取最大长度并零填充
+     * Constructor
+     * Creates a unified AvatarController, internally composes network layer based on configuration
+     * @param avatar - Avatar instance
+     * @param container - Canvas container element (required)
      */
-    private alignFlamePair;
+    constructor(avatar: Avatar, container: HTMLElement);
     /**
-     * 判断是否为空 Flame（用于跳过 isLast=true 的哨兵帧）
-     */
-    private isEmptyFlame;
-    /**
-     * 生成并对齐过渡帧，确保首尾帧与起止帧完全一致
-     */
-    private generateAndAlignTransitionFrames;
-    /**
-     * 获取缓存的 Idle 首帧，如果未缓存则获取并缓存
-     */
-    private getCachedIdleFirstFrame;
-    /**
-     * 构造函数
-     * 创建统一的 AvatarController，内部根据配置自动组合网络层
-     */
-    constructor(avatar: Avatar, options?: AvatarViewOptions);
-    /**
-     * 获取控制器（公共接口）
+     * Get controller (public interface)
      */
     get controller(): AvatarController;
     /**
-     * 创建canvas元素
-     */
-    private createCanvas;
-    /**
-     * 获取canvas元素（供外部访问）
-     */
-    getCanvas(): HTMLCanvasElement;
-    /**
-     * 初始化视图系统
-     */
-    private initializeView;
-    /**
-     * 初始化渲染系统
-     */
-    private initializeRenderSystem;
-    /**
-     * 获取默认相机配置
-     */
-    private getDefaultCameraConfig;
-    /**
-     * 根据资源解析最终的相机配置，优先使用角色设置，其次 camera.json
-     */
-    private resolveCameraConfig;
-    /**
-     * 从角色设置中推导相机配置
-     */
-    private deriveCameraConfigFromSettings;
-    /**
-     * 渲染第一帧
-     */
-    private renderFirstFrame;
-    /**
-     * 开始idle动画循环
-     */
-    private startIdleAnimationLoop;
-    /**
-     * 开始实时对话动画循环
-     */
-    private startRealtimeAnimationLoop;
-    /**
-     * 停止idle动画循环
-     */
-    private stopIdleAnimationLoop;
-    /**
-     * 停止实时对话动画循环
-     */
-    private stopRealtimeAnimationLoop;
-    /**
-     * 停止所有动画循环
-     */
-    private stopAllAnimationLoops;
-    /**
-     * 渲染实时帧（由播放层回调调用）
-     */
-    private renderRealtimeFrame;
-    /**
-     * 过渡完成回调（通知播放层启动音频）
-     */
-    private onTransitionComplete;
-    /**
-     * 状态转换方法
-     * 统一管理状态转换，确保状态一致性
-     */
-    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 并清理所有相关资源
+     * Cleanup view resources
+     * Closes avatarController and cleans up all related resources
      */
     dispose(): void;
     /**
-     * 获取相机配置
-     */
-    getCameraConfig(): CameraConfig | null;
-    /**
-     * 更新相机配置
-     */
-    updateCameraConfig(cameraConfig: CameraConfig): void;
-    /**
-     * 处理尺寸变化：通知渲染系统更新视口与投影
-     */
-    private handleResize;
-    /**
-     * 获取渲染性能统计
-     * @returns 渲染性能统计数据，如果渲染系统未初始化则返回 null
-     */
-    getPerformanceStats(): RenderPerformanceStats | null;
+     * 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>;
+    /**
+     * Generate transition frame array from current idle frame to target keyframe (pure rendering mode)
+     * @param toKeyframeData - Target keyframe data
+     * @param frameCount - Number of transition frames
+     * @param transitionType - Transition type: 'start' means Idle -> toKeyframeData (start transition), 'end' means toKeyframeData -> Idle (end transition)
+     * @returns Transition frame array with length of frameCount
+     */
+    generateTransitionFromIdle(toKeyframeData: KeyframeData, frameCount: number, transitionType?: 'start' | 'end'): Promise<KeyframeData[]>;
+    /**
+     * Get or set avatar transform in canvas
+     *
+     * @example
+     * // Get current transform
+     * const current = avatarView.transform
+     *
+     * // Set transform
+     * avatarView.transform = { x: 0.5, y: 0, scale: 2.0 }
+     */
+    get transform(): {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    set transform(value: {
+        x: number;
+        y: number;
+        scale: number;
+    });
 }
-//# sourceMappingURL=AvatarView.d.ts.map

package/dist/core/NetworkLayer.d.ts

@@ -1,59 +1,7 @@
-import { AvatarController } from './AvatarController';
-export declare class NetworkLayer {
-    private wsClient;
-    private dataController;
-    private currentReqId;
-    private hasSentEnd;
-    private readonly audioBytesPerSecond;
-    private audioMetrics;
-    constructor(dataController: AvatarController);
-    /**
-     * 连接服务
-     */
-    connect(characterId: string): Promise<void>;
-    /**
-     * 发送音频数据到服务器
-     */
-    sendAudioData(audioData: ArrayBuffer, isLast: boolean): void;
-    /**
-     * 断开连接
-     */
-    disconnect(): void;
-    /**
-     * 获取当前请求ID
-     */
-    getCurrentReqId(): string | null;
-    /**
-     * 重置请求ID（用于打断后清理）
-     */
-    resetReqId(): void;
-    /**
-     * 设置 WebSocket 事件监听器
-     */
-    private setupWebSocketListeners;
-    /**
-     * 处理接收到的消息
-     */
-    private handleMessage;
-    /**
-     * 处理动画消息
-     */
-    private handleAnimationMessage;
-    /**
-     * 处理错误消息
-     */
-    private handleErrorMessage;
-    /**
-     * 创建音频指标
-     */
-    private createAudioMetrics;
-    /**
-     * 重置音频指标
-     */
-    private resetAudioMetrics;
-    /**
-     * 上报音频指标
-     */
-    private reportAudioMetrics;
-}
-//# sourceMappingURL=NetworkLayer.d.ts.map
+/**
+ * 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/common/v1/models.d.ts

@@ -0,0 +1,36 @@
+import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
+export declare const protobufPackage = "common.v1";
+/**
+ * CustomAnimation 自定义动画配置
+ * 用于角色资产组的自定义动画定义
+ */
+export interface CustomAnimation {
+    /** 动画唯一标识 */
+    key: string;
+    /** pb类型动画文件URL */
+    pbUrl: string;
+    /** wav类型音频文件URL（可选） */
+    wavUrl: string;
+    /** 备注说明 */
+    remark: string;
+}
+export declare const CustomAnimation: MessageFns<CustomAnimation>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};

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

@@ -77,4 +77,3 @@ export interface MessageFns<T> {
     fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 export {};
-//# sourceMappingURL=driveningress.d.ts.map

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

@@ -1,6 +1,32 @@
 import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
+import { CustomAnimation } from '../../common/v1/models';
 import { Timestamp } from '../../google/protobuf/timestamp';
 export declare const protobufPackage = "driveningress.v2";
+export declare enum MessageType {
+    MESSAGE_UNSPECIFIED = 0,
+    /** MESSAGE_CLIENT_CONFIGURE_SESSION - 协商会话参数 */
+    MESSAGE_CLIENT_CONFIGURE_SESSION = 1,
+    /** MESSAGE_SERVER_CONFIRM_SESSION - 确认协商成功 */
+    MESSAGE_SERVER_CONFIRM_SESSION = 2,
+    MESSAGE_CLIENT_AUDIO_INPUT = 3,
+    MESSAGE_SERVER_ERROR = 4,
+    MESSAGE_SERVER_RESPONSE_ANIMATION = 5,
+    UNRECOGNIZED = -1
+}
+export declare function messageTypeFromJSON(object: any): MessageType;
+export declare function messageTypeToJSON(object: MessageType): string;
+export declare enum AudioFormat {
+    AUDIO_FORMAT_PCM_S16LE = 0,
+    UNRECOGNIZED = -1
+}
+export declare function audioFormatFromJSON(object: any): AudioFormat;
+export declare function audioFormatToJSON(object: AudioFormat): string;
+export declare enum TransportCompression {
+    TRANSPORT_COMPRESSION_NONE = 0,
+    UNRECOGNIZED = -1
+}
+export declare function transportCompressionFromJSON(object: any): TransportCompression;
+export declare function transportCompressionToJSON(object: TransportCompression): string;
 export interface GetCharacterInfoRequest {
     characterId: string;
 }
@@ -18,6 +44,8 @@ export interface CharacterAsset {
     characterSettings?: {
         [key: string]: any;
     } | undefined;
+    /** 自定义动画列表 */
+    customAnimations: CustomAnimation[];
 }
 export interface Resource {
     type: string;
@@ -38,12 +66,66 @@ export interface Animations {
     frameMono?: ResourceHolder | undefined;
     audioMono?: ResourceHolder | undefined;
 }
+export interface ClientConfigureSession {
+    sampleRate: number;
+    bitrate: number;
+    audioFormat: AudioFormat;
+    transportCompression: TransportCompression;
+}
+export interface ServerConfirmSession {
+    connectionId: string;
+}
+export interface ClientAudioInput {
+    reqId: string;
+    end: boolean;
+    audio: Uint8Array;
+}
+export interface ServerError {
+    connectionId: string;
+    reqId: string;
+    code: number;
+    message: string;
+}
+export interface Flame {
+    translation: number[];
+    rotation: number[];
+    neckPose: number[];
+    jawPose: number[];
+    eyePose: number[];
+    eyeLid: number[];
+    expression: number[];
+}
+export interface FlameAnimation {
+    keyframes: Flame[];
+}
+export interface ServerResponseAnimation {
+    connectionId: string;
+    reqId: string;
+    end: boolean;
+    animation?: FlameAnimation | undefined;
+}
+export interface Message {
+    type: MessageType;
+    clientConfigureSession?: ClientConfigureSession | undefined;
+    serverConfirmSession?: ServerConfirmSession | undefined;
+    clientAudioInput?: ClientAudioInput | undefined;
+    serverError?: ServerError | undefined;
+    serverResponseAnimation?: ServerResponseAnimation | undefined;
+}
 export declare const GetCharacterInfoRequest: MessageFns<GetCharacterInfoRequest>;
 export declare const CharacterAsset: MessageFns<CharacterAsset>;
 export declare const Resource: MessageFns<Resource>;
 export declare const ResourceHolder: MessageFns<ResourceHolder>;
 export declare const Models: MessageFns<Models>;
 export declare const Animations: MessageFns<Animations>;
+export declare const ClientConfigureSession: MessageFns<ClientConfigureSession>;
+export declare const ServerConfirmSession: MessageFns<ServerConfirmSession>;
+export declare const ClientAudioInput: MessageFns<ClientAudioInput>;
+export declare const ServerError: MessageFns<ServerError>;
+export declare const Flame: MessageFns<Flame>;
+export declare const FlameAnimation: MessageFns<FlameAnimation>;
+export declare const ServerResponseAnimation: MessageFns<ServerResponseAnimation>;
+export declare const Message: MessageFns<Message>;
 export interface DrivenIngressService {
     GetCharacterInfo(request: GetCharacterInfoRequest): Promise<CharacterAsset>;
 }
@@ -78,4 +160,3 @@ export interface MessageFns<T> {
     fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 export {};
-//# sourceMappingURL=driveningress.d.ts.map

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

@@ -105,4 +105,3 @@ export interface ListValueWrapperFns {
     unwrap(message: ListValue): Array<any>;
 }
 export {};
-//# sourceMappingURL=struct.d.ts.map

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

@@ -126,4 +126,3 @@ export interface MessageFns<T> {
     fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 export {};
-//# sourceMappingURL=timestamp.d.ts.map