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

package/dist/core/AvatarView.d.ts

@@ -1,4 +1,4 @@
-import { Flame } from '../generated/driveningress/v1/driveningress';
+import { KeyframeData } from '../types';
 import { Avatar } from './Avatar';
 import { AvatarController } from './AvatarController';
 export declare class AvatarView {
@@ -32,40 +32,173 @@ export declare class AvatarView {
     private isPureRenderingMode;
     private avatarActiveTimer;
     private readonly AVATAR_ACTIVE_INTERVAL;
+    /**
+     * 对齐两端 Flame 维度：标量统一长度，expression 取最大长度并零填充
+     */
     private alignFlamePair;
+    /**
+     * 生成并对齐过渡帧，确保首尾帧与起止帧完全一致
+     * @param from 起始帧
+     * @param to 目标帧
+     * @param durationMs 过渡时长（开头或结尾）
+     * @param useLinearInterpolation 是否使用线性插值（旧实现），true 用于 idle->speaking，false 用于 speaking->idle（使用 Bezier 曲线）
+     */
     private generateAndAlignTransitionFrames;
+    /**
+     * 获取缓存的 Idle 首帧，如果未缓存则获取并缓存
+     */
     private getCachedIdleFirstFrame;
+    /**
+     * 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;
+    /**
+     * 创建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;
+    /**
+     * 准备实时渲染（生成过渡到 Speaking）
+     * 统一逻辑：从当前正在播放的帧 -> Speaking 第一帧
+     */
     private prepareRealtimeRendering;
+    /**
+     * 开始实时渲染循环
+     */
     private startRealtimeRendering;
+    /**
+     * 停止实时对话渲染
+     */
     private stopRealtimeRendering;
+    /**
+     * Cleanup view resources
+     * Closes avatarController and cleans up all related resources
+     */
     dispose(): void;
-    renderFlame(flame: Flame, enableIdleRendering?: boolean): Promise<void>;
-    generateTransitionFromIdle(toFlame: Flame, frameCount: number, transitionType?: 'start' | 'end'): Promise<Flame[]>;
+    /**
+     * 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[]>;
+    /**
+     * 使用新的相机配置重新渲染当前帧（用于暂停状态下更新相机）
+     * 复用 AvatarController 的重新渲染逻辑，因为 renderCallback 会调用 renderRealtimeFrame，
+     * 而 renderRealtimeFrame 会使用已更新的相机配置（通过 renderSystem.updateCamera）
+     * @private
+     */
     private rerenderCurrentFrameWithNewCamera;
+    /**
+     * 处理尺寸变化：通知渲染系统更新视口与投影
+     */
     private handleResize;
+    /**
+     * 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;
@@ -76,7 +209,19 @@ export declare class AvatarView {
         y: number;
         scale: number;
     });
+    /**
+     * 上报 avatar_active 埋点
+     * @private
+     */
     private reportAvatarActive;
+    /**
+     * 启动 avatar_active 心跳埋点（每10分钟一次）
+     * @private
+     */
     private startAvatarActiveHeartbeat;
+    /**
+     * 停止 avatar_active 心跳埋点
+     * @private
+     */
     private stopAvatarActiveHeartbeat;
 }

package/dist/core/NetworkLayer.d.ts

@@ -1 +1,7 @@
+/**
+ * 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

@@ -1,10 +1,17 @@
 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>;

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

@@ -9,19 +9,29 @@ 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

@@ -4,9 +4,9 @@ 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,
@@ -31,7 +31,9 @@ export interface GetCharacterInfoRequest {
     characterId: string;
 }
 export interface CharacterAsset {
+    /** 资产ID，例如 "v1/xxx" */
     characterId: string;
+    /** 资产版本，例如 "1.0.0" */
     version: string;
     createdAt?: Timestamp | undefined;
     updatedAt?: Timestamp | undefined;
@@ -42,6 +44,7 @@ export interface CharacterAsset {
     characterSettings?: {
         [key: string]: any;
     } | undefined;
+    /** 自定义动画列表 */
     customAnimations: CustomAnimation[];
 }
 export interface Resource {

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

@@ -1,15 +1,30 @@
 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;
     };
@@ -18,19 +33,37 @@ 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;

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

@@ -1,8 +1,109 @@
 import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
 export declare const protobufPackage = "google.protobuf";
-
+/**
+ * A Timestamp represents a point in time independent of any time zone or local
+ * calendar, encoded as a count of seconds and fractions of seconds at
+ * nanosecond resolution. The count is relative to an epoch at UTC midnight on
+ * January 1, 1970, in the proleptic Gregorian calendar which extends the
+ * Gregorian calendar backwards to year one.
+ *
+ * All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
+ * second table is needed for interpretation, using a [24-hour linear
+ * smear](https://developers.google.com/time/smear).
+ *
+ * The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
+ * restricting to that range, we ensure that we can convert to and from [RFC
+ * 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
+ *
+ * # Examples
+ *
+ * Example 1: Compute Timestamp from POSIX `time()`.
+ *
+ *     Timestamp timestamp;
+ *     timestamp.set_seconds(time(NULL));
+ *     timestamp.set_nanos(0);
+ *
+ * Example 2: Compute Timestamp from POSIX `gettimeofday()`.
+ *
+ *     struct timeval tv;
+ *     gettimeofday(&tv, NULL);
+ *
+ *     Timestamp timestamp;
+ *     timestamp.set_seconds(tv.tv_sec);
+ *     timestamp.set_nanos(tv.tv_usec * 1000);
+ *
+ * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
+ *
+ *     FILETIME ft;
+ *     GetSystemTimeAsFileTime(&ft);
+ *     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
+ *
+ *     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
+ *     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
+ *     Timestamp timestamp;
+ *     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
+ *     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
+ *
+ * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
+ *
+ *     long millis = System.currentTimeMillis();
+ *
+ *     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
+ *         .setNanos((int) ((millis % 1000) * 1000000)).build();
+ *
+ * Example 5: Compute Timestamp from Java `Instant.now()`.
+ *
+ *     Instant now = Instant.now();
+ *
+ *     Timestamp timestamp =
+ *         Timestamp.newBuilder().setSeconds(now.getEpochSecond())
+ *             .setNanos(now.getNano()).build();
+ *
+ * Example 6: Compute Timestamp from current time in Python.
+ *
+ *     timestamp = Timestamp()
+ *     timestamp.GetCurrentTime()
+ *
+ * # JSON Mapping
+ *
+ * In JSON format, the Timestamp type is encoded as a string in the
+ * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+ * format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
+ * where {year} is always expressed using four digits while {month}, {day},
+ * {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
+ * seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+ * are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+ * is required. A proto3 JSON serializer should always use UTC (as indicated by
+ * "Z") when printing the Timestamp type and a proto3 JSON parser should be
+ * able to accept both UTC and other timezones (as indicated by an offset).
+ *
+ * For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+ * 01:30 UTC on January 15, 2017.
+ *
+ * In JavaScript, one can convert a Date object to this format using the
+ * standard
+ * [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
+ * method. In Python, a standard `datetime.datetime` object can be converted
+ * to this format using
+ * [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
+ * the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
+ * the Joda Time's [`ISODateTimeFormat.dateTime()`](
+ * http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
+ * ) to obtain a formatter capable of generating timestamps in this format.
+ */
 export interface Timestamp {
+    /**
+     * Represents seconds of UTC time since Unix epoch
+     * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
+     * 9999-12-31T23:59:59Z inclusive.
+     */
     seconds: string;
+    /**
+     * Non-negative fractions of a second at nanosecond resolution. Negative
+     * second values with fractions must still have non-negative nanos values
+     * that count forward in time. Must be from 0 to 999,999,999
+     * inclusive.
+     */
     nanos: number;
 }
 export declare const Timestamp: MessageFns<Timestamp>;