> 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/troubleshoot-lip-sync.md).

# 排查口型同步问题

诊断并修复 Convai Unreal Engine 插件中的口型同步问题——没有嘴部动作、帧饥饿、blendshape 映射错误，以及骨骼不匹配。

使用此页面识别并修复最常见的口型同步问题。每个条目都会说明你观察到的现象、问题原因以及需要进行的更改。

### 说话时嘴部没有动作

**症状：** 角色在说话（音频正常播放），但嘴部和面部没有动作。

**原因 — 缺少 Face Sync 组件：** Actor 上没有 `Convai Face Sync` 组件，因此不会向 Convai 请求面部数据。

**修复方法：** 打开角色蓝图，添加 `Convai Face Sync` 组件，并将 `LipSyncMode` 设为与绑定相匹配的模式（例如，MetaHuman 使用 `MetaHuman Blendshapes` ）。然后编译并保存。

**验证：** 进入 Play 模式，确认运行时 Actor 的组件列表中包含 **Convai Face Sync** 组件。

***

**原因 — AnimGraph 节点未连接：** 已在动画蓝图中放置 `Convai Face Sync` AnimGraph 节点，但该节点未连接到当前使用的姿势链。

**修复方法：** 打开面部动画蓝图。确认 `Convai Face Sync` 节点的 **Source Pose** 引脚接收前一个姿势，并且其 **Output Pose** 引脚连接到最终输出。重新编译动画蓝图。

**验证：** 在 AnimGraph 中，沿着通往输出的活动路径，节点不应有任何未连接的引脚。

***

**原因 — 解析到错误的聊天机器人组件：** Actor 上有多个 `Convai Chatbot` 组件，而 AnimGraph 节点自动发现了错误的组件。

**修复方法：** 将正确的 `Convai Chatbot` 组件引用显式连接到 **Convai Chatbot Component** 引脚，该引脚位于 `Convai Face Sync` 节点上。

**验证：** 在 PIE 中，当该特定聊天机器人组件参与对话时，角色的面部应会动起来。

### 嘴部会动，但播放了错误的曲线

**症状：** 脸上的某些部位会动，但不是嘴巴——例如，眼睛快速眨动，或无关的形状被激活。

**原因 — LipSyncMode 不匹配：** 项目级 **口型同步模式** 为 `Auto`，而 `LipSyncMode` 组件上的 `Convai Face Sync` 与骨骼网格体上的曲线名称不匹配。例如，组件模式设为 `VisemeBased` ，但网格体使用的是 MetaHuman CTRL 曲线，反之亦然。

**修复方法：** 打开角色蓝图，选择 `Convai Face Sync` 组件，并将 `LipSyncMode` 更改为与绑定匹配的值。当项目级 **口型同步模式** 为 `Auto`:

| 绑定类型              | 正确的 LipSyncMode  |
| ----------------- | ---------------- |
| MetaHuman         | `MetaHuman 混合形状` |
| CC5               | `MetaHuman 混合形状` |
| CC4（标准导出）         | `ARKit 混合形状`     |
| CC4（扩展导出）         | `CC4 扩展混合形状`     |
| 使用 OVR 视素曲线的自定义绑定 | `基于音素`           |

项目级 **口型同步模式** 可在以下位置进行全局设置： **Edit > Project Settings > Plugins > Convai > Advanced > Lip Sync Mode**。具体的项目级设置值（例如 `Off`, `VisemeBased`, `BS_MHA`和 `BS_ARKit` ）会在连接设置期间覆盖组件值。角色使用不同绑定时，请将项目级设置为 `Auto` ，并为每个 `Convai Face Sync` 组件设置对应绑定的值。对于 `CC4 Extended Blendshapes`，请将项目级设置保持为 `Auto` ，并将组件设为 `CC4 Extended Blendshapes`.

**验证：** 在编辑器中重新打开骨骼网格体，并检查 **曲线** 列表。确认曲线名称与所选模式生成的名称一致。

### 帧耗尽——嘴部动画后在说话途中冻结

