@spatius/avatarkit 1.3.8 → 1.3.10-beta.1

package/dist/core/AvatarController.d.ts

@@ -1,9 +1,30 @@
 import { Avatar } from './Avatar';
-import { ConnectionState, AvatarError, DrivingServiceMode, FrameStarvationMode, ConversationState, AnimationType } from '../types';
+import { ConnectionState, AvatarError, DrivingServiceMode, FrameStarvationMode, ConversationState, AnimationType, AudioFormat, AudioFormatPatch } from '../types';
 import { FrameRateInfo } from '../performance/FrameRateMonitor';
 export declare class AvatarController {
     private networkLayer?;
     private readonly playbackMode;
+    /**
+     * 宿主**要求**的音频格式：构造时传入的值，之后由 {@link setAudioFormat} 逐字段合并。
+     * 与 `_audioFormat` 分开存，是为了让规范化可逆：22050 + Opus 上行会被规范化成
+     * 「Opus 上行关」，之后把采样率改回 16000 时上行应当自动恢复——只存规范化后的值就找
+     * 不回宿主原本要的 `opusUplinkEnabled: true` 了。唯一不可逆的一条：切到 Opus 输入时
+     * 采样率写死 48000（与 Android / iOS 的 `AudioFormat` 构造语义一致，三端同形）。
+     */
+    private _requestedAudioFormat;
+    /**
+     * 本 view 生效的音频格式（已规范化）。**不是全局的**：同一页面里两个 view 可以跑不同
+     * 采样率。构造时定下，之后任一字段都可经 {@link setAudioFormat} 改。
+     */
+    private _audioFormat;
+    /**
+     * 本 view 生效的音频格式（已规范化）。只读——改格式走 {@link setAudioFormat}。
+     *
+     * 对外可读，与 iOS `AvatarController.audioFormat` / Android `AvatarController.audioFormat`
+     * 对齐：宿主传进去的值会被规范化（Opus 输入归一到 48 kHz、不兼容的 Opus 上行采样率会关掉
+     * Opus 上行），读回来才能确认实际生效的是什么。
+     */
+    get audioFormat(): AudioFormat;
     private isStartingPlayback;
     private currentConversationId;
     private reqEnd;
@@ -69,6 +90,11 @@ export declare class AvatarController {
     private receivedAudioBytes;
     private receivedAnimationFrames;
     private playbackStartedAt;
+    /**
+     * 新一轮起播时 SDK 自己打断上一轮走的也是 interrupt()；那不是宿主的动作，不记
+     * lifecycle_api_called。内部调用经 interruptForNewRound() 置位后再进 interrupt()。
+     */
+    private suppressLifecycleEvent;
     private playbackEndedAt;
     /**
      * Whether this round's final animation batch (ServerResponseAnimation.end) has arrived.
@@ -127,11 +153,12 @@ export declare class AvatarController {
     /**
      * 音频字节率（bytes/s），按 **实际配置的采样率** 动态计算，而不是写死 16kHz。
      * SDK 支持 8k/16k/22.05k/24k/32k/44.1k/48k，写死会让非 16k 的时长统计整体缩放出错。
-     * Opus 输入已被 AvatarSDK.getAudioFormat() 归一化成 48000，正是解码后 PCM 的真实采样率。
+     * Opus 输入已被 normalizeAudioFormat 归一化成 48000，正是解码后 PCM 的真实采样率。
      */
     private get audioBytesPerSecond();
     constructor(avatar: Avatar, options?: {
         playbackMode?: DrivingServiceMode;
+        audioFormat?: AudioFormat;
     });
     private handleVisibilityChange;
     /**
@@ -168,6 +195,50 @@ export declare class AvatarController {
      * on PCM exactly as before.
      */
     private normalizeInputAudioToPcm;
+    /**
+     * 改本 view 的音频格式——**部分更新**：传什么改什么，没传的字段保持原状。
+     *
+     * 四个字段走同一条路，不区分「重」「轻」：**打断当前轮次 → 销毁音频上下文 → 写入新格式
+     * → direct 模式断连**。之后喂入的音频按新格式解释；下次 `start()` 时编码器、输入解码器与
+     * 会话配置都按新格式重建。
+     *
+     * - 不设 idle 门禁：「音频已喂进来、动画还在路上、尚未起播」这个中间态既不是 idle 也不在
+     *   播，恰恰必须清干净；interrupt 本就是为此存在的，idle 且无音频时它是空操作。
+     * - **只销毁音频上下文，不重建**：`AudioContext` 的采样率是构造参数、Web Audio 不允许改，
+     *   而重建需要用户手势——那是 SDK 保证不了、只有宿主知道的前提。宿主在自己的手势回调里调
+     *   {@link initializeAudioContext} 重建；在那之前 `send()` 会经 `onError` 报
+     *   `audioContextNotInitialized` 并返回 null，不会静默无声。
+     * - 断连而不自动重连：宿主接下来还要重建上下文，连接由它后续的 `start()` 带起。
+     *
+     * 规则：
+     * - 切到 `inputAudioFormat: 'opus'` 时采样率写死 48000（Opus 解码固定值），传了别的值也
+     *   会被改写。切回 `'pcm'` 时采样率**保持当前值**（可能是 48000）——要换就在同一次调用里
+     *   一起传 `sampleRate`。
+     * - 采样率不兼容 Opus 上行（不是 8k/16k/24k/48k）时 Opus 上行会被关掉；之后把采样率改回
+     *   兼容值，上行按宿主原本的要求自动恢复。
+     * - 传入的值与当前要求完全一致时什么都不做（不打断、不销毁、不断连）。
+     *
+     * **两种非法用法都只记一条 `logger.error` 后原样返回**，不抛异常也不进 `onError`：
+     * 1. `sampleRate` 不在支持列表里（8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000）
+     * 2. 在 Opus 输入下传 `sampleRate`（无论是本来就是 Opus 输入，还是这一次一起切过去）
+     *
+     * 都是调用方把代码写错了，不是运行期可恢复的 SDK 故障。走 `onError` 并不更可靠：那是
+     * 可选回调，宿主未必注册、注册了也未必打到控制台；为它们新增 ErrorCode 还会平白扩大
+     * 三端公开错误码面。注释 + 日志 + 文档已经够让写代码的人当场发现。三端一致。
+     */
+    setAudioFormat(patch: AudioFormatPatch): void;
+    /**
+     * 把错误交给宿主，同时写一条 `logger.error`。
+     *
+     * **所有 onError 都必须走这里。** 直接调 `this.onError?.()` 的写法曾让 9 个调用点里 7 个
+     * 不打日志：宿主如果没把回调接到 console（demo 的 log() 就只写页面面板），这些错误在
+     * 控制台完全不可见，排查时看起来像「什么都没发生」——一次上下文未初始化的正常拒绝，
+     * 因此被当成功能失效查了很久。
+     *
+     * 日志走 SDK 自己的 logger（受 logLevel 控制），宿主自己再打一条也无妨：重复一行日志的
+     * 代价，远小于一条错误在控制台彻底消失。
+     */
+    private emitError;
     /**
      * Start service (SDK mode only)
      */
@@ -210,6 +281,14 @@ export declare class AvatarController {
      * Animation will continue from paused frame (because animation time base comes from audio, will auto-sync)
      */
     resume(): Promise<void>;
+    /**
+     * 宿主调了 close / interrupt（AvatarView.dispose 在 View 里记）。带调用栈：排查
+     * "数字人中途消失"时，这条日志直接指出是宿主哪段代码在断连后多久做了什么。
+     * 在播时记 warning，便于按级别筛出"播到一半被宿主打断"。
+     */
+    private logLifecycleCall;
+    /** SDK 内部起新一轮时打断上一轮：走 interrupt() 但不记宿主生命周期事件。 */
+    private interruptForNewRound;
     /**
      * Interrupt current playback
      */

package/dist/core/AvatarSDK.d.ts

@@ -1,4 +1,5 @@
 import { Configuration, RenderQuality } from '../types';
+/** PCM 输入 + Opus 上行时受支持的采样率（Opus 编码器可用的采样率）。 */
 export declare class AvatarSDK {
     private static _initializationState;
     private static _initializingPromise;
@@ -48,6 +49,15 @@ export declare class AvatarSDK {
     /**
      * Cleanup resources
      */
+    private static onPageHide;
+    /**
+     * pagehide 时直发一条 `page_unload`：整页刷新 / 关闭是"数字人整个消失"的一种来源
+     * （宿主自己 reload 切 region 就是实例），服务端只能看到一个 1001，客户端此前什么都
+     * 不留。走 emitDirectLog（fetch keepalive）而不是 logEvent——后者先写 IndexedDB 再等
+     * 批处理，页面卸载时发不出去。
+     */
+    private static installPageHideProbe;
+    private static removePageHideProbe;
     static cleanup(): void;
     /**
      * Device performance score (CPU + GPU).
@@ -63,9 +73,10 @@ export declare class AvatarSDK {
     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.
+     * Runs a ~2s benchmark, reports device info and scores via telemetry.
+     * Returns false when neither WebGL2 nor WebGPU can be created — that is deterministic
+     * and the benchmark is skipped. Otherwise runs the benchmark and returns true; the
+     * score thresholds are not yet enforced and will be calibrated from production data.
      */
     static isDeviceSupported(): Promise<boolean>;
-    private static _getGPURenderer;
 }

package/dist/core/AvatarView.d.ts

@@ -1,4 +1,4 @@
-import { CameraConfig } from '../types';
+import { AvatarViewOptions, CameraConfig } from '../types';
 import { Avatar } from './Avatar';
 import { AvatarController } from './AvatarController';
 export declare class AvatarView {
@@ -13,6 +13,10 @@ export declare class AvatarView {
     private resizeObserver;
     private onWindowResize;
     private onVisibilityChange;
+    private canvasSeenConnected;
+    private canvasDetachedReported;
+    private containerSeenSized;
+    private containerHiddenReported;
     private frameCount;
     private lastFpsUpdate;
     private currentFPS;
@@ -32,8 +36,9 @@ export declare class AvatarView {
      * Creates a unified AvatarController, internally composes network layer based on configuration
      * @param avatar - Avatar instance
      * @param container - Canvas container element (required)
+     * @param options - Per-view options; see {@link AvatarViewOptions}
      */
-    constructor(avatar: Avatar, container: HTMLElement);
+    constructor(avatar: Avatar, container: HTMLElement, options?: AvatarViewOptions);
     /**
      * Get controller (public interface)
      */
@@ -100,8 +105,12 @@ export declare class AvatarView {
      * to work correctly with WebGL preserveDrawingBuffer:false.
      */
     exportBitmap(): Promise<Blob | null>;
-    /** @deprecated Use startRenderLoop() */
-    private startIdleAnimationLoop;
+    /**
+     * 当前初始化走到哪一步。供构造函数里的最终 catch 上报 `render_init_failed.stage`：
+     * 各步骤抛的错误类型五花八门（Error / AvatarError / WASM 抛的字符串），只靠
+     * message 没法聚合，stage 才是能按环节切分的低基数字段。
+     */
+    private _initStage;
     /**
      * Render a specific idle frame by index for benchmark capture.
      * Bypasses animation loop and _renderingEnabled check.
@@ -118,11 +127,17 @@ export declare class AvatarView {
      */
     dispose(): void;
     /**
-     * 获取相机配置
+     * 获取相机配置。
+     *
+     * @deprecated 1.3.9 起弃用，下个版本移除。相机由角色自身的设置决定，渲染基线也按它校准；
+     * 宿主侧改 fov / 位置会让画面偏离基线。没有替代接口——请删除宿主侧的相机覆盖逻辑。
+     * SDK 自己的评测链路（web-iframe）仍可调用。
      */
     getCameraConfig(): CameraConfig | null;
     /**
-     * 更新相机配置
+     * 更新相机配置。
+     *
+     * @deprecated 1.3.9 起弃用，下个版本移除，理由见 {@link getCameraConfig}。
      */
     updateCameraConfig(cameraConfig: CameraConfig): void;
     /**
@@ -134,30 +149,6 @@ export declare class AvatarView {
      * @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).
      */
@@ -189,10 +180,19 @@ export declare class AvatarView {
         useLinear?: boolean;
     }): Promise<unknown[]>;
     /**
-     * Cancel any in-progress frame sequence playback.
-     * Called by renderFromProtobuf when streaming frames arrive during transition.
+     * canvas 是否还挂在 DOM 上。宿主卸载父组件而没调 dispose() 时，canvas 会跟着容器
+     * 一起被移除，SDK 却还在跑：没有任何现有埋点会响。渲染循环每 tick 查一次
+     * `isConnected`（不触发 layout），脱离时记一条 error，重新挂回记一条 info。
+     * 只在 canvas 曾经在 DOM 里之后才判，避免离屏构造的误报。
+     */
+    private probeCanvasAttachment;
+    /**
+     * 容器被缩成 0×0（display:none 或父级折叠）时 ResizeObserver 会回调一次 0 尺寸。
+     * 画面还在 DOM 里但用户看不见，与 detach 是不同的消失方式，分开记。
+     * 只在容器曾有过非零尺寸之后才判。
      */
-    cancelFrameSequence(): void;
+    private probeContainerVisibility;
+    private syncCanvasSize;
     /** 计算 canvas backing-store 像素尺寸. 默认 css × dpr;
      *  AvatarSDK.setRenderResolutionCap 启用且高度超过阈值时,
      *  按比例缩到阈值, css 尺寸不变 (浏览器自动拉伸). */

package/dist/core/avatarViewRegistry.d.ts

@@ -3,6 +3,8 @@ declare class AvatarViewRegistry {
     private entries;
     register(view: AvatarView): void;
     unregister(view: AvatarView): void;
+    /** 遍历仍存活的 view（顺手清掉已被 GC 的弱引用）。 */
+    forEachLive(fn: (view: AvatarView) => void): void;
     applyResolutionCapToAll(): void;
 }
 export declare const avatarViewRegistry: AvatarViewRegistry;