> 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/web-plugins/convai-web-sdk/lipsync-and-blendshape/metahuman-limit-drivers-required-for-mha.md).

# 应用 MetaHuman 限制驱动器

将 MetaHuman 绑定耦合、调校后的增益和淡入淡出包络应用到 251 通道流中，使角色的嘴唇保持闭合，同时下颌移动。

将 MetaHuman 绑定耦合应用到每个 `mha` 帧，然后再将其写入角色的形态目标。当由 `mha` 格式驱动的角色在每次下颌运动时都会露出牙齿，请参阅此页面。处理完成后，下颌张开时双唇仍保持接触，嘴部看起来像是在说话，而不是一张一合。

### 为什么 mha 流需要耦合

&#x20;`mha`  流是针对 Unreal 的 MetaHuman 绑定制作的，该绑定会由某些控件驱动其他控件。同一角色的 glTF 导出包含形态目标，但不包含这些耦合关系。最明显的例子是由  `jawOpen`  驱动四个  `mouthLipsTogether*`  控件：如果没有此耦合，每次张开下颌都会使双唇分开并露出牙齿。

每个耦合都会将目标通道设为自身值与源值中的较大值。SDK 会应用以下 11 个耦合：

| 源               | 目标                       |
| --------------- | ------------------------ |
| `eyeBlinkL`     | `eyeLidPressL`           |
| `eyeBlinkR`     | `eyeLidPressR`           |
| `noseWrinkleL`  | `noseWrinkleUpperL`      |
| `noseWrinkleR`  | `noseWrinkleUpperR`      |
| `mouthStretchL` | `mouthStretchLipsCloseL` |
| `mouthStretchR` | `mouthStretchLipsCloseR` |
| `jawOpen`       | `jawOpenExtreme`         |
| `jawOpen`       | `mouthLipsTogetherUL`    |
| `jawOpen`       | `mouthLipsTogetherUR`    |
| `jawOpen`       | `mouthLipsTogetherDL`    |
| `jawOpen`       | `mouthLipsTogetherDR`    |

名称是  `CTRL_expressions_*`  通道的简写形式。 `MHA_LIMIT_DRIVERS` 会导出解析为帧索引的同一张表，条目格式为  `{ source, target, sourceIdx, targetIdx }`.

### 前提条件

* 启用唇形同步，且将  `blendshapeConfig.format` 设为 `'mha'`，并从  `client.blendshapeQueue` 读取帧。请参阅 [使用混合变形驱动面部动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/lipsync-and-blendshape.md).
* 形态目标以  `CTRL_expressions_*`  通道命名的角色。请参阅 [混合变形通道顺序参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript/mappings-reference.md).

### 将耦合规则应用于帧

如果你已经自行将帧写入变形目标，请先对每一帧调用 `applyMhaLimits` 。该函数会就地修改帧，对少于 251 个值的帧不做任何处理。

流在一次回复的每一帧中发送的 `noseWrinkleUpperL` 和 `noseWrinkleUpperR` 都恰好为 1.0，这看起来像是表情僵住的冷笑。 `applyMhaLimits` 和口型同步处理器会将这两个通道上大于或等于 0.999 的值视为未设置，以便通过耦合规则根据 `noseWrinkle`推导出它们的值。如果不使用这些辅助函数而直接将原始帧写入变形目标，请自行清除这两个通道的值。

```ts
import { applyMhaLimits } from '@convai/web-sdk/lipsync-helpers';

function applyMhaFrame(frame: Float32Array) {
  const shaped = new Float32Array(frame);
  applyMhaLimits(shaped);
  applyFrame(shaped);
}
```

如上例所示，在修改帧之前先复制一份，以免改动队列中保存的值。

### 使用口型同步处理器

`createLipsyncProcessor('mha')` 封装了完整的逐帧处理流程：先处理嘴部对称性，再应用耦合规则、各通道增益和淡入淡出包络，最后写入变形目标。

```ts
import { createLipsyncProcessor } from '@convai/web-sdk/lipsync-helpers';

const lipsync = createLipsyncProcessor('mha', { skipEyeChannels: true });
const bindings = lipsync.bindAll(gltf.scene);

// 每次渲染时传入要播放的帧；角色静默时传入 null。
lipsync.tick(frameOrNull, deltaSeconds, bindings);
```

处理器返回以下成员：

| 成员                                    | 功能说明                                                      |
| ------------------------------------- | --------------------------------------------------------- |
| `process(frame, deltaSeconds)`        | 处理一帧并返回本次更新要写入的值；静默后包络稳定时返回 `null` 。返回的数组会被复用；如需保留，请复制一份。 |
| `bindMesh(mesh)`                      | 解析单个网格的变形槽位并返回一个绑定；没有匹配通道时返回 `null` 。                     |
| `bindAll(root)`                       | 遍历场景并绑定所有具有匹配变形目标的网格。                                     |
| `apply(output, bindings)`             | 将处理后的帧写入绑定。对于 `null`.                                     |
| `tick(frame, deltaSeconds, bindings)` | `process` 和 `apply` 合为一次调用。                               |
| `profile`                             | 当前使用的格式配置。                                                |

