> 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/convai-unity-sdk/getting-started/add-lip-sync.md).

# 添加口型同步

Unity 版 Convai SDK 包含一个实时口型同步系统，可驱动 `SkinnedMeshRenderer` 与角色语音音频同步的 blendshape。它支持三种行业标准的 blendshape 格式，并自动处理播放缓冲、平滑和淡出。

### 工作原理

当 Convai 发送语音音频时，它还会以角色的传输格式（ARKit、MetaHuman 或 CC4 Extended）流式传输一系列 blendshape 帧。SDK 会对这些帧进行缓冲和插值，应用可选平滑，并将结果写入角色的 `SkinnedMeshRenderer` 每一帧。

```mermaid
graph LR
    A[Convai：语音 + blendshape 帧] --> B[ConvaiLipSyncComponent]
    B --> C[帧缓冲 + 插值]
    C --> D[平滑]
    D --> E[SkinnedMeshRenderer 的 blendshape]
```

### 快速设置

{% stepper %}
{% step %}

#### 将组件添加到

添加 `ConvaiLipSyncComponent` 相同的 GameObject 上，作为你的 `ConvaiCharacter` （或任意子 GameObject）。
{% endstep %}

{% step %}

#### 设置 profile ID

在 Inspector 中，将 **Locked Profile ID** 设置为你角色使用的传输格式：

* `arkit` — Apple ARKit（61 个 blendshape）
* `metahuman` — Unreal MetaHuman（251 个 blendshape）
* `cc4_extended` — Character Creator 4 Extended（170 个 blendshape）
  {% endstep %}

{% step %}

#### 分配目标网格

在 **Target Meshes** 列表中，添加所有 `SkinnedMeshRenderer` 具有面部 blendshape 的组件。
{% endstep %}

{% step %}

#### 进入 Play Mode

留空 **Mapping** 为空 — SDK 会为所选 profile 自动选择匹配的内置映射。进入 Play Mode 并对角色说话。

角色的嘴会与其语音输出同步移动。

{% hint style="warning" %}
如果嘴没有移动，请确认你的 `SkinnedMeshRenderer` blendshape 名称与所选 profile 的预期命名约定一致。ARKit 使用 camelCase 名称（例如， `jawOpen`, `mouthSmileLeft`）。MetaHuman 使用 `CTRL_expressions_` 前缀。如果你的骨骼绑定使用不同的名称，请使用自定义映射——参见 [Profiles and mappings](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync/profiles-and-mappings.md).
{% endhint %}
{% endstep %}
{% endstepper %}

### 内置 profile

选择与你角色绑定时所使用的 blendshape 格式相匹配的 profile。

| Profile      | Locked Profile ID | Blendshapes | 典型角色来源                            |
| ------------ | ----------------- | ----------- | --------------------------------- |
| ARKit        | `arkit`           | 61          | Apple 绑定的角色、部分自定义骨骼               |
| MetaHuman    | `metahuman`       | 251         | 导出到 Unity 的 Unreal MetaHuman      |
| CC4 Extended | `cc4_extended`    | 170         | Reallusion Character Creator 4 角色 |

如果你的角色使用了非标准的 blendshape 名称，请创建自定义映射，将 SDK 的输出通道路由到你骨骼的实际名称。

{% content-ref url="/pages/60064eabc10799fef78f5bfba5ab16e07ed98015" %}
[配置文件与映射](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync/profiles-and-mappings.md)
{% endcontent-ref %}

### 播放设置

**核心设置：**

| 字段                 | 默认值     | 描述                                                  |
| ------------------ | ------- | --------------------------------------------------- |
| `_lockedProfileId` | `arkit` | SDK 流式传输的传输格式（`arkit`, `metahuman`, `cc4_extended`) |
| `_mapping`         | *（无）*   | 可选的自定义映射资源（留空可使用内置自动映射）                             |
| `_targetMeshes`    | *（空列表）* | `SkinnedMeshRenderer` 用于写入 blendshape 的组件           |

**播放与行为：**

| 字段                 | 默认值   | 范围       | 描述                                                 |
| ------------------ | ----- | -------- | -------------------------------------------------- |
| `_smoothingFactor` | `0.5` | 0–0.9    | 每帧指数平滑（更高 = 更平滑但更慢）                                |
| `_fadeOutDuration` | `0.2` | 0.05–2.0 | 音频结束后将所有 blendshape 淡出到 0 所需的秒数                    |
| `_fadeInDuration`  | `0.1` | 0–0.5    | 在播放开始时，从播放前姿态过渡到首批采样帧所需的秒数，以消除响应开始时的首帧突变（`0` 会禁用它） |
| `_timeOffset`      | `0.0` | -0.5–0.5 | 相对于音频偏移播放时间（负值 = 更早）                               |

