> 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 音频输出连接到角色的面部 BlendShape，同步口部动作与语音，并调整播放延迟。

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

### 工作原理

Convai 发送语音音频时，也会以角色使用的传输格式（ARKit、MetaHuman 或 CC4 Extended）流式传输一系列 Blend Shape 帧。SDK 会缓冲并插值这些帧，应用可选的平滑处理，然后在每一帧将结果写入角色的 `SkinnedMeshRenderer` 。

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

如果同一角色还挂载了另一个驱动面部 Blend Shape 的模块（例如 Emotion 控制器），Convai 会在将结果写入网格之前，在内部将口型同步输出与该模块的输出进行合成，而不是让两个模块分别写入。默认配置会在角色说话时，几乎完全由 `ConvaiLipSyncComponent` 控制嘴部。如果角色上没有其他面部输出模块， `ConvaiLipSyncComponent` 则会如上所示，直接写入目标网格。

### 快速设置

{% stepper %}
{% step %}

#### 添加组件

将 `ConvaiLipSyncComponent` 添加到与 `ConvaiCharacter` 相同的 GameObject 上（或添加到任意子 GameObject 上）。
{% endstep %}

{% step %}

#### 设置配置文件 ID

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

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

{% step %}

#### 指定目标网格

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

{% step %}

#### 进入 Play 模式

将 **Mapping** 留空 — SDK 会根据所选配置文件自动选择匹配的内置映射。进入播放模式并让角色说话。

角色的嘴部会与语音输出同步动作。

{% hint style="warning" %}
如果嘴部没有动作，请确认你的 `SkinnedMeshRenderer` Blend Shape 名称是否符合所选配置文件的命名约定。ARKit 使用 camelCase 名称（例如， `jawOpen`, `mouthSmileLeft`）。MetaHuman 使用 `CTRL_expressions_` 前缀。如果你的绑定使用了不同的名称，请使用自定义映射 — 请参阅 [配置文件与映射](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync/profiles-and-mappings.md).
{% endhint %}
{% endstep %}
{% endstepper %}

### 内置配置文件

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

| 配置文件      | 锁定的配置文件 ID     | Blendshape | 常见角色来源                            |
| --------- | -------------- | ---------- | --------------------------------- |
| ARKit     | `arkit`        | 61         | 使用 Apple 绑定的角色，以及部分自定义绑定          |
| MetaHuman | `metahuman`    | 251        | 导出到 Unity 的 Unreal MetaHuman      |
| CC4 扩展    | `cc4_extended` | 170        | Reallusion Character Creator 4 角色 |

如果角色绑定使用了非标准的 blendshape 名称，请创建自定义映射，将 SDK 的输出通道对应到绑定中实际使用的名称。

