> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/how-convai-embody-works.md).

# Convai Embody 的工作原理

了解 Convai Embody 如何将角色 ID 转换为会说话的 3D 身体，以及它为何共用一个连接并按固定顺序运行动作。

本页介绍 Convai Embody 如何从角色 ID 获取会说话的身体，以及背后的设计选择。如需了解如何将角色添加到页面，请参阅 [将 3D 角色添加到 React 应用](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md).

### 一份凭据，一个连接

会说话的角色由两部分组成：负责渲染的身体，以及负责聆听和回应的思维。Convai Web SDK 已经提供了思维，即一个 `ConvaiClient` ，它负责传输对话内容和角色语音。Convai Embody 添加了身体，并将两者连接起来。

Convai Embody 自行打开连接，而不是让应用提供客户端，是因为口型同步必须来自生成语音的同一会话。两个客户端意味着两个会话：一个会话提供听到的语音，另一个驱动嘴部，因此角色要么对着没有声音的内容动嘴，要么说话时一动不动。打开一个连接并将其作为 `character.client` 传回，就能避免这种故障。这也是聊天小组件通过 `useWidgetClient` 而非 `useConvaiClient`接收连接的原因；后者会创建第二个客户端。

默认情况下，该连接会向 Convai 请求 MetaHuman 混合形状帧。如果不发出此请求，Convai 就不会发送口型同步数据，角色说话时脸部也会一动不动。

嘴部会跟随实际播放的语音，而不是帧发送时所依据的时钟。浏览器会暂存并拉伸收到的音频，以平滑网络抖动，因此按固定时钟播放的帧会在回复过程中逐渐与语音错开。Convai Embody 会读取接收音频的播放位置，并显示对应时刻的帧；遇到网络中断时，它会保持当前帧，以便中断后嘴部仍与语音同步。

### 从角色 ID 到身体

```mermaid
graph LR
    A["角色 ID 和凭据"] --> B["Convai 解析身体清单"]
    B --> C["选择受支持的绑定"]
    C --> D["加载并规范化模型"]
    D --> E["播放待机动画片段"]
    A --> F["打开 Convai Web SDK 连接"]
    F --> G["语音和口型同步帧"]
    E --> H["逐帧更新"]
    G --> H
```

Convai 会将角色 ID 解析为身体清单，其中包含要加载的模型、动画片段以及模型所采用的绑定。角色的头像可以有自己发布的 Web 身体。如果没有，Convai 会提供为头像性别配置的默认身体；如果角色没有头像，则提供中性默认身体。如果两者都不存在，请求会失败并返回 `Character has no 3D embodiment configured.`

清单可以为多个绑定提供同一个身体。Convai Embody 会选择它能识别的第一个绑定。当前支持的绑定是 `convai-mha-1`，即 Unreal Engine MetaHuman 绑定。其骨骼和变形目标名称作为数据存储在绑定配置中，而不是写在代码里，因此要支持其他绑定，只需添加配置。

模型经过 Draco 压缩，因此加载器需要 Draco 解码器。随后，模型会缩放到站立的人体高度，并调整位置，使双脚落在地面上；接着开始播放待机动画片段，这样角色就不会一直保持在绑定姿势。

身体的动画片段以及应用传入的任何动画片段 `animations` 都会按名称加载；如果应用提供的动画片段与身体动画片段同名，则会替换后者。待机动画片段开始播放后，Convai Embody 会将动画片段的切换交由应用处理：说话时只会带动嘴部，不会切换身体动画片段，因此，若应用需要播放说话动画片段，应在客户端报告角色正在说话时切换到该片段。请参阅 [为角色添加自定义动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md).

清单通常由 Convai 提供，但应用也可以提供自己的解析器，返回其托管文件对应的清单。其余流程不变，因为身体仍会连接到角色的 Convai 会话。请参阅 [使用自己的 3D 模型](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/use-your-own-3d-model.md).

### 帧处理流程

每一帧中，让角色动起来的系统都会按固定顺序运行。这个顺序是设计的一部分：每个系统都会修改骨骼或变形目标，而后续系统会读取或覆盖这些数据。

| 顺序 | 系统                      | 在此处运行的原因                                                                                     |
| -- | ----------------------- | -------------------------------------------------------------------------------------------- |
| 1  | 视线复位                    | 视线系统会从不会被动画片段重写的骨骼上撤销上一帧的转动，以免转动不断累积。模型的缩放只在加载时测量一次。                                         |
| 2  | 动画片段，然后是落地校正            | 动画片段会为骨架摆姿势，随后将鞋底最低点放到地面上。                                                                   |
| 3  | 凝视                      | 视线系统会在动画片段设定的姿势上转动眼睛、颈部和躯干，因此要在动画片段之后运行。                                                     |
| 4  | 呼吸                      | 呼吸效果会叠加在动画片段设定的姿势上，因此要在其后运行，而且不会累积。                                                          |
| 5  | 口型同步，然后是眼部移动、眨眼，最后是面部法线 | 眨眼在唇形同步之后运行，因此会控制两个动画都会影响到的眼睑通道。最后，对于随面部形变移动、但未提供法线的模型，会重新计算表面法线；否则，闭合的眼睑会沿用睁眼时的法线受光，呈现黑色阴影。 |

