> 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).

# 添加口型同步

Convai 的 Unity 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` 到与你的 `ConvaiCharacter` 相同的 GameObject 上（或添加到任意子 GameObject）。
{% endstep %}

{% step %}

#### 设置配置文件 ID

在 Inspector 中，将 **锁定配置文件 ID** 为角色所使用的传输格式：

* `arkit` — Apple ARKit（61 个 blendshape）
* `metahuman` — Unreal MetaHuman（275+ 个 blendshape）
* `cc4extended` — Character Creator 4 Extended（240+ 个 blendshape）
  {% endstep %}

{% step %}

#### 分配目标网格

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

{% step %}

#### 进入播放模式

留空 **映射** 留空——SDK 会为所选配置文件自动选择匹配的随附映射。进入 Play 模式并对角色说话。

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

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

### 随附配置文件

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

| Profile   | 锁定配置文件 ID     | Blendshape | 典型角色来源                            |
| --------- | ------------- | ---------- | --------------------------------- |
| ARKit     | `arkit`       | 61         | 使用 Apple 绑定的角色，一些自定义骨骼            |
| MetaHuman | `metahuman`   | 275+       | 导出到 Unity 的 Unreal MetaHuman      |
| CC4 扩展    | `cc4extended` | 240+       | 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`, `cc4extended`) |
| `_mapping`         | *（无）*   | 可选的自定义映射资源（留空则使用随附的自动映射）                           |
| `_targetMeshes`    | *（空列表）* | `SkinnedMeshRenderer` 用于写入 blendshape 的组件          |

**播放与行为：**

| 字段                 | 默认值   | 范围       | 说明                              |
| ------------------ | ----- | -------- | ------------------------------- |
| `_smoothingFactor` | `0.5` | 0–0.9    | 每帧指数平滑（值越高越平滑，但速度越慢）            |
| `_fadeOutDuration` | `0.2` | 0.05–2.0 | 音频结束后将所有 blendshape 淡出到 0 所需的秒数 |
| `_timeOffset`      | `0.0` | -0.5–0.5 | 相对于音频偏移播放时间（负值 = 更早）            |

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

| 字段                          | 默认值    | 范围       | 说明                 |
| --------------------------- | ------ | -------- | ------------------ |
| `_latencyMode`              | `平衡`   | —        | 控制缓冲深度与响应速度之间权衡的预设 |
| `_maxBufferedSeconds`       | `3.0`  | 1–10     | 环形缓冲区容量（秒）         |
| `_minResumeHeadroomSeconds` | `0.12` | 0.05–0.3 | 发生欠载后缓冲区重新填充的阈值    |

**延迟模式选项：**

| 模式                | 使用场景               |
| ----------------- | ------------------ |
| `平衡`              | 默认。推荐用于大多数部署       |
| `UltraLowLatency` | 延迟极低；在不稳定连接下容易发生欠载 |
| `NetworkSafe`     | 高缓冲；最适合不稳定或高延迟网络   |
| `自定义`             | 可手动控制上方的缓冲字段       |

### 使用示例

#### 示例 1：ARKit 角色

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

**设置：**

1. 添加 `ConvaiLipSyncComponent` 到 NPC GameObject（与 `ConvaiCharacter`).
2. 设置 `_lockedProfileId` 到 `arkit`.
3. 在 **目标网格** 列表中，添加 `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. 在 **目标网格** 列表中，添加所有 `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:

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

The question should be specific, self-contained, and written in natural language.
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.