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

# 口型同步使用示例

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

### 添加与覆盖混合

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

#### 在静止动画上叠加口型同步

使用 `ApplyMode = Add` 当身体动画或静止动画已经驱动了一些面部曲线时——例如轻微呼吸动画会让下巴稍微移动。Convai 的数值会叠加到源姿态已包含的内容上，因此两种动画共存。

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

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

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

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

使用 `ApplyMode = Override` 当 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 面部同步` 节点位于身体层节点之后、最终输出之前。使用 `ApplyMode = Add` 以便保留任何身体层面部曲线（例如眨眼轨道）。

AnimGraph 顺序应为：

1. 身体动画节点（生成包含身体和静止面部曲线的源姿态）
2. `Convai 面部同步` 节点（读取源姿态，添加 Convai 曲线）
3. 输出姿势

这个顺序可确保静止眨眼和其他身体层面部动画在 Convai 口型同步的同时得以保留。

### 自定义 blendshape 重映射

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

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

在 `BlendshapeMapping` 表中，添加一条条目：

| 键（`FName`)                 | `TargetNames`                            | `乘数`  | `偏移`  |
| -------------------------- | ---------------------------------------- | ----- | ----- |
| `CTRL_expressions_jawOpen` | `["InstructorJaw_L", "InstructorJaw_R"]` | `1.0` | `0.0` |

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

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

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

| 键（`FName`)                 | `TargetNames`                  | `乘数`  | `偏移`  |
| -------------------------- | ------------------------------ | ----- | ----- |
| `CTRL_expressions_jawOpen` | `["CTRL_expressions_jawOpen"]` | `0.6` | `0.0` |

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

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

若要完全阻止 Convai 驱动某条特定曲线——例如为了保持眼睛完全睁开，不受语音数据影响——请添加一条带有 `UseOverrideValue = true`:

| 键（`FName`)                   | `TargetNames`                    | `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 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-unreal-engine-plugin/features/lip-sync/lip-sync-usage-examples.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.