数字人形象

⚠️ 方案说明（重要）

本项目使用 UE 数字人（UE PixelStreaming 自集成方案，见 UE 联调）。

src/components/Avatar 下的 GLB 数字人（React + Three.js / iframe 方案）已废弃，仅作为 UE 不可用时的兜底回退保留，新接入不要再使用。

大屏通过 src/components/Avatar/Core/Avatar.vue 渲染数字人形象：当配置了 UE 信令地址（VITE_APP_UE_SIGNALLING_URL）时，自动切换为 UE PixelStreaming 自集成方案；未配置或 UE 初始化失败时才回退到已废弃的 iframe（GLB）方案。

---

一、GLB 数字人（iframe，已废弃，仅作兜底）

已废弃：以下 React + Three.js（GLB）iframe 方案不再使用，仅在 UE 未配置 / 初始化失败（handleSelfHostError）时由 Avatar.vue 回退。新项目请直接使用 UE 方案（见第二节）。

数字人通过 iframe 加载 React 应用（默认 VITE_APP_AVATAR_URL），使用 postMessage 双向通信。

口型与动作驱动

• 驱动消息为 DriveAvatarBroadcast，载荷包含 audio（前端合成的静音 WAV，8kHz / 单声道 / 16bit）、audioType、lipsync（口型关键帧）、animation: 'Idle'。
• 口型用 8 个 viseme 循环序列（PP / kk / I / AA / O / U / FF / TH），每 0.12s 一帧，片段时长 0.9s、间隔 700ms 循环推送；停止时推送一个 0.06s 空片段立即复位。

驱动来源分模式

来源	驱动条件
系统导览	isDemoSpeaking（段落音频播报中）
智能交互 / 专家问答	isTTSPlaying（TTS 序列播放中）
工具调用进行中（status === 'calling'）	暂停口型

• 系统导览气泡内容优先取 streamingContent（逐字打字机效果）；新一轮刚开始（demoRoundStarted = false）时返回空，避免闪回上一轮文本；段间空档回退到最近一条 assistant 消息。

---

二、UE 自集成方案（当前使用）

Avatar.vue 检测到 VITE_APP_UE_SIGNALLING_URL 配置且 UE 实例初始化成功时，渲染 UePixelStreaming 组件（本项目实际使用的方案）：

• 语音一律由前端播放，统一转成 PCM 16bit 单声道 16000Hz 后连续投喂 UE；
• UE 不做 TTS、也不解码，只按采样序列驱动数字人口型与动作；
• UE 通道不通不影响出声，只是数字人不做口型（前端语音照常播放）。

完整的音频协议、分片、起播对齐与踩坑清单见 UE 联调。