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

# 排查口型同步问题

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

### 说话时嘴部没有动

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

**原因——缺少 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 不匹配：** 项目范围的 **Lip Sync Mode** 是 `Auto`，并且 `LipSyncMode` 在该 `Convai Face Sync` 组件上的设置与 Skeletal Mesh 上的曲线名称不匹配。例如，该组件模式设置为 `VisemeBased` 但该网格拥有 MetaHuman CTRL 曲线，反之亦然。

**修复：** 打开角色 Blueprint，选择 `Convai Face Sync` 该组件，并将 `LipSyncMode` 更改为与骨骼绑定匹配的值。当项目范围的 **Lip Sync Mode** 是 `Auto`:

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

项目范围 **Lip Sync Mode** 可在以下位置全局设置： **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`.

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

### 帧饥饿——嘴部开始动画后在说话中途冻结

**症状：** 口型同步开始正常，但面部在一次说话过程中途冻结，然后恢复或突然回到中立状态。

**原因：** 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 资产，导航到 **曲线** 部分，并复制那里显示的精确曲线名称。将其粘贴到 `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 资产可能未包含在烹制中。Skeletal Mesh 曲线必须被 Animation Blueprint 引用，或包含在资产列表中才能在烹制后保留。

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

**验证：** 运行 Development 烹制并检查烹制日志中是否有关于角色 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" %}
[面部同步组件参考](/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 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/troubleshoot-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.