视线会像真人一样跟随摄像机。眼睛跟随较小的移动，头部跟随较大的移动，只有摄像机长时间位于一侧时，躯干才会转向它。聆听时，角色偶尔会把视线移开。眼睛并非固定在头部上：当没有摄像机，或角色没有在关注摄像机时，眼睛会保持上次注视的世界方向，因此头部转动时，眼睛会在同一帧做出反向补偿；随后，眼睛会以约半秒的半衰期逐渐回到头部的朝向。呼吸时，胸部先于腰部起伏。眨眼是一段录制好的动作，而非开关：从 36 次录制的眨眼中选取一次，左右眼睑各自沿着曲线运动，并按录制时的 60 Hz 时间播放，因此无论帧率如何，呈现的动作都相同；眨眼间隔、半眨眼和双眨眼，以及静止时眼睑自然下垂的程度，都是 embody 自身的设定；眼睑也会随向下看的视线而变化。

### 身体的着色方式

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-4c03e6bbbd731630c93e714844291966f7c15b69%2Fsample-avatars-busts.jpg?alt=media" alt="Bust shots of four sample avatars, two women and two men, each lit by the same key light from the left with a soft shadow across the neck and under the chin"><figcaption><p>同一场景中的四种身体：皮肤在阴影中仍保持原有色调，头发呈现出发丝质感，眼睛能捕捉光线，布料则保持哑光。</p></figcaption></figure>

加载时，身体的材质会重新着色，使其无论面对何种灯光，都能像皮肤和头发一样响应场景中的光照。皮肤会变为基于物理的电介质材质，阴影边缘的光线会柔和地延展过去，并呈现毛孔细节；头发以覆盖率方式绘制，靠近头皮处颜色较深，带有微弱的发色高光，并在轮廓处淡出；眼睛会呈现经过校准的虹膜、深色瞳孔和眼中高光；牙齿则由周围的口腔区域进行照明和着色。如果角色的清单中写有 `gender: 'male'` 就会呈现男性外观：睫毛采用纹理自身的 alpha 值；皮肤反应更紧致、粉色更少、毛孔更多；并采用 `steady` 静止表情。系统不会更改你的灯光； `ConvaiCharacter`自带的画布会添加一个跟随摄像机的肖像绑定， `createPortraitRig` 则会为普通的 three.js 场景提供相同的绑定。请参阅 `surfaces`, `faceMaterials` 和 `mouth` ，详见 [createCharacter 参考文档](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md).

### 唇形同步时序

Convai 会提前发送嘴部帧，并按挂钟时间进行调度；语音本身通过 WebRTC 播放，由 WebRTC 缓冲并调整播放速度。因此，Convai Embody 会根据语音自身的时钟来驱动嘴部动作，该时钟从音轨读取：

* 回复的嘴部动作会在语音首次变得可听时开始，并与流中的第一个嘴部动作同步，因此无论回复以元音还是闭唇动作开头，每次回复都会有相同的轻微提前量。
* 语音暂停时，嘴部会保持当前状态；语音分块之间的停顿（有些语音会分段送达）不会导致跳过下一块对应的嘴部形状；间隔一段时间后到达的帧会从其对应的声音开始播放，而不会突然成批播放。
* 如果语音仍在播放，但流中暂时没有数据，嘴部会继续根据语音音量运动，直到帧恢复。语音绝不会在面部静止时播放。
* 回复结束时，嘴部会平滑地闭合一次。

### 减少动态效果

当用户的系统通过 `prefers-reduced-motion` 媒体查询请求减少动态效果时，Convai Embody 会减弱呼吸等叠加的动作层，并抑制移开视线和细微的眼部动作。唇形同步和动画片段不会减弱，因为它们承载着含义：让嘴部动作变得不明显，虽然不会让角色看起来更平静，却会增加理解角色的难度。

### 环境

每个版本的 `@convai/embody` 都会连接到一个 Convai 环境，该环境由默认的 `baseUrl`设置。角色 ID 仅属于一个环境，不会在其他环境中通用。来自其他环境的 ID 会返回“未找到”错误，看起来像是权限问题，实际原因却是环境不匹配。

### 相关概念

{% content-ref url="/pages/29f9aac19fcc2f8cd08338eeb8c9340da2c133cf" %}
[使用 blendshape 驱动面部动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/lipsync-and-blendshape.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/how-convai-embody-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
