> 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-unity-sdk/getting-started/add-lip-sync/create-a-custom-blendshape-map.md).

# 创建自定义唇形同步映射

口型同步映射会将源 blendshape 通道（来自传输流）路由到你角色的实际 blendshape 名称上 `SkinnedMeshRenderer`。当你的绑定使用的 blendshape 名称与内置直通映射所预期的不同时，或者你需要为特定角色调整权重时，请创建自定义映射。

{% hint style="warning" %}
从 SDK 4.4.0 起， `ConvaiLipSyncMapAsset` 不再公开 `ClearMappings()`, `InitializeWithDefaults()`，或 `AutoDetectFromMeshes()` 作为公共运行时方法。这些操作现在只能从资源的 Inspector 中运行——请参见 **填充映射条目** 下方。现有的映射资源仍可照常工作；移除的只是从你自己的 C# 代码中调用这些操作的能力。
{% endhint %}

{% stepper %}
{% step %}

#### 创建资源

在 Project 窗口中，导航到你想存储该映射的文件夹。右键单击并选择 **创建 > Convai > 口型同步 > 口型同步映射**。请用描述性的名称为资源命名——例如， `ConvaiLipSyncMap_MyRig_FromARKit`.
{% endstep %}

{% step %}

#### 配置顶层字段

选中新资源以在 Inspector 中打开它，并展开 **配置** 部分。

| 字段            | 默认值    | 描述                                                     |
| ------------- | ------ | ------------------------------------------------------ |
| **目标配置文件 ID** | *（空）*  | 此映射所针对的配置文件 ID（例如， `arkit`, `metahuman`，或你的自定义配置文件 ID） |
| **描述**        | *（空）*  | 可选的设计备注——运行时不使用                                        |
| **全局倍率**      | `1.0`  | 在写入前应用于所有输出权重的缩放系数（0–3）                                |
| **全局偏移**      | `0.0`  | 添加到所有输出权重的偏移量（-1–1）                                    |
| **允许未映射直通**   | `true` | 没有显式映射条目的通道将直接使用其源名称写入                                 |

{% hint style="info" %}
**允许未映射直通** 当你的大多数 blendshape 名称都与源通道匹配时，这很有用——你只需为不匹配的那些添加条目。未映射的通道会直接使用其源名称写入。
{% endhint %}
{% endstep %}

{% step %}

#### 填充映射条目

展开 **工具** 部分，在同一个 Inspector 中添加映射条目。此部分取代了运行时的 `ClearMappings()`, `InitializeWithDefaults()`，以及 `AutoDetectFromMeshes()` 早期 SDK 版本中使用的调用——现在每个映射操作都从 Inspector 中运行。

**从网格：** 添加一个或多个 `SkinnedMeshRenderer` 在……下的引用 **预览网格**，然后点击 **从网格自动检测** 并选择匹配模式：

| 匹配模式         | 行为                                                                    |
| ------------ | --------------------------------------------------------------------- |
| **精确匹配**     | 要求源通道与网格 blendshape 之间名称完全相同（不区分大小写）                                  |
| **包含匹配（推荐）** | 当找不到精确匹配时，回退到子字符串匹配                                                   |
| **模糊匹配**     | 在去除常见绑定工具前缀后再进行匹配（例如 `CTRL_expressions_`, `bs_`, `CC_Base_`）当包含匹配也失败时 |

**从映射文本：** 点击 **导入映射文件...** 从磁盘加载映射文件，或者 **粘贴映射文本** 导入剪贴板中已有的 JSON。二者仅接受规范的 version-1 映射 JSON——即一个包含以下内容的 JSON 对象： `"version": 1`、一个 `mappings` 数组，并且字段名与资源的序列化条目相同：

```json
{
  "version": 1,
  "targetProfileId": "arkit",
  "mappings": [
    {
      "sourceBlendshape": "jawOpen",
      "targetNames": ["jaw_open"],
      "multiplier": 1.0
    }
  ]
}
```