**症状：** 口型同步正常启动，但角色面部在一段话说到一半时冻结，随后恢复动画或突然回到中性状态。

**原因：** AnimGraph 节点在网络传来新帧之前，已耗尽所有缓冲帧。这是一个时序问题，在高延迟连接下通常更明显。

**修复方法：** 增大 `StarvationBlendOutDuration` AnimGraph 节点上的该值（例如设为 `1.2`），这样面部会逐渐淡出，而不是突然跳变。这样可以降低短暂帧耗尽间隙的可见程度。

**验证：** 在 PIE 中使用网络限速时，间隙期间嘴部应平滑淡出，而不是冻结在最后一帧。

***

**原因——插值已禁用：** 当 `bEnableInterpolation` 在 `false` 时， `Convai Face Sync` 组件会逐帧重放离散帧，而不在帧间进行平滑处理，因此间隙可能会更加明显。

**修复方法：** 在角色蓝图的 `bEnableInterpolation` 组件中启用 `Convai Face Sync` ，在角色蓝图的 **Details（细节）** 面板中的 **Convai | LipSync**.

**验证：** 在 PIE 中，帧与帧之间的过渡应当更加平滑。

### 自定义混合变形映射未产生输出

**症状：** 已配置一个 `BlendshapeMapping` 条目，但目标曲线没有变化。

**原因——目标曲线名称不匹配：** FConvaiBlendshapeParameters `中的` TargetNames `数组` 与 Skeletal Mesh 上的曲线名称不完全一致。

**修复方法：** 在编辑器中打开 Skeletal Mesh 资源，找到 **Curves（曲线）** 部分，并复制其中显示的准确曲线名称。将其粘贴到 `TargetNames` 条目中。

**验证：** 在映射中添加一条测试项，输入 PIE，并确认目标曲线有响应。

***

**原因 — 源名称不匹配：** BlendshapeMapping `BlendshapeMapping` 表中的键与 Convai 为所选 `LipSyncMode`.

**返回的曲线名称不匹配。** 修复：

* `通过检查该模式预期的曲线集合，确认源曲线名称：`VisemeBased`：15 个 OVR 视素名称（`, `sil`, `PP`, `FF`, `TH`, `DD`, `kk`, `CH`, `SS`, `nn`, `RR`, `aa`, `E`, `ih`, `oh`)
* `ou`BS\_ARKit
* `：61 个 ARKit 混合变形曲线名称（52 个 Apple ARKit 标准曲线 + 9 个头部/眼部旋转曲线）`BS\_MHA

：MetaHuman CTRL 曲线名称

**使用完全一致的源名称作为映射键。** 验证： `移除或暂时清空映射。如果使用 1:1 映射时曲线能够动画播放，则源名称正确，问题出在`.

### TargetNames

**面部在编辑器中会动，但在打包版本中不会动** 症状：

**PIE 中唇形同步正常，但在已烘焙的构建版本中面部不会动。** 原因：

**曲线资源或动画蓝图资源可能未包含在烘焙内容中。骨骼网格体曲线必须由动画蓝图引用，或包含在资源列表中，才能在烘焙后保留。** 修复： **确认角色蓝图或包含在烘焙内容中的关卡引用了面部动画蓝图。如果曲线被剥离，请将它们添加到资源的** Skeleton

**中，并确保 Skeleton 资源包含在已烘焙的包中。** 验证：

{% hint style="info" %}
运行 Development 烘焙，并检查烘焙日志中是否有关于角色 Skeleton 上曲线轨道被剥离的警告。`命令行覆盖项（` -LipSyncAnim\* [标志）在 PIE 期间设置后，不会沿用到打包版本中，除非在启动时显式传入。支持的覆盖标志完整列表，请参阅](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) 面部同步 AnimGraph 节点参考。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/8b7003d8fdf40c7b56b0fd2a54376bfc5105903c" %}
[Face Sync 组件参考](https://docs.convai.com/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/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/aade7c9244e67877d732705a3f1075d5958e0a22" %}
[口型同步和动画问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/lip-sync-and-animation-issues.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/troubleshoot-lip-sync.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.
