> 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-animgraph-node-reference.md).

# Face Sync AnimGraph 节点参考

该 `Convai 面部同步` 节点（`FAnimNode_ConvaiFaceSync`）是一个放置在 AnimGraph 中、位于姿势源和输出姿势之间的动画蓝图节点。它从以下对象读取面部数据： `Convai 聊天机器人` 同一 Actor 上的组件，应用上/下面部 alpha、可选平滑、starvation 混合，以及可选重映射表，然后将结果曲线值写入输出姿势。

当以下情况时，该节点会自动从所属 Actor 解析其聊天机器人组件： `Convai 聊天机器人组件` 引脚未设置。所有标记为“默认隐藏引脚”的属性都可通过节点的 **详细信息** 动画蓝图编辑器中的面板访问。

### 姿势输入与组件链接

| 属性                       | 类型                         | 默认值       | 描述                                                                                          |
| ------------------------ | -------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| `SourcePose`             | `FPoseLink`                | —         | 添加或应用面部曲线的输入姿势。请从 AnimGraph 中前一个节点连接到这里。                                                    |
| `ConvaiChatbotComponent` | `UConvaiChatbotComponent*` | `nullptr` | 用于读取面部数据的聊天机器人组件引用。当 `nullptr`时，节点会自动发现第一个 `UConvaiChatbotComponent` 在所属 Actor 上的组件。引脚默认显示。 |

### 应用模式

| 属性          | 类型                         | 默认值   | 描述                                                             |
| ----------- | -------------------------- | ----- | -------------------------------------------------------------- |
| `ApplyMode` | `EConvaiFaceSyncApplyMode` | `Add` | 控制曲线值如何写入输出姿势。 `Add` 将 Convai 值叠加到现有曲线值之上； `Override` 完全替换现有值。 |

#### EConvaiFaceSyncApplyMode 值

| 值          | 行为                                                             |
| ---------- | -------------------------------------------------------------- |
| `Add`      | 将 Convai 曲线值添加到源姿势已经包含的任何曲线值上。当身体或待机动画也驱动面部曲线，而你希望将它们混合在一起时使用。 |
| `Override` | 用 Convai 曲线值替换现有曲线值。当 Convai 应作为动画曲线的唯一驱动来源时使用。                |

### 面部拆分

| 属性                         | 类型              | 默认值   | 描述                                               |
| -------------------------- | --------------- | ----- | ------------------------------------------------ |
| `UpperFaceBlendshapeNames` | `TArray<FName>` | `[]`  | 被视为上半脸形状（眉毛、眼睛、眼睑）的曲线名称。此列表之外的每条曲线都视为下半脸。引脚默认隐藏。 |
| `UpperFaceAlpha`           | `float`         | `0.8` | 应用于上半脸曲线值的缩放。限制在 `[0.0, 1.0]`。引脚默认隐藏。            |
| `LowerFaceAlpha`           | `float`         | `1.0` | 应用于下半脸曲线值的缩放。限制在 `[0.0, 1.0]`。引脚默认隐藏。            |

当 `UpperFaceBlendshapeNames` 为空时，所有曲线都接收 `LowerFaceAlpha` 缩放。

### 平滑

平滑使用指数移动平均（EMA）。速度值被限制在 `[0.0, 1.0]` 在编辑器中。 `0.0` 会产生最大的延迟（每帧该值几乎不会向目标移动）； `1.0` 是即时的（不进行平滑，该值在一帧内到达目标）。在 `0.5` 和 60 fps 下，每条曲线每帧大约向目标移动 50%。实用起始值： `0.3`–`0.5` 用于平滑且响应灵敏的下半脸； `0.1`–`0.2` 用于更克制的上半脸。

| 属性                          | 类型      | 默认值     | 描述                                                                                                             |
| --------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `bEnableLowerFaceSmoothing` | `bool`  | `false` | 为下半脸曲线启用指数移动平均平滑。                                                                                              |
| `LowerFaceSmoothingSpeed`   | `float` | `1.0`   | 下半脸平滑的 EMA 速度。限制在 `[0.0, 1.0]` 在编辑器中： `0.0` = 最大延迟， `1.0` = 即时。仅当 `bEnableLowerFaceSmoothing` 为 `true`。引脚默认隐藏。 |
| `bEnableUpperFaceSmoothing` | `bool`  | `false` | 为上半脸曲线启用指数移动平均平滑。                                                                                              |
| `UpperFaceSmoothingSpeed`   | `float` | `1.0`   | 上半脸平滑的 EMA 速度。限制在 `[0.0, 1.0]` 在编辑器中： `0.0` = 最大延迟， `1.0` = 即时。仅当 `bEnableUpperFaceSmoothing` 为 `true`。引脚默认隐藏。 |

### 缓冲耗尽混合

当口型同步缓冲区的帧耗尽时——例如在说话轮次之间或第一帧到达之前——节点会将曲线贡献混合到零。 当帧再次可用时，它会重新混入。这可以防止面部突然跳回中性再跳回来。

| 属性                           | 类型      | 默认值   | 描述                                                   |
| ---------------------------- | ------- | ----- | ---------------------------------------------------- |
| `StarvationBlendInDuration`  | `float` | `0.1` | 将曲线贡献从 `0` 到 `1` 在帧变为可用时进行混合。设置为 `0` 可实现即时过渡。引脚默认隐藏。 |
| `StarvationBlendOutDuration` | `float` | `0.8` | 将曲线贡献从 `1` 到 `0` 在缓冲区为空时。设置为 `0` 可实现即时过渡。引脚默认隐藏。     |

