> 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-unreal-engine-plugin/features/lip-sync/lip-sync-usage-examples.md).

# 口型同步使用示例

为常见场景配置口型同步：叠加与覆盖混合、平滑调优、与身体动画混合，以及将 blendshape 重新映射到自定义骨骼。

这些示例涵盖最常见的 `FAnimNode_ConvaiFaceSync` 配置。每个示例都描述了场景、需要更改的节点或组件设置，以及预期结果。

### 添加与覆盖混合

当多个动画系统都向同一组面部曲线写入时——例如，待机动画和 Convai 的口型同步——你需要决定 Convai 的数值如何与现有动画组合。

#### 在待机动画之上叠加口型同步

使用 `ApplyMode = 添加` 当身体或待机动画已经驱动了一些面部曲线时——例如，一个轻微抬动下颌的细微呼吸动画。Convai 的数值会叠加到源姿势已包含的内容之上，因此两种动画可以共存。

在 AnimGraph 节点 **Details** 面板：

| 属性          | 值    |
| ----------- | ---- |
| `ApplyMode` | `添加` |

源姿势动画保留其面部曲线，而 Convai 的数值会叠加在其上。

#### 让 Convai 成为唯一驱动

使用 `ApplyMode = 覆盖` 当 Convai 应独占所有动画曲线，而任何待机面部动画都会产生冲突时——例如，一个角色的待机动画使用眉部曲线，而这些曲线会与来自 Convai 的情绪数据冲突。

在 AnimGraph 节点 **Details** 面板：

| 属性          | 值    |
| ----------- | ---- |
| `ApplyMode` | `覆盖` |

源姿势曲线会被 Convai 帧值完全替换。

### 调整平滑

#### 平滑口型运动以减少抖动

语音 blendshape 数据会产生快速的逐帧变化，在屏幕上表现为抖动，尤其是在下半张脸。启用下半脸平滑，并将速度设置为适中，以使运动更平稳，同时不产生明显延迟。

在 AnimGraph 节点 **Details** 面板：

| 属性                          | 值      |
| --------------------------- | ------ |
| `bEnableLowerFaceSmoothing` | `true` |
| `LowerFaceSmoothingSpeed`   | `0.4`  |

数值为 `0.4` 可获得更平滑的口型运动，同时仍保持响应性。降低到 `0.1` 可获得更强的平滑效果，但延迟更大；提高到 `1.0` 可获得更快的响应和更少的平滑。默认值 `1.0` 为即时，不应用任何平滑。

#### 抑制眉部和眼部运动

语音数据有时会包含与角色情绪不符或显得不自然的眉部和眼睑运动。降低 `UpperFaceAlpha` 可在不完全禁用上半脸曲线的情况下，降低其贡献。

在 AnimGraph 节点 **Details** 面板：

| 属性               | 值     |
| ---------------- | ----- |
| `UpperFaceAlpha` | `0.2` |

设置 `UpperFaceAlpha` 为 `0.0` 可完全抑制上半脸 blendshape，同时保留完整的口型动画。

### 与身体动画混合

#### 保留身体动画曲线

当 Animation Blueprint 将身体和面部层级串联在一起时，请确保 `Convai Face Sync` 节点放在身体层节点之后、最终输出之前。使用 `ApplyMode = 添加` 以便保留任何身体层面的面部曲线（例如眨眼轨道）。

AnimGraph 的顺序应为：

1. 身体动画节点（生成包含身体和待机面部曲线的源姿势）
2. `Convai Face Sync` 节点（读取源姿势，添加 Convai 曲线）
3. 输出姿势

此顺序可确保待机眨眼和其他身体层面的面部动画与 Convai 口型同步同时保留。

### 自定义 blendshape 重映射

#### 将一条 Convai 曲线映射到两条骨骼曲线

某些自定义骨骼会将单个口部运动拆分为左右两个目标曲线。例如，MetaHuman 源曲线 `CTRL_expressions_jawOpen` 来自 Convai，可能需要驱动自定义骨骼上的两个用户定义目标曲线。

在 `BlendshapeMapping` 在 AnimGraph 节点的

