> 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 组件：** 该 `Convai Face Sync` 组件未放在 Actor 上，因此不会从 Convai 请求面部数据。

**修复：** 打开角色 Blueprint，添加一个 `Convai Face Sync` 组件，并将 `LipSyncMode` 设置为与该绑定匹配的模式（例如 `MetaHuman Blendshapes` 用于 MetaHuman）。编译并保存。

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

***

**原因——AnimGraph 节点未连接：** 该 `Convai Face Sync` AnimGraph 节点已放在 Animation Blueprint 中，但未接入当前激活的姿势链。

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

**验证：** 在 AnimGraph 中，该节点在通往输出的活动路径上不应有断开的引脚。

***

**原因——解析到了错误的 chatbot 组件：** 该 Actor 有多个 `Convai Chatbot` 组件，而 AnimGraph 节点自动发现了错误的那个。

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

**验证：** 在 PIE 中，当该特定 chatbot 组件在对话中处于活动状态时，角色的脸部应会动起来。

### 嘴巴在动，但驱动了错误的曲线

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

**原因——LipSyncMode 不匹配：** 项目级的 **唇形同步模式** 是 `自动`，以及 `LipSyncMode` 在 `Convai Face Sync` 组件上的设置与 Skeletal Mesh 上的曲线名称不匹配。例如，组件模式设置为 `VisemeBased` 但网格具有 MetaHuman CTRL 曲线，反之亦然。

**修复：** 打开角色 Blueprint，选择 `Convai Face Sync` 组件，并将 `LipSyncMode` 更改为与绑定相匹配的值。当项目级 **唇形同步模式** 是 `自动`:

| 绑定类型                   | 正确的 LipSyncMode            |
| ---------------------- | -------------------------- |
| MetaHuman              | `MetaHuman Blendshapes`    |
| CC5                    | `MetaHuman Blendshapes`    |
| CC4（标准导出）              | `ARKit Blendshapes`        |
| CC4（扩展导出）              | `CC4 Extended Blendshapes` |
| 带有 OVR viseme 曲线的自定义绑定 | `基于 Viseme`                |

项目级 **唇形同步模式** 可在以下位置全局设置： **Edit > Project Settings > Plugins > Convai > Advanced > Lip Sync Mode**。例如具体的项目级值，如 `关闭`, `VisemeBased`, `BS_MHA`，以及 `BS_ARKit` 会在连接设置期间覆盖组件值。使用项目级 `自动` 值，当角色使用不同的绑定时，并在每个 `Convai Face Sync` 组件上设置对应于绑定的特定值。对于 `CC4 Extended Blendshapes`，请将项目级设置保持为 `自动` 并将组件设为 `CC4 Extended Blendshapes`.

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

### 帧饥饿——嘴巴先动，随后在说话中途冻结

**症状：** 唇形同步一开始正常，但脸部在一次发言过程中途冻结，然后恢复或突然回到中性状态。

**原因：** AnimGraph 节点在新的网络帧到达之前已耗尽所有缓冲帧。这是一个时序问题，在高延迟连接上往往更明显。

**修复：** 增加 `StarvationBlendOutDuration` 在 AnimGraph 节点上（例如设为 `1.2`），使脸部逐渐淡出而不是突然跳变。这样能让短暂的饥饿间隙不那么明显。

**验证：** 在受限网络下的 PIE 中，嘴巴应在间隙期间平滑淡出，而不是停留在最后一帧。

***

**原因——插值已禁用：** 当 `bEnableInterpolation` 是 `false` 在 `Convai Face Sync` 组件会重放离散帧，而不会在帧之间平滑过渡，这会让间隙更明显。

**修复：** 启用 `bEnableInterpolation` 在 `Convai Face Sync` 角色 Blueprint 中的该组件 **详情** 面板中的 **Convai | LipSync**.

**验证：** PIE 中各帧之间的过渡应更平滑。

### 自定义 blendshape 重映射没有输出

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

**原因——目标曲线名称不匹配：** 该 `TargetNames` 中的数组 `FConvaiBlendshapeParameters` 条目与 Skeletal Mesh 上的精确曲线名称不匹配。

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

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

***

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

**修复：** 通过检查该模式预期的曲线集来确认源曲线名称：

* `VisemeBased`：15 个 OVR viseme 名称（`sil`, `PP`, `FF`, `TH`, `DD`, `kk`, `CH`, `SS`, `nn`, `RR`, `aa`, `E`, `ih`, `oh`, `ou`)
* `BS_ARKit`：61 个 ARKit blendshape 曲线名称（52 个标准 Apple ARKit + 9 个头部/眼睛旋转曲线）
* `BS_MHA`：MetaHuman CTRL 曲线名称

请将精确的源名称用作映射键。

**验证：** 移除映射或临时清空映射。如果曲线在 1:1 映射下能够动画，则说明源名称正确，问题出在 `TargetNames`.

### 编辑器中会动，但在打包构建中不动

**症状：** 唇形同步在 PIE 中正常，但在烘焙后的构建中脸部不动画。

**原因：** 曲线资源或 Animation Blueprint 资源可能未包含在 cook 中。Skeletal Mesh 曲线必须由 Animation Blueprint 引用，或包含在资源列表中，才能在 cook 后保留。

**修复：** 确认面部 Animation Blueprint 已被角色 Blueprint 或包含在 cook 中的关卡引用。如果曲线被剥离，请将它们添加到该资源的 **Skeleton** ，并确保该 Skeleton 资源位于已烘焙的包中。

**验证：** 运行 Development cook，并检查 cook 日志中是否有关于角色 Skeleton 上被剥离曲线轨道的警告。

{% hint style="info" %}
命令行覆盖（`-LipSyncAnim*` 标志）在 PIE 中设置后不会自动带到打包构建中，除非在启动时显式传入。请参阅 [Face Sync AnimGraph 节点参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/face-sync-animgraph-node-reference.md) 以查看受支持覆盖标志的完整列表。
{% endhint %}

### 下一步

{% content-ref url="/pages/8b7003d8fdf40c7b56b0fd2a54376bfc5105903c" %}
[Face Sync 组件参考](/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 节点参考](/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" %}
[口型同步和动画问题](/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.