@spatius/avatarkit 1.3.9 → 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;
@@ -132,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;
     /**
@@ -173,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)
      */

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;
@@ -72,7 +73,7 @@ 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.
+     * 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.

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 {
@@ -36,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)
      */