> 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 Face Sync AnimGraph 节点的全部属性参考——应用模式、面部 alpha、平滑、饥饿混合和 blendshape 映射。

该 `Convai Face Sync` 节点（`FAnimNode_ConvaiFaceSync`）是放置在 AnimGraph 中、位于姿势源和输出姿势之间的动画蓝图节点。它从 `Convai Chatbot` 同一 Actor 上的组件读取面部数据，应用上/下脸 alpha、可选平滑、饥饿混合以及可选重映射表，然后将生成的曲线值写入输出姿势。

当……时，该节点会从所属 Actor 自动解析其聊天机器人组件。 `Convai Chatbot Component` 插脚未设置。所有标记为“默认隐藏插脚”的属性都可通过该节点的 **详情** 面板在 Animation Blueprint 编辑器中访问。

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

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

### 应用模式

| 属性          | 类型                         | 默认值  | 说明                                                       |
| ----------- | -------------------------- | ---- | -------------------------------------------------------- |
| `ApplyMode` | `EConvaiFaceSyncApplyMode` | `添加` | 控制曲线值写入输出姿势的方式。 `添加` 将 Convai 值叠加到现有曲线值之上； `覆盖` 完全替换现有值。 |

#### EConvaiFaceSyncApplyMode 值

| 值    | 行为                                                             |
| ---- | -------------------------------------------------------------- |
| `添加` | 将 Convai 曲线值添加到源姿势已包含的任何曲线值上。当身体或待机动画也驱动面部曲线，并且你希望将它们混合在一起时使用。 |
| `覆盖` | 用 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` 定义每个条目的映射行为。所有字段均可在 Blueprint 中读写。

| 字段                      | 类型              | 默认值     | 说明                                                                                                           |
| ----------------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `TargetNames`           | `TArray<FName>` | `[]`    | 一个或多个骨骼网格上的目标曲线名称，用于写入源值。单个源曲线可分发到多个目标。                                                                      |
| `乘数`                    | `float`         | `1.0`   | 每个条目在以下之前应用的缩放 `GlobalMultiplier` （除非 `IgnoreGlobalModifiers` 是 `true`）。注意：源中的字段名包含一个拼写错误——它是 `乘数`，而不是 `乘数`. |
| `偏移`                    | `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` 中解析，并优先于在 Animation Blueprint 中编写的值。命令行中未设置的标志将回退到 `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`                  | `添加` 或 `覆盖`         | `-LipSyncAnimApplyMode=Override`             |

{% hint style="info" %}
命令行覆盖按进程生效。它们可用于在开发期间微调口型同步行为，而无需编辑并重新编译 Animation Blueprint。它们不会在编辑器重启后保留。
{% 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/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 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/face-sync-animgraph-node-reference.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.