`bindMesh` 和 `bindAll` 还会原地修复一个已知的导出问题：前缀后缺少下划线的名称，例如 `CTRL_expressionsjawOpen`，会在网格的 `CTRL_expressions_jawOpen` morphTargetDictionary `中重命名为`.

选项及其默认值：

| 选项                    | 默认值                               | 即可完全隐藏叠加层。                           |
| --------------------- | --------------------------------- | ------------------------------------ |
| `symmetrizeMouth`     | `true`                            | 对每一对左右口部和下颌通道取平均值。                   |
| `applyLimits`         | `true`                            | 应用上述 11 项耦合。                         |
| `useRecommendedGains` | `true`                            | 使用下方的推荐增益表作为起始值。                     |
| `gainOverrides`       | `{}`                              | 按短名称指定每个通道的增益，例如 `{ jawOpen: 0.8 }`. |
| `skipEyeChannels`     | `false`                           | 保持眼部通道不变。                            |
| `envelope`            | `{ attack: 0.09, release: 0.18 }` | 淡入和淡出的时间常数，单位为秒。 `false` 会禁用包络。      |

`createLipsyncProcessor` 仅支持 `mha` 格式。传入任何其他格式名称都会抛出错误，并列出可用格式。若要使用其他格式，请传入自定义的 `LipsyncFormatProfile` ，而不要传入格式名称。

{% hint style="info" %}
`getFrameWithAlpha` 已对一个回合的首尾各 10 帧进行淡化。如果帧要经过处理器的包络处理，请改用 `getFrame` 读取，以免重复应用淡化效果。
{% endhint %}

### 推荐增益

启用 `useRecommendedGains` 后，这些通道会进行缩放。其他所有通道的增益均为 `1`.

| 通道                                                                                         | 增益     |
| ------------------------------------------------------------------------------------------ | ------ |
| `jawOpen`                                                                                  | `0.72` |
| `jawOpenExtreme`                                                                           | `0.42` |
| `jawLeft`, `jawRight`, `mouthLeft`, `mouthRight`                                           | `0`    |
| `mouthUpperLipRaiseL`, `mouthUpperLipRaiseR`                                               | `0.6`  |
| `mouthLowerLipDepressL`, `mouthLowerLipDepressR`                                           | `0.45` |
| `mouthLipsTogetherUL`, `mouthLipsTogetherUR`, `mouthLipsTogetherDL`, `mouthLipsTogetherDR` | `0.8`  |
| `mouthFunnelUL`, `mouthFunnelUR`, `mouthFunnelDL`, `mouthFunnelDR`                         | `1.15` |
| `mouthLipsPurseUL`, `mouthLipsPurseUR`, `mouthLipsPurseDL`, `mouthLipsPurseDR`             | `1.15` |

该表导出为 `MHA_RECOMMENDED_GAINS`. `createMhaGainMask(overrides)` 会将其作为包含 251 个值的 `Float32Array` 返回，按帧顺序排列，并应用你的覆盖项。

### 让程序化动画控制眼睛

当应用程序自行控制眨眼或眼球运动时，两个写入器同时写入相同通道会导致闪烁。设置 `skipEyeChannels: true`，或者在自行写入帧时跳过 `MHA_EYE_CHANNEL_INDICES` 中的索引。这些索引涵盖以下通道： `eyeBlinkL`, `eyeBlinkR`, `eyeLookUpL`, `eyeLookUpR`, `eyeLookDownL`, `eyeLookDownR`, `eyeLookLeftL`, `eyeLookLeftR`, `eyeLookRightL`, `eyeLookRightR`, `eyeRelaxL`, `eyeRelaxR`, `eyeLowerLidUpL`，以及 `eyeLowerLidUpR`.

### 逐个使用辅助函数

处理器由一些辅助函数构成，你也可以单独调用它们：

| 辅助函数                           | 即可完全隐藏叠加层。                    |
| ------------------------------ | ----------------------------- |
| `applyMhaLimits(frame)`        | 就地应用耦合关系。                     |
| `symmetrizeMhaMouth(frame)`    | 就地对每一对左右口部和下颌通道取平均值。          |
| `createMhaGainMask(overrides)` | 按帧顺序返回各通道的增益。                 |
| `mhaChannelIndex(shortName)`   | 返回短通道名称对应的帧索引，或者 `undefined`. |

### 验证结果

播放一段回复，并观察发开口元音时嘴部的动作。

{% hint style="success" %}
下颌张开时，嘴唇仍贴近牙齿；只有在发宽元音时才会露出牙齿，嘴角则会同时向两侧移动。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/29f9aac19fcc2f8cd08338eeb8c9340da2c133cf" %}
[使用 blendshape 驱动面部动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/lipsync-and-blendshape.md)
{% endcontent-ref %}

{% content-ref url="/pages/4478f4a3cec9e37c9839b186fe7a71671f76fa3e" %}
[Blendshape 声道顺序参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript/mappings-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/22ae6f4a7ad0727295a752b42c53546668e69c5a" %}
[在 React 中添加口型同步](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/real-time-lipsync.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/web-plugins/convai-web-sdk/lipsync-and-blendshape/metahuman-limit-drivers-required-for-mha.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.
