> 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/face-sync-component-reference.md).

# Face Sync 组件参考

Convai Face Sync 组件的属性参考，以及全部六种口型同步模式值，并提供 MetaHuman、CC4、CC5 和自定义骨骼的绑定兼容性指导。

`UConvaiFaceSyncComponent` (Blueprint 显示名称 **"Convai 面部同步"**) 是一个场景组件，它接收来自 Convai 的面部动画数据，将其缓冲，并在每个 Tick 中暴露当前帧。

将其添加到与以下对象相同的 Actor 中 `UConvaiChatbotComponent`。 `Convai Face Sync` AnimGraph 节点通过聊天机器人组件读取面部数据，该组件会委托给附加的 `UConvaiFaceSyncComponent`.

### 属性

| 属性                     | 类型               | 默认       | 说明                                                                                                                |
| ---------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `LipSyncMode`          | `EC_LipSyncMode` | `BS_MHA` | 当项目级 **口型同步模式** 是 `自动`。必须与角色 Skeletal Mesh 上可用的曲线匹配。暴露于 **Details** 面板中的 **Convai\|LipSync** 并作为 Blueprint 可读写属性。 |
| `bEnableInterpolation` | `bool`           | `false`  | 当 `true`时，组件会在连续的 blendshape 帧之间进行插值以平滑播放。暴露于 **Details** 面板中的 **Convai\|LipSync**；不是 Blueprint 可读写属性。            |

### EC\_LipSyncMode 值

`EC_LipSyncMode` 是一个对 Blueprint 可见的枚举（`UENUM(BlueprintType)`）定义于 `ConvaiDefinitions.h`.

| 值                 | 显示名称             | 兼容的绑定骨架                  | 备注                                                                                                                |
| ----------------- | ---------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `关闭`              | `关闭`             | —                        | 当用作项目级值，或者项目级值为 `自动` 且组件值为 `关闭`.                                                                                  |
| `自动`              | `自动`             | 按角色单独设置的绑定骨架             | 作为项目级值时，使用附加的 `UConvaiFaceSyncComponent`的 `LipSyncMode` 在运行时选择 blendshape 格式。该选择在插件本地进行，而不是由 Convai 进行。           |
| `基于音素`            | `基于音素口型`         | 带有 OVR viseme 曲线的自定义绑定骨架 | 生成 15 个 OVR viseme 曲线名称： `静音`, `PP`, `FF`, `TH`, `DD`, `kk`, `CH`, `SS`, `nn`, `RR`, `aa`, `E`, `ih`, `oh`, `ou`. |
| `BS_MHA`          | `MetaHuman 混合变形` | MetaHuman, CC5           | 生成 MetaHuman CTRL 曲线名称。这是默认模式。                                                                                    |
| `BS_ARKit`        | `ARKit 混合变形`     | CC4                      | 生成 61 个 ARKit blendshape 曲线名称（52 个标准 Apple ARKit + 9 个头部/眼部旋转曲线）。                                                 |
| `BS_CC4_Extended` | `CC4 扩展混合变形`     | 使用扩展 blendshape 集的 CC4   | 生成 CC4 Extended 曲线名称。当 CC4 角色在 Character Creator 4 中导出时启用了扩展 blendshape 选项时使用。                                    |

#### 选择正确的模式

当项目级 **口型同步模式** 是 `自动`时，每个组件的 `LipSyncMode` 值必须对应角色 Skeletal Mesh 资产中存在的曲线名称。如果模式与绑定骨架不匹配，AnimGraph 节点会接收到数据，但找不到可写入的匹配曲线，因此面部不会动起来。

* **MetaHuman 角色：** 使用 `BS_MHA`.
* **CC5 角色：** 使用 `BS_MHA`.
* **CC4 角色（标准导出）：** 使用 `BS_ARKit`.
* **CC4 角色（扩展 blendshape 导出）：** 使用 `BS_CC4_Extended`.
* **带有 OVR viseme 目标的自定义绑定骨架：** 使用 `基于音素`.

{% hint style="info" %}
你可以在以下位置设置项目级默认值： **编辑 > 项目设置 > 插件 > Convai > 高级 > Lip Sync 模式**。使用 `自动` 当项目中的角色使用不同的绑定骨架时，这样插件就会读取每个组件的 `LipSyncMode` 在运行时。对于 `BS_CC4_Extended`，请将项目级设置保持为 `自动` 并设置 `LipSyncMode` 在 `Convai Face Sync` 组件。
{% endhint %}

### 录制 API（仅限 C++）

`UConvaiFaceSyncComponent` 提供一个 C++ 录制 API，让你在对话期间捕获实时唇形同步序列，并稍后回放——例如在过场动画、缓存响应或离线预览中。这些方法是普通的 C++ 成员，没有 `UFUNCTION` 装饰宏，且不能从 Blueprints 访问。

| 方法                                                                                                                 | 返回                     | 说明                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `StartRecordingLipSync()`                                                                                          | `void`                 | 开始将来自 Convai 的传入 blendshape 帧捕获到内部缓冲区。在一次对话轮次之前或期间调用此方法，以录制实时面部数据。                                                                                       |
| `FinishRecordingLipSync()`                                                                                         | `FAnimationSequenceBP` | 停止录制，并将捕获到的序列作为一个 `FAnimationSequenceBP`返回。返回的结构体封装了一个 `FAnimationSequence` （帧数组、时长、帧率），并且可以存储在变量中或传递给 `PlayRecordedLipSync`.                            |
| `PlayRecordedLipSync(FAnimationSequenceBP RecordedLipSync, int StartFrame, int EndFrame, float OverwriteDuration)` | `bool`                 | 回放之前捕获的序列。 `StartFrame` 和 `EndFrame` 定义要回放的帧范围；传入 `0` 和 `-1` 以回放整个序列。 `OverwriteDuration` 在大于零时覆盖序列中存储的时长。返回 `false` 如果序列无效、录制正在进行，或者请求的帧范围无效，则返回 false。 |

`FAnimationSequenceBP` 是一个 C++ 结构体，封装了一个 `FAnimationSequence` （带有帧率和时长的按帧索引帧数组）。它定义于 `ConvaiDefinitions.h` 并且是以下函数的返回类型： `FinishRecordingLipSync`.

{% hint style="info" %}
录制的序列会回放所捕获的精确 blendshape 数据。它们不会从 Convai 重新流式传输，且回放与任何正在进行的对话无关。
{% endhint %}

### 状态查询（仅限 C++）

这些 C++ 方法可让你轮询组件当前的播放状态。它们没有 `UFUNCTION` 装饰宏，且不能从 Blueprints 访问。

| 方法                  | 返回                   | 说明                                                   |
| ------------------- | -------------------- | ---------------------------------------------------- |
| `IsPlaying() const` | `bool`               | 返回 `true` 当组件正在主动回放帧时返回 true（无论是来自实时流还是录制序列）。        |
| `GetCurrentFrame()` | `TMap<FName, float>` | 返回组件当前正在应用的帧的 blendshape 名称到权重的映射。适用于调试或用相同数据驱动辅助系统。 |

### 相关参考

{% 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/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/face-sync-component-reference.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.