> 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/record-and-replay-lip-sync.md).

# 记录并回放口型同步

该 `UConvaiFaceSyncComponent` 录制 API 让你能够捕获实时对话中到达的 blendshape 帧，并在不重新从 Convai 进行流式传输的情况下按需回放。它适用于同一段口型同步序列会反复播放的过场动画、在响应被触发之前进行预热，或者用于调试以及面部动画的离线预览。

{% hint style="warning" %}
录制 API — `StartRecordingLipSync`, `FinishRecordingLipSync`, `PlayRecordedLipSync`, `IsPlaying`，以及 `GetCurrentFrame` — 仅适用于 C++。这些方法没有 `UFUNCTION` 修饰，无法从蓝图中访问。
{% endhint %}

### 何时使用录制 API

| 使用场景         | 方法                                            |
| ------------ | --------------------------------------------- |
| 带固定角色台词的过场动画 | 在开发期间录制一次，保存该序列，并在过场动画中回放                     |
| 预热的响应缓存      | 首次播放时录制响应，后续相同响应直接回放                          |
| 离线面部动画预览     | 在 PIE 会话期间录制，使用以下方法检查帧数据： `GetCurrentFrame()` |
| 实时流式传输（实时对话） | 不要使用录制 API——AnimGraph 节点会自动处理实时帧              |

### 前提条件

* Actor 具有一个 `Convai 面部同步` 组件和一个可工作的 `Convai 聊天机器人` 组件。
* 该角色在对话时已经会生成口型同步（如果没有，请参见 [口型同步快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/lip-sync-quick-start.md) ）。

### 录制一个序列

{% stepper %}
{% step %}

#### 在发言开始前启动录制

调用 `StartRecordingLipSync()` 在 `UConvaiFaceSyncComponent` 实例。从这一刻起，Convai 传来的每一帧 blendshape 数据都会在应用到面部的同时被内部缓存。

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

{% endstep %}

{% step %}

#### 让角色说话

像平常一样触发一次对话。角色会说话，面部也会动画化。组件会在后台捕获传入的帧——录制期间不需要额外调用。
{% endstep %}

{% step %}

#### 停止录制并保存结果

当发言结束时，调用 `FinishRecordingLipSync()`。该方法会停止捕获并返回一个 `FAnimationSequenceBP` ，其中包含按帧索引排列的完整 blendshape 帧列表、总时长以及帧率。

```cpp
// 伪代码
FAnimationSequenceBP CachedSequence = FaceSync->FinishRecordingLipSync();
```

将这个值存为 Actor 或组件上的成员变量，以便之后回放。此时你已经拥有了在该轮对话中播放过的完整面部动画。
{% endstep %}
{% endstepper %}

### 回放已录制的序列

调用 `PlayRecordedLipSync` 在 `UConvaiFaceSyncComponent` 实例来回放已保存的序列。组件会将录制的帧精确地喂给 AnimGraph 节点，就像在实时流中那样，而且不需要当前有活动的 Convai 对话流。

#### PlayRecordedLipSync 参数

| 参数                  | 类型                     | 描述                                  |
| ------------------- | ---------------------- | ----------------------------------- |
| `RecordedLipSync`   | `FAnimationSequenceBP` | 由 `FinishRecordingLipSync`.         |
| `StartFrame`        | `int32`                | 要回放的第一帧索引。传入 `0` 以从头开始。             |
| `EndFrame`          | `int32`                | 要回放的最后一帧索引。传入 `-1` 以播放到序列末尾。        |
| `OverwriteDuration` | `float`                | 覆盖序列中以秒为单位存储的播放时长。传入 `0.0` 以使用原始时长。 |

`PlayRecordedLipSync` 返回 `bool` — `true` 如果序列成功开始，则返回 `false` 如果序列为空或无效、录制仍在进行中， `StartFrame` 大于最后一帧索引，或者 `EndFrame` 大于 `0` 且小于 `StartFrame`.

```cpp
// 伪代码
bool bStarted = FaceSync->PlayRecordedLipSync(CachedSequence, 0, -1, 0.0f);
```

### 监控播放状态

在录制序列播放时，使用这些 C++ 方法来观察组件：

| 方法                  | 返回                   | 描述                                            |
| ------------------- | -------------------- | --------------------------------------------- |
| `IsPlaying() const` | `bool`               | `true` 当组件正在主动回放来自录制序列或实时序列的帧时。               |
| `GetCurrentFrame()` | `TMap<FName, float>` | 当前正在应用的帧的 blendshape 名称到权重的映射。适合用同一份数据驱动辅助系统。 |

### C++ 示例流程

典型的过场动画用法如下：

```cpp
// 伪代码
// 1. 在发言开始前或开始时：
FaceSync->StartRecordingLipSync();

// 2. 角色说话——录制会在后台自动进行。

// 3. 当发言结束时：
FAnimationSequenceBP CachedSequence = FaceSync->FinishRecordingLipSync();

// 4. 当你想回放该序列时（例如在过场动画触发时）：
FaceSync->PlayRecordedLipSync(CachedSequence, 0, -1, 0.0f);
```

{% hint style="info" %}
回放一个序列不会重新触发音频。请单独播放匹配的音频片段，并对齐播放开始时间，以保持面部和声音同步。
{% endhint %}

### 下一步

{% content-ref url="/pages/8b7003d8fdf40c7b56b0fd2a54376bfc5105903c" %}
[面部同步组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/face-sync-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/1d4e6a68b8b0634dd00381e03cb9447a556b758c" %}
[口型同步使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/lip-sync-usage-examples.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/record-and-replay-lip-sync.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.