使用 **复制映射 JSON** 以相同格式导出当前资源的映射，例如在资源之间共享映射，或将其以文本形式提交到版本控制中。

**其他映射操作：** **初始化默认值** 会清除所有现有映射，并为该资源的每个已知源通道创建一条禁用条目 **目标配置文件 ID**. **全部清除** 移除所有映射条目。 **按 A-Z 排序** 按源通道字母顺序重新排序条目。 **+ 添加条目** 添加一个空白条目以便手动编辑。

每个条目——无论如何添加——都会将一个源通道映射到一个或多个目标 blendshape 名称，包含以下字段：

| 条目字段             | 默认值     | 描述                                             |
| ---------------- | ------- | ---------------------------------------------- |
| **源 Blendshape** | *（空）*   | 通道从 Convai 传入时的名称（例如， `jawOpen`)               |
| **目标名称**         | *（空列表）* | 你角色上的 blendshape 名称 `SkinnedMeshRenderer` 用于驱动 |
| **倍率**           | `1.0`   | 在全局倍率之前应用于每个条目的缩放系数（0–5）                       |
| **偏移**           | `0.0`   | 每个条目的偏移量（-1–1）                                 |
| **响应曲线**         | `1.0`   | 在缩放前应用于输入值的指数（0.25–4）                          |
| **Enabled**      | `true`  | 在不删除的情况下切换此条目的启用或禁用                            |
| **最小值钳制**        | `0.0`   | 最小输出值（0–1）                                     |
| **最大值钳制**        | `1.0`   | 最大输出值（0–1）                                     |
| **使用覆盖值**        | `false` | 启用后，总是写入 **覆盖值** 而不是流值                         |
| **覆盖值**          | `0.0`   | 在……时写入的常量值 **使用覆盖值** 已启用                       |
| **忽略全局修饰**       | `false` | 跳过 **全局倍率** 和 **全局偏移** 此条目的                    |
| {% endstep %}    |         |                                                |

{% step %}

#### 将映射分配给组件

在 `ConvaiLipSyncComponent` Inspector，在其中将你的新映射资源拖入 **映射** 字段。

进入 Play Mode 并对角色说话。所有已映射的 blendshape 都会动起来。请检查 Unity Console 中是否有关于无法解析的 blendshape 名称的警告。
{% endstep %}
{% endstepper %}

### 使用示例

#### 示例 1：从 ARKit 流到自定义绑定

**场景：** 某个模拟角色由一位使用 snake\_case 命名（`jaw_open`, `mouth_smile_left`）的美术进行了绑定，而不是使用 ARKit 标准的 camelCase 名称（`jawOpen`, `mouthSmileLeft`).

**设置：**

* 创建 `ConvaiLipSyncMap_CustomRig_FromARKit.asset`
* 目标配置文件 ID： `arkit`
* 允许未映射直通： `false` （所有名称都不同）
* 为每个 blendshape 添加条目：

| 源 blendshape      | 目标名称                |
| ----------------- | ------------------- |
| `jawOpen`         | `jaw_open`          |
| `mouthSmileLeft`  | `mouth_smile_left`  |
| `mouthSmileRight` | `mouth_smile_right` |
| *（对所有需要的通道继续）*    |                     |

**预期结果：** 尽管使用的命名约定与 ARKit 标准不同，角色的嘴部仍能正确动画。

#### 示例 2：降低下颌运动强度

**场景：** 某个 AI 接待员角色在说话时下颌张得太大，看起来不自然。

**设置：**

* 复制随附的 `ConvaiLipSyncDefaultMap_ARKit.asset` 并将其重命名为
* 找到 `jawOpen` 条目
* 将 **倍率** 到 `0.6` 和 **最大值钳制** 到 `0.7`

**预期结果：** 角色的下颌张开幅度只有原始流值的 60–70%，从而使嘴部运动更克制、更自然。

### 下一步

配置好口型同步后，请验证你的完整场景设置。

{% content-ref url="/pages/21a0b0c11649e9125ef5195167e66c3a2caaadf1" %}
[验证您的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync/create-a-custom-blendshape-map.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.