{% content-ref url="/pages/60064eabc10799fef78f5bfba5ab16e07ed98015" %}
[配置文件与映射](https://docs.convai.com/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 所需的秒数                                             |
| `_settleDuration`  | `0.35` | 0.1–1.0  | 角色说完最后一个词后，嘴部恢复静止所需的秒数；此过程会延续动画原有的运动，而不是直接截断。请参阅 [响应如何结束](#how-a-response-ends). |
| `_fadeInDuration`  | `0.1`  | 0–0.5    | 播放开始时，从播放前的姿势过渡到首批采样帧所需的秒数，可消除响应开始时首帧的跳变（`0` 禁用该效果）                              |
| `_timeOffset`      | `0.0`  | -0.5–0.5 | 相对于音频调整播放时间（负值 = 提前）                                                             |

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

| 字段                          | 默认值        | 范围       | 说明                           |
| --------------------------- | ---------- | -------- | ---------------------------- |
| `_latencyMode`              | `Balanced` | —        | 控制缓冲深度与响应速度之间权衡的预设           |
| `_maxBufferedSeconds`       | `3.0`      | 1–10     | 环形缓冲区容量（秒）                   |
| `_minResumeHeadroomSeconds` | `0.12`     | 0.05–0.3 | 缓冲区耗尽后重新填充的阈值                |
| `_deliverChunksAhead`       | `false`    | —        | 索引化 NeuroSync 分块的预览功能（需主动启用） |

**延迟模式选项：**

| 模式                | 适用场景                  |
| ----------------- | --------------------- |
| `Balanced`        | 默认。推荐用于大多数部署          |
| `UltraLowLatency` | 延迟极低；在连接不稳定时容易出现缓冲区耗尽 |
| `NetworkSafe`     | 缓冲量大；最适合不可靠或高延迟网络     |
| `Custom`          | 解锁对上述缓冲区字段的手动控制       |

### 响应结束时

响应正常结束时，嘴部会在 **回归静止时长** (`0.35` 秒（默认）内恢复静止，而不是突然闭合或保持最后的形状。闭合动作会延续最后几帧已有的运动趋势——如果下颌仍在抬起，就会平滑地落下，不会出现可见的顿挫；如果下颌已经在闭合，就会继续闭合。这与 **淡出时长**不同；响应被中断或取消、而非自行结束时，会使用更快的截断方式。

如果你直接驱动 `LipSyncPlaybackEngine` ，而不是通过 `ConvaiLipSyncComponent`，请调用 `SettleToRest()` ，以便在自己的代码中触发相同的回归静止效果；并读取 `IsSettling` ，以检查当前淡出是回归静止过程，而非定时截断。

### 提前传送分块预览

**提前传送分块（预览）** 启用后，SDK 可以在索引化 NeuroSync 分块到达播放位置之前请求它们。普通项目请保持禁用。只有在测试已使用 `ConvaiLipSyncComponent`.

的角色的提前传送分块预览路径时，才启用此选项。 `_deliverChunksAhead` 启用后，SDK 会在房间连接的口型同步配置中发送 `deliver_chunks_ahead=true` 。默认请求不包含此字段，因此除非启用预览选项，否则现有的口型同步行为不会改变。

SDK 会根据帧索引缓冲提前到达的分块，并等待响应开头的帧连续就绪后，才开始将它们传送给播放引擎。视觉输出仍会等待角色音频播放信号，因此嘴部不会在可听语音开始前就开始移动。如果 Convai 取消当前 NeuroSync 时间线，或者角色回合因中断而结束，SDK 会在下一次响应前清除已缓冲的嘴部帧。

### 使用示例

#### 示例 1：ARKit 角色

**场景：** 某企业培训模拟项目使用了一个采用 Apple ARKit 混合形状绑定的角色。

**设置：**

1. 将 `ConvaiLipSyncComponent` 添加到 NPC GameObject（与 `ConvaiCharacter`).
2. 相同） `将` 设置为 `arkit`.
3. 在 **目标网格** 列表中，添加 `SkinnedMeshRenderer` 从虚拟形象的头部网格中获取。
4. 留空 `_mapping` 留空——内置的 ARKit 自动映射支持标准的驼峰式 ARKit 混合形状名称（`jawOpen`, `mouthSmileLeft`等）。

**预期结果：** 在对话过程中，虚拟形象的嘴部、嘴唇和下颌会与角色的语音同步动画。每次回复结束后，嘴部都会平滑地恢复静止状态（`_settleDuration` 默认值为 0.35 秒）。

#### 示例 2：MetaHuman 角色

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

**设置：**

1. 将 `ConvaiLipSyncComponent` 添加到 NPC 的 GameObject。
2. 将 `_lockedProfileId` 设为 `metahuman`.
3. 在 **目标网格** 列表中，添加 MetaHuman 头部和牙齿网格上的所有 `SkinnedMeshRenderer` 组件——MetaHuman 会将这些网格拆分到多个渲染器中。
4. 将 `_mapping` 留空——内置的 MetaHuman 映射适用于以 `CTRL_expressions_` 为前缀的混合形状。
5. 将 `_smoothingFactor` 调高 `0.7` ，以便在高多边形数的绑定模型上实现更流畅的动画。

**预期结果：** 所有面部区域都会协同动画——嘴唇、下颌、脸颊和舌头形状——从而呈现高度逼真的嘴部动作。平滑处理可减少高分辨率网格上可见的逐帧抖动。

### 后续步骤

配置好口型同步后，选择玩家与角色交谈的方式。

{% content-ref url="/pages/26b817b7abe1379d0e73ce3dc01f1e053df39b56" %}
[配置对话输入模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md)
{% endcontent-ref %}

也可以浏览“功能”部分，为角色添加动作、情绪、长期记忆或视觉功能。

{% content-ref url="/pages/8c561f7c198c46628ed5818040fdaa9af3397caf" %}
[功能](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features.md)
{% endcontent-ref %}

查看“核心概念”，深入了解会话生命周期和事件系统。

{% content-ref url="/pages/b20dffbec401e06e9fe4168f409ab42a87fa327b" %}
[核心概念](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts.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/convai-unity-sdk/getting-started/add-lip-sync.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.
