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

# 面部同步组件参考

`UConvaiFaceSyncComponent` （Blueprint 显示名称 **“Convai Face Sync”**）是一个场景组件，用于接收来自 Convai 的面部动画数据，对其进行缓冲，并在每个 Tick 中暴露当前帧。

将其添加到与 `UConvaiChatbotComponent`。该 `Convai 面部同步` AnimGraph 节点通过聊天机器人组件读取面部数据，而该组件会委托给所附加的 `UConvaiFaceSyncComponent`.

### 属性

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

### EC\_LipSyncMode 值

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

| 值                 | 显示名称                       | 兼容的绑定                  | 说明                                                                                                                 |
| ----------------- | -------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `关闭`              | `关闭`                       | —                      | 当用作项目级值时会禁用唇形同步，或者当项目级值为 `Auto` 且组件值为 `关闭`.                                                                        |
| `Auto`            | `Auto`                     | 按角色的绑定                 | 作为项目级值时，使用所附加的 `UConvaiFaceSyncComponent`的 `LipSyncMode` 在运行时选择 blendshape 格式。该选择在插件本地进行，而不是由 Convai 完成。           |
| `VisemeBased`     | `基于 Viseme`                | 带有 OVR viseme 曲线的自定义绑定 | 生成 15 个 OVR viseme 曲线名称： `sil`, `PP`, `FF`, `TH`, `DD`, `kk`, `CH`, `SS`, `nn`, `RR`, `aa`, `E`, `ih`, `oh`, `ou`. |
| `BS_MHA`          | `MetaHuman Blendshapes`    | MetaHuman、CC5          | 生成 MetaHuman CTRL 曲线名称。这是默认模式。                                                                                     |
| `BS_ARKit`        | `ARKit Blendshapes`        | CC4                    | 生成 61 个 ARKit blendshape 曲线名称（52 个标准 Apple ARKit + 9 个头部/眼球旋转曲线）。                                                  |
| `BS_CC4_Extended` | `CC4 Extended Blendshapes` | 带扩展 blendshape 集的 CC4  | 生成 CC4 Extended 曲线名称。当 CC4 角色在 Character Creator 4 中启用了扩展 blendshape 选项导出时使用。                                      |

#### 选择正确的模式

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

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

{% hint style="info" %}
你可以在以下位置设置项目级默认值： **编辑 > 项目设置 > 插件 > Convai > 高级 > 唇形同步模式**时。使用 `Auto` 当项目中的角色使用不同的绑定时，这样插件就会读取每个组件的 `LipSyncMode` 在运行时。对于 `BS_CC4_Extended`，请将项目级设置保持为 `Auto` 并设置 `LipSyncMode` 在 `Convai 面部同步` 组件。
{% 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` 如果序列无效、录制处于活动状态，或者请求的帧范围无效，则返回 |

`FAnimationSequenceBP` 是一个 C++ 结构体，用于封装一个 `FAnimationSequence` （按帧索引的帧数组，包含帧率和时长）。它定义于 `ConvaiDefinitions.h` 并且是……的返回类型 `FinishRecordingLipSync`.

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

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

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

| 方法                  | 返回                   | 说明                                                     |
| ------------------- | -------------------- | ------------------------------------------------------ |
| `IsPlaying() const` | `bool`               | 返回 `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 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/face-sync-component-reference.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.