> 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` （蓝图显示名称 **“Convai Face Sync”**）是一个场景组件，用于接收来自 Convai 的面部动画数据、对其进行缓冲，并在每个 Tick 中公开当前帧。

将其添加到与 `UConvaiChatbotComponent`相同的 Actor 上。 `Convai Face Sync` AnimGraph 节点通过 chatbot 组件读取面部数据，而 chatbot 组件会将读取操作委托给附加的 `UConvaiFaceSyncComponent`.

### 返回的结果

| 属性                     | 类型               | 默认值      | 说明                                                                                                                        |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `LipSyncMode`          | `EC_LipSyncMode` | `BS_MHA` | 当项目级 **唇形同步模式** 为 `Auto`时，用于选择 Convai 生成的混合变形目标集。必须与角色骨骼网格体上可用的曲线匹配。在 **细节** 面板的 **Convai\|LipSync** 下提供，并且是一个可通过蓝图读写的属性。 |
| `bEnableInterpolation` | `bool`           | `false`  | 为 `true`时，组件会在连续的混合变形帧之间进行插值，以平滑播放。在 **细节** 面板的 **Convai\|LipSync**下提供；不是可通过蓝图读写的属性。                                      |

### EC\_LipSyncMode 的值

`EC_LipSyncMode` 是一个通过蓝图公开的枚举（`UENUM(BlueprintType)`），定义于 `ConvaiDefinitions.h`.

| 值                 | 显示名称             | 兼容的绑定             | 备注                                                                                                            |
| ----------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `Off`             | `Off`            | —                 | 当用作项目级值时会禁用唇形同步；如果项目级值为 `Auto` 且组件值为 `Off`.                                                                   |
| `Auto`            | `Auto`           | 每个角色各自的绑定         | 用作项目级值时，会在运行时使用附加的 `UConvaiFaceSyncComponent`的 `LipSyncMode` 来选择混合变形目标格式。该选择由插件在本地完成，而非由 Convai 完成。           |
| `VisemeBased`     | `基于音素`           | 带有 OVR 口型曲线的自定义绑定 | 生成 15 个 OVR 口型曲线名称： `sil`, `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 混合变形曲线名称（52 个 Apple ARKit 标准曲线 + 9 个头部/眼部旋转曲线）。                                                 |
| `BS_CC4_Extended` | `CC4 扩展混合形状`     | CC4（扩展混合变形集）      | 生成 CC4 Extended 曲线名称。当 CC4 角色在 Character Creator 4 中导出时启用了扩展混合变形选项，请使用此模式。                                    |

#### 选择正确的模式

当项目范围的 **Lip Sync Mode** 为 `Auto`时，每个组件的 `LipSyncMode` 值必须与角色 Skeletal Mesh 资源中存在的曲线名称相对应。如果模式与骨架不匹配，AnimGraph 节点会接收到数据，但找不到可写入的匹配曲线，因此面部不会动起来。

* **MetaHuman 角色：** 使用 `BS_MHA`.
* **CC5 角色：** 使用 `BS_MHA`.
* **CC4 角色（标准导出）：** 使用 `BS_ARKit`.
* **CC4 角色（扩展混合变形导出）：** 使用 `BS_CC4_Extended`.
* **带有 OVR 音素目标的自定义骨架：** 使用 `VisemeBased`.

{% hint style="info" %}
你可以在以下位置设置项目范围的默认值： **编辑 > 项目设置 > 插件 > Convai > 高级 > Lip Sync Mode**。如果项目中的角色使用不同的骨架，请使用 `Auto` ，这样插件便会在运行时读取每个组件的 `LipSyncMode` 。对于 `BS_CC4_Extended`，将项目范围的设置保持为启用状态 `Auto` 并将 `LipSyncMode` 设置为 `Convai Face Sync` 组件上的此设置。
{% endhint %}

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

`UConvaiFaceSyncComponent` 提供了一个 C++ 录制 API，可在对话期间捕获实时口型同步序列，并在之后重放，例如用于过场动画、缓存的响应或离线预览。这些方法是普通的 C++ 成员，不带 `UFUNCTION` 修饰，因此无法在蓝图中访问。

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

`FAnimationSequenceBP` 是一个封装了 `FAnimationSequence` 的 C++ 结构体（包含按帧索引的帧数组、帧率和时长）。它定义在 `ConvaiDefinitions.h` 中，并且是 `FinishRecordingLipSync`.

{% hint style="info" %}
录制的序列会重放捕获到的确切混合形状数据。它们不会从 Convai 重新流式传输数据，且播放不受任何正在进行的对话影响。
{% endhint %}

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

这些 C++ 方法可用于轮询组件当前的播放状态。它们不带 `UFUNCTION` 修饰，因此无法在蓝图中访问。

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

### 相关参考

{% content-ref url="/pages/ed19695d8a46eb28447110735f1f0dfe84079492" %}
[Face Sync AnimGraph 节点参考](https://docs.convai.com/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" %}
[录制并回放口型同步](https://docs.convai.com/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" %}
[口型同步的工作原理](https://docs.convai.com/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.
