@xmov/avatar 2.0.0-alpha.38

package/src/types/index.ts

@@ -0,0 +1,207 @@
+import type XmovAvatar from "../index"
+import type { IRawWidgetData } from "./frame-data"
+import type { SDKError } from "./error"
+import type { TDownloadProgress } from "../modules/ResourceManager"
+import { FPSStats } from "../utils/fpsTracker";
+
+export { ERROR_CODE_MAP, ERROR_NAME_MAP } from './error';
+
+export type {
+  CapabilitySeverity,
+  CapabilityName,
+  ICapabilityCheckItem,
+  ICapabilityCheckReport,
+} from './capability';
+
+export enum AvatarStatus {
+  // initialized = 0,
+  online = 0,      // 在线可见状态（合并了原来的 playing）
+  offline = 1,
+  network_on = 2,  // 已废弃
+  network_off = 3, // 已废弃
+  close = 4,
+  visible = 5,    // 可见状态
+  invisible = 6,   // 隐身状态（原来的 paused）
+  stopped = 7,     // 已废弃
+}
+
+
+/**
+ * 渲染状态枚举
+ * 用于表示渲染器的状态，与数字人状态（AvatarStatus）分离
+ */
+export enum RenderState {
+  init = 'init',              // 开始渲染（初始状态，准备开始）
+  rendering = 'rendering',     // 渲染中（正在渲染）
+  pausing = 'pausing',          // 暂停渲染中（正在暂停渲染）
+  paused = 'paused',          // 暂停渲染（暂停但保留数据）
+  resumed = 'resumed',        // 恢复渲染（从暂停恢复）
+  stopped = 'stopped',        // 渲染停止（完全停止）
+}
+
+
+/**
+ * 网络情况
+ * @params downlink 下载速率（Mbps）
+ * @params rtt 延迟（毫秒）
+ */
+export interface INetworkInfo {
+  downlink: number
+  rtt: number
+  networkStatus: boolean
+}
+
+export enum InitModel {
+  normal = 'normal',
+  invisible = 'invisible',
+}
+
+export interface IInitParams {
+  scaleDownBy?: any
+  useAlphaMask?: any
+  initModel?: InitModel
+  onDownloadProgress: TDownloadProgress;
+}
+export interface IAvatarOptions {
+  sdkInstance?: XmovAvatar
+  containerId: string
+  container?: HTMLElement
+  appId: string
+  appSecret: string
+  gatewayServer: string // back
+  tag?: string // 标签 指定特定房间
+  gateway_type?: string // gateway类型，默认为default
+  asr_id?: number // Agent ASR 配置 ID
+  llm_id?: number // Agent LLM 配置 ID
+  session_speak_req_id?: 0 | 1 // Agent 会话播报序号起始值：0 无开场白，1 有开场白
+  headers?: Record<string, string> // 自定义请求头
+  cacheServer?: string
+  env?: string
+  config?: any
+  hardwareAcceleration?: string
+  enableClientInterrupt?: boolean
+  enableLogger?: boolean // 是否启用日志
+  enableDebugger?: boolean // 是否启用调试模式
+  audioOnlyMode?: boolean // 音频+事件模式（无渲染模式）：仅保留音频播放和UI事件，不执行数字人渲染
+  renderMode?: 'client' | 'server' // 渲染模式：client=薄客户端(video播放)，server/undefined=完整渲染
+  streamingServer?: string // 薄客户端模式下，Streaming Server 的 WebSocket 地址
+  useAlphaMask?: boolean // 是否启用 alpha mask 透明背景（双路流方案）
+  scaleDownBy?: number
+  onMessage: (error: SDKError) => void
+  onStartSessionWarning?: (message: Object) => void
+  onAAFrameHandle?: (data: any) => void
+  onNetworkInfo?(networkInfo: INetworkInfo): void
+  onWidgetEvent?(data: IRawWidgetData): void
+  proxyWidget?: {
+    [key: string]: (data: any) => void
+  }
+  onStateChange?(state: string): void;
+  onStateRenderChange?(state: string, duration: number): void;
+  onSpeakStateChange?(state: string, client_speak_id: string | number): void;
+  onRenderChange?(state: RenderState): void;
+  onVoiceStateChange?(state: string, duration?: number, client_speak_id?: string | number): void;
+  onStatusChange?(status: AvatarStatus): void;
+  onWalkStateChange?(state: string): void;
+  onFPSUpdate?(stats: FPSStats): void;
+  /**
+   * 数字人音频实时播放数据回调
+   * - MSE/WebM 模式（raw_audio=false）：通过 AudioWorklet + WebCodecs 捕获和编码
+   * - PCM 模式（raw_audio=true）：通过 capture worklet + WebCodecs/MediaRecorder 编码
+   * 两种模式输出格式完全一致（WebM/Opus），业务侧无需区分
+   */
+  onAudioPlaybackData?(data: IAudioPlaybackData): void;
+  /**
+   * 每帧数据回调
+   * 返回当前帧的 face + body 原始数据（帧号、body_id 等）
+   */
+  onFrameDataUpdate?(data: IFrameDataUpdate): void;
+}
+
+/**
+ * 音频播放数据回调参数（farend 格式）
+ * 用于 ASR 回声消除（AEC），由 Agent 封装为 AU v1 farend Binary 帧
+ */
+export interface IAudioPlaybackData {
+  data: ArrayBuffer;       // opus 音频原始数据（WebM 容器）
+  codec: string;                // 编码格式，固定 "opus"
+  isFirstChunk: boolean;        // 是否为该 speak 段的首段数据（包含 WebM 容器头）
+  sampleRate: number;           // 采样率
+  samples: number;              // 等效采样点数（100ms 对应的采样数）
+  timestamp: number;            // 当前 100ms 音频块起点的 epoch 毫秒时间戳
+  speech_id: number;            // 当前轮次id
+}
+
+/**
+ * 帧数据回调参数
+ * 用于返回每一帧的 face + body 原始数据（不包含渲染数据）
+ */
+export interface IFrameDataUpdate {
+  /** 客户端帧号 */
+  frameIndex: number;
+  /** body 数据 */
+  body: {
+    /** body_id */
+    body_id: number;
+    /** 视频名称 */
+    name: string;
+    /** 视频内帧号（相对于视频起始的帧偏移） */
+    video_frame: number;
+    /** 起始帧号 */
+    sf: number;
+    /** 当前状态 */
+    state: string;
+  } | null;
+  /** face 数据（不包含骨骼渲染数据） */
+  face: {
+    /** body_id */
+    body_id: number;
+    /** 起始帧号 */
+    sf: number;
+    /** 结束帧号 */
+    ef: number;
+    /** 状态 */
+    state: string;
+    /** face 帧类型：0=原始数据，1=实时数据 */
+    face_frame_type: number;
+  } | null;
+}
+
+export interface DeviceInfo {
+  device_id: string
+  device_brand: string
+  device_model: string
+  os_version: string
+  browser: string
+  browser_version: string
+  browser_ua: string
+  sdk_version: string
+  resolution: {
+    width: number
+    height: number
+  }
+  download_speed: number
+  decode_speed: number
+  render_speed: number
+}
+
+export interface Layout {
+  container: {
+    size: number[]
+  },
+  avatar: {
+    v_align: string //'left' | 'center' | 'right'
+    h_align: string //'top' | 'center' | 'bottom'
+    scale: number | string
+    offset_x: number
+    offset_y: number
+  }
+}
+
+export interface WalkConfig {
+  min_x_offset: number
+  max_x_offset: number
+  walk_points: {
+    [key: string]: number
+  }
+  init_point?: number
+}

package/src/types/render.ts

@@ -0,0 +1,18 @@
+export interface IBackgroundRender {
+  render(): HTMLElement
+}
+export interface IImgRender {
+  render(): HTMLElement
+}
+export interface ITextRender {
+  render(): HTMLElement
+}
+export interface IVideoRender {
+  render(): HTMLElement
+}
+export interface I3DRender {
+  render(): HTMLCanvasElement
+}
+export interface ISubtitleRender {
+  render(): HTMLElement
+}