**流式传输与延迟：**

| 字段                          | 默认值     | 范围       | 描述                          |
| --------------------------- | ------- | -------- | --------------------------- |
| `_latencyMode`              | `均衡`    | ——       | 控制缓冲深度与响应速度的预设              |
| `_maxBufferedSeconds`       | `3.0`   | 1–10     | 环形缓冲区容量（秒）                  |
| `_minResumeHeadroomSeconds` | `0.12`  | 0.05–0.3 | 发生缓冲耗尽后重新填充的阈值              |
| `_deliverChunksAhead`       | `false` | ——       | 索引化 NeuroSync chunk 的预览参与开关 |

**延迟模式选项：**

| 模式     | 使用场景                 |
| ------ | -------------------- |
| `均衡`   | 默认。推荐用于大多数部署         |
| `超低延迟` | 延迟极小；在不稳定连接上容易出现缓冲耗尽 |
| `网络安全` | 高缓冲；最适合不可靠或高延迟网络     |
| `自定义`  | 解锁对上方缓冲字段的手动控制       |

### 提前 chunk 交付预览

**Ahead Chunk Delivery（预览）** 允许 SDK 在其播放位置之前请求索引化的 NeuroSync chunk。正常项目请保持禁用。仅当你正在测试该预览 ahead-chunk 路径，并且角色已经使用 `ConvaiLipSyncComponent`.

当 `_deliverChunksAhead` 启用时，SDK 会发送 `deliver_chunks_ahead=true` 到房间连接的口型同步配置中。默认请求不包含此字段，因此，除非你开启预览选项，否则现有口型同步行为不会改变。

SDK 会按帧索引缓冲 ahead chunk，并等待从响应开始帧起保持连续后，才开始将它们传递给播放引擎。视觉输出仍会等待角色音频播放信号，因此嘴不会在可听语音开始前移动。如果 Convai 取消当前 NeuroSync 时间线，或因中断导致角色回合结束，SDK 会在下一次响应前清空已缓冲的嘴部帧。

### 使用示例

#### 示例 1：ARKit 角色

**场景：** 一个企业培训模拟使用了一个绑定 Apple ARKit blendshape 的角色。

**设置：**

1. 添加 `ConvaiLipSyncComponent` 到 NPC GameObject（与 `ConvaiCharacter`).
2. 将 `_lockedProfileId` 设置为 `arkit`.
3. 在 **Target Meshes** 列表中，添加 `SkinnedMeshRenderer` 来自头像头部网格的。
4. 留空 `_mapping` 为空 — 内置的 ARKit 自动映射覆盖标准的 camelCase ARKit blendshape 名称（`jawOpen`, `mouthSmileLeft`，等等）。

**预期结果：** 在对话过程中，头像的嘴、嘴唇和下颌会与角色的语音同步动画。每次响应结束后，blendshape 会平滑地恢复到中性状态（`_fadeOutDuration` = 0.2 秒默认值）。

#### 示例 2：MetaHuman 角色

**场景：** 一个高保真的医疗模拟使用了一个导出到 Unity 的 Unreal MetaHuman 角色。

**设置：**

1. 添加 `ConvaiLipSyncComponent` 到 NPC GameObject。
2. 将 `_lockedProfileId` 设置为 `metahuman`.
3. 在 **Target Meshes** 列表中，添加所有 `SkinnedMeshRenderer` MetaHuman 头部和牙齿网格上的组件——MetaHuman 将这些拆分为多个渲染器。
4. 留空 `_mapping` 为空 — 内置的 MetaHuman 映射针对 `CTRL_expressions_` 带前缀的 blendshape。
5. 提高 `_smoothingFactor` 设置为 `0.7` 可让高面数骨骼上的动画更流畅。

**预期结果：** 所有面部区域会一起动画——嘴唇、下颌、脸颊和舌头形状——从而产生高度逼真的口型运动。平滑可减少高分辨率网格上可见的逐帧抖动。

### 下一步

配置好口型同步后，请验证你的完整设置。

{% content-ref url="/pages/21a0b0c11649e9125ef5195167e66c3a2caaadf1" %}
[验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.