> 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]
```

如果同一个角色还有另一个驱动面部 blendshape 的模块——例如情绪控制器——Convai 会在内部将口型同步输出与该模块的输出进行合成，然后再写入网格，而不是让两者独立写入。默认的平衡会几乎把嘴部完全交给 `ConvaiLipSyncComponent` ，只要角色在说话。若角色没有其他面部输出模块， `ConvaiLipSyncComponent` 会像上面所示那样直接写入目标网格。

### 快速设置

{% stepper %}
{% step %}

#### 添加组件

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

{% step %}

#### 设置配置文件 ID

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

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

{% step %}

#### 分配目标网格

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

{% step %}

#### 进入播放模式

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

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

{% hint style="warning" %}
如果嘴巴没有动，请确认您的 `SkinnedMeshRenderer` blendshape 名称与所选配置文件预期的命名约定一致。ARKit 使用驼峰式名称（例如 `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 格式相匹配的配置文件。

| 配置文件         | 锁定的配置文件 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 分块的预览性启用选项 |

**延迟模式选项：**

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

### 提前分块传送预览

**提前分块传送（预览）** 使 SDK 能够在其播放位置之前请求已索引的 NeuroSync 分块。普通项目请保持禁用。仅当您正在测试某个已使用 `ConvaiLipSyncComponent`.

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

SDK 会按帧索引提前缓冲分块，并等待响应开始时帧连续后，才开始将其送入播放引擎。视觉输出仍会等待角色音频播放信号，因此嘴巴不会在可听到语音开始之前移动。如果 Convai 取消当前 NeuroSync 时间线，或由于中断导致角色轮次结束，SDK 会在下一次响应前清除已缓冲的嘴部帧。

### 使用示例

#### 示例 1：ARKit 角色

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

**设置：**

1. 添加 `ConvaiLipSyncComponent` 到 NPC GameObject（与 `ConvaiCharacter`).
2. 将 `_lockedProfileId` 到 `arkit`.
3. 在 **目标网格** 列表中，添加 `SkinnedMeshRenderer` 来自头像头部网格的
4. 将 `_mapping` 留空——随附的 ARKit 自动映射覆盖标准驼峰式 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, 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.