> 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，同步口部动作与语音，并调整播放延迟。

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

如果同一角色还使用另一个驱动面部 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 会自动为所选配置文件选择匹配的内置映射。进入播放模式并对角色说话。

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

{% 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     | 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" %}
[配置文件与映射](/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`              | `平衡`    | —        | 控制缓冲深度与响应性之间平衡的预设     |
| `_maxBufferedSeconds`       | `3.0`   | 1–10     | 环形缓冲区容量（秒）            |
| `_minResumeHeadroomSeconds` | `0.12`  | 0.05–0.3 | 饥饿后缓冲区重新填充阈值          |
| `_deliverChunksAhead`       | `false` | —        | 索引 NeuroSync 分块的预览可选项 |

**延迟模式选项：**

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

### 响应如何结束

当响应正常结束时，嘴部会在 **收束时长** (`0.35` 秒内恢复到静止状态，而不是突然闭合或保持最后的形状。闭合会延续最后几帧已经做出的动作——仍在上升的下颌会平滑回落，没有可见的折角，而已经在闭合的嘴会继续闭合。这与 **淡出时长**不同，后者是在响应被中断或取消而不是自然结束时使用的更快切断。

如果您直接驱动 `LipSyncPlaybackEngine` 而不是通过 `ConvaiLipSyncComponent`的情况下推送一个值，请调用 `SettleToRest()` ，可以从您自己的代码中触发同样的收束，并读取 `IsSettling` 来检查当前淡出是否是收束，而不是定时切断。

### 提前分块传递预览

**提前分块传递（预览）** 使 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`，等等）。

**预期结果：** 在对话期间，头像的嘴、唇和下颌会与角色语音同步动画。每次响应结束后，嘴部会平滑地恢复到静止状态（`_settleDuration` = 0.35 秒默认）。

#### 示例 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/26b817b7abe1379d0e73ce3dc01f1e053df39b56" %}
[配置对话输入模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md)
{% endcontent-ref %}

或者浏览 Features 部分，为你的角色添加 Actions、Emotion、Long-Term Memory 或 Vision。

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

查看 Core Concepts，以更深入理解会话生命周期和事件系统。

{% content-ref url="/pages/b20dffbec401e06e9fe4168f409ab42a87fa327b" %}
[核心概念](/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.