| 表中，添加一项：`FName`)           | `键（`                                     | `乘数`  | `偏移`  |
| -------------------------- | ---------------------------------------- | ----- | ----- |
| `CTRL_expressions_jawOpen` | `["InstructorJaw_L", "InstructorJaw_R"]` | `1.0` | `0.0` |

两个自定义目标曲线都会接收到与源 `CTRL_expressions_jawOpen` 曲线相同的值。

#### 将曲线缩小以防止裁切

如果某条特定曲线在某个网格上造成过多形变，请添加一个带有减小 `乘数`:

| 表中，添加一项：`FName`)           | `键（`                           | `乘数`  | `偏移`  |
| -------------------------- | ------------------------------ | ----- | ----- |
| `CTRL_expressions_jawOpen` | `["CTRL_expressions_jawOpen"]` | `0.6` | `0.0` |

目标曲线将接收 `60%` 的输入值。 `GlobalMultiplier` 仍然会生效，除非在 `IgnoreGlobalModifiers` 设置为 `true` 上将其设置为启用。

#### 将曲线固定为一个固定值

若要完全阻止某条特定曲线被 Convai 驱动——例如让眼睛始终完全睁开，无论语音数据如何——请添加一项带有 `UseOverrideValue = true`:

| 表中，添加一项：`FName`)             | `键（`                             | `UseOverrideValue` | `OverrideValue` |
| ---------------------------- | -------------------------------- | ------------------ | --------------- |
| `CTRL_expressions_eyeBlinkL` | `["CTRL_expressions_eyeBlinkL"]` | `true`             | `0.0`           |

该曲线将保持在 `0.0` ，不受传入数据影响。

### 录制并回放口型同步序列

#### 捕获用于过场动画播放的响应

使用录制 API 在对话期间捕获实时口型同步序列，并在之后回放——例如用于非交互式过场动画或预热的响应缓存。

录制 API 仅支持 C++。 `StartRecordingLipSync()`, `FinishRecordingLipSync()`, `PlayRecordedLipSync()`, `IsPlaying()`，以及 `GetCurrentFrame()` 是 `UConvaiFaceSyncComponent` 上的纯 C++ 方法，且没有 `UFUNCTION` 修饰符。

```cpp
// 伪代码
UConvaiFaceSyncComponent* FaceSync = MyCharacter->FindComponentByClass<UConvaiFaceSyncComponent>();

// 1. 在说话开始前或开始时开始录制。
FaceSync->StartRecordingLipSync();

// 2. 角色说话——帧会自动捕获。

// 3. 在该轮结束时停止录制并存储序列。
FAnimationSequenceBP CachedSequence = FaceSync->FinishRecordingLipSync();

// 4. 在需要时回放该序列（例如在过场触发时）。
//    参数：录制序列，起始帧（0 = 开始），
//    结束帧（-1 = 结束），覆盖时长（0.0 = 使用录制时长）。
FaceSync->PlayRecordedLipSync(CachedSequence, 0, -1, 0.0f);
```

{% hint style="info" %}
使用 `IsPlaying()` 用于轮询回放是否处于活动状态，以及 `GetCurrentFrame()` 用于读取实时 blendshape 值，以供音频驱动效果或口型同步调试覆盖层等辅助系统使用。
{% endhint %}

### 下一步

{% content-ref url="/pages/ed19695d8a46eb28447110735f1f0dfe84079492" %}
[Face Sync AnimGraph 节点参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/face-sync-animgraph-node-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/37d2872ffdb903e0d2cf86a4c12dfd99660c927f" %}
[录制并回放口型同步](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/record-and-replay-lip-sync.md)
{% endcontent-ref %}

{% content-ref url="/pages/b0b44be9f2ee8ca031b08c9677450b5f826a9c8c" %}
[排查口型同步问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/troubleshoot-lip-sync.md)
{% endcontent-ref %}

{% content-ref url="/pages/713990439742181b882d6f2ca1521bb051a162be" %}
[口型同步的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/how-lip-sync-works.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-unreal-engine-plugin/features/lip-sync/lip-sync-usage-examples.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.