这两个值都按恒定速率生效。在过渡中途反向所需时间会按比例少于完整过渡。

### Blendshape 映射

| 属性                  | 类型                                         | 默认值   | 描述                                                                                                                          |
| ------------------- | ------------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------- |
| `BlendshapeMapping` | `TMap<FName, FConvaiBlendshapeParameters>` | `{}`  | 可选的重映射表。键为来自 Convai 的源曲线名称；值为一个 `FConvaiBlendshapeParameters` 结构体，用于定义目标曲线名称、每项乘数、偏移、限制以及可选覆盖。为空时，曲线按 1:1 应用，不进行重映射。引脚默认隐藏。 |
| `GlobalMultiplier`  | `float`                                    | `1.0` | 应用于所有映射曲线值的乘数，除非 `IgnoreGlobalModifiers` 在该条目上已设置。引脚默认隐藏。                                                                   |
| `GlobalOffset`      | `float`                                    | `0.0` | 添加到所有映射曲线值上的偏移，除非 `IgnoreGlobalModifiers` 在该条目上已设置。引脚默认隐藏。                                                                  |

#### FConvaiBlendshapeParameters 字段

`FConvaiBlendshapeParameters` 定义每个条目的映射行为。所有字段均可在蓝图中读/写。

| 字段                      | 类型              | 默认值     | 描述                                                                                                                             |
| ----------------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `TargetNames`           | `TArray<FName>` | `[]`    | Skeletal Mesh 上用于写入源值的一个或多个目标曲线名称。一条源曲线可分发到多个目标。                                                                               |
| `Multiplyer`            | `float`         | `1.0`   | 在以下操作之前应用于每项的缩放： `GlobalMultiplier` （除非 `IgnoreGlobalModifiers` 为 `true`）。注意：源中的字段名包含一个拼写错误——它是 `Multiplyer`，而不是 `Multiplier`. |
| `Offset`                | `float`         | `0.0`   | 每项在缩放后添加的偏移。                                                                                                                   |
| `UseOverrideValue`      | `bool`          | `false` | 当 `true`，则曲线设置为 `OverrideValue` ，而不管输入数据如何。适用于将曲线固定到某个值。                                                                       |
| `OverrideValue`         | `float`         | `0.0`   | 当 `UseOverrideValue` 为 `true`.                                                                                                 |
| `IgnoreGlobalModifiers` | `bool`          | `false` | 当 `true`, `GlobalMultiplier` 和 `GlobalOffset` 未应用于此条目时使用的固定值。                                                                  |
| `ClampMinValue`         | `float`         | `0.0`   | 在所有缩放和偏移之后，曲线允许达到的最小值。                                                                                                         |
| `ClampMaxValue`         | `float`         | `1.0`   | 在所有缩放和偏移之后，曲线允许达到的最大值。                                                                                                         |

### 命令行覆盖

下面列出的可调属性可在启动时通过传入一个 `-LipSyncAnim*` 标志来覆盖。覆盖会在每个 PIE 会话中于 `Initialize_AnyThread` 中解析一次，并优先于在动画蓝图中编写的值。命令行中未设置的标志将回退到 `UPROPERTY` 值。

| 标志                                       | 类型                  | 示例                                           |
| ---------------------------------------- | ------------------- | -------------------------------------------- |
| `-LipSyncAnimUpperFaceAlpha`             | `float`             | `-LipSyncAnimUpperFaceAlpha=0.5`             |
| `-LipSyncAnimLowerFaceAlpha`             | `float`             | `-LipSyncAnimLowerFaceAlpha=0.8`             |
| `-LipSyncAnimStarvationBlendInDuration`  | `float`             | `-LipSyncAnimStarvationBlendInDuration=0.05` |
| `-LipSyncAnimStarvationBlendOutDuration` | `float`             | `-LipSyncAnimStarvationBlendOutDuration=1.2` |
| `-LipSyncAnimGlobalMultiplier`           | `float`             | `-LipSyncAnimGlobalMultiplier=1.2`           |
| `-LipSyncAnimGlobalOffset`               | `float`             | `-LipSyncAnimGlobalOffset=0.0`               |
| `-LipSyncAnimLowerFaceSmoothingSpeed`    | `float`             | `-LipSyncAnimLowerFaceSmoothingSpeed=0.4`    |
| `-LipSyncAnimUpperFaceSmoothingSpeed`    | `float`             | `-LipSyncAnimUpperFaceSmoothingSpeed=0.2`    |
| `-LipSyncAnimEnableLowerFaceSmoothing`   | `bool` (`1`/`true`) | `-LipSyncAnimEnableLowerFaceSmoothing=1`     |
| `-LipSyncAnimEnableUpperFaceSmoothing`   | `bool` (`1`/`true`) | `-LipSyncAnimEnableUpperFaceSmoothing=1`     |
| `-LipSyncAnimBypassSmoothing`            | `bool` (`1`/`true`) | `-LipSyncAnimBypassSmoothing=1`              |
| `-LipSyncAnimBypassStarvationBlend`      | `bool` (`1`/`true`) | `-LipSyncAnimBypassStarvationBlend=1`        |
| `-LipSyncAnimApplyMode`                  | `Add` 或 `Override`  | `-LipSyncAnimApplyMode=Override`             |

{% 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/face-sync-animgraph-node-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.