> 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 通道路由到角色的网格，并可按通道调整权重和钳制参数。

口型同步映射会将源混合形状通道（来自传输流）路由到角色上的实际混合形状名称 `SkinnedMeshRenderer`。当您的绑定使用的混合形状名称与随附直通映射所预期的名称不同时，或需要针对特定角色调整权重时，请创建自定义映射。

{% stepper %}
{% step %}

#### 创建资源

在“项目”窗口中，导航到要存储映射的文件夹。右键单击并选择 **创建 > Convai > 口型同步 > 口型同步映射**。为资源命名一个描述性名称——例如， `ConvaiLipSyncMap_MyRig_FromARKit`.
{% endstep %}

{% step %}

#### 配置顶级字段

选择新资源以在“检视器”中打开它，然后展开 **配置** 部分。

| 字段         | 默认    | 说明                                                                                                         |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| **目标配置文件** | *（无）* | 弹出菜单，列出此映射所针对的已注册口型同步配置文件（例如， `arkit`, `metahuman`，或您的自定义配置文件）。如果没有注册配置文件，“检视器”将改为使用一个 **目标配置文件 ID** 文本字段。 |
| **说明**     | *（空）* | 可选的设计者备注——运行时不使用                                                                                           |

在 **说明**下方，有一个 **全局修饰器** 子标题，其中包含三个字段：

| 字段         | 默认    | 说明                     |
| ---------- | ----- | ---------------------- |
| **乘数**     | `1.0` | 在写入前应用于所有输出权重的缩放       |
| **偏移量**    | `0.0` | 添加到所有输出权重的偏移量          |
| **允许未映射项** | `是`   | 没有显式映射条目的通道将直接使用其源名称写入 |

{% hint style="info" %}
**允许未映射项** 当您的大多数混合形状名称与源通道匹配时很有用——您只需为不同的名称添加条目。未映射的通道会直接使用其源名称写入。
{% endhint %}
{% endstep %}

{% step %}

#### 填充映射条目

展开 **工具** 部分，在同一“检视器”中添加映射条目。所有映射操作——清除、初始化默认值以及从网格自动检测——均在“检视器”中运行。

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

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

**从映射文本：** 点击 **导入映射文件...** 以从磁盘加载映射文件，或 **粘贴映射文本** 以导入剪贴板中已有的 JSON。两者均只接受规范的版本 1 映射 JSON——即包含 `"version": 1`下方，有一个 `映射` 数组，且字段名称与资源序列化条目中的字段名称相同：

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

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

**其他映射操作：** **初始化默认值** 清除所有现有映射，并为资源的每个已知源通道创建一个启用的直通条目 **目标配置文件** ——每个条目的 **目标名称** 会设置为源通道自身的名称。 **全部清除** 删除所有映射条目。 **按 A-Z 排序** 按源通道以字母顺序重新排列条目。 **+ 添加条目** 添加一个空白条目以供手动编辑。

每个条目——无论以何种方式添加——都会将一个源通道映射到一个或多个目标混合形状名称，并包含以下字段：

| 条目字段        | 默认      | 说明                                      |
| ----------- | ------- | --------------------------------------- |
| **源混合形状**   | *（空）*   | 从 Convai 到达的通道名称（例如， `jawOpen`)         |
| **目标名称**    | *（空列表）* | 您的角色上的混合形状名称 `SkinnedMeshRenderer` 用于驱动 |
| **乘数**      | `1.0`   | 在全局乘数之前应用的每条目缩放（0–5）                    |
| **偏移量**     | `0.0`   | 每条目偏移量（-1–1）                            |
| **响应曲线**    | `1.0`   | 在缩放前应用于输入值的指数（0.25–4）                   |
| **已启用**     | `是`     | 在不删除此条目的情况下将其打开或关闭                      |
| **钳制最小值**   | `0.0`   | 最小输出值（0–1）                              |
| **钳制最大值**   | `1.0`   | 最大输出值（0–1）                              |
| **使用覆盖值**   | `否`     | 启用后，始终写入 **覆盖值** 而非流值                   |
| **覆盖值**     | `0.0`   | 当 **使用覆盖值** 开启时写入的常量值                   |
| **忽略全局修饰器** | `否`     | 跳过 **全局修饰器** **乘数** 和 **偏移量** 对此条目      |

**批量操作：** 展开 **批量操作** 部分（默认折叠），以便一次性对每个映射条目应用更改，而不是逐一编辑：

| 按钮                  | 效果                                                           |
| ------------------- | ------------------------------------------------------------ |
| **全部启用** / **全部禁用** | 设置 **已启用** 在每个条目上                                            |
| **重置乘数**            | 将每个条目的 **乘数** 重置为 `1.0`                                      |
| **重置偏移量**           | 将每个条目的 **偏移量** 重置为 `0.0`                                     |
| **重置曲线**            | 将每个条目的 **响应曲线** 重置为 `1.0`                                    |
| **仅启用眼部**           | 启用源混合形状名称与眼部相关关键字匹配的条目（`眼睛`, `眨眼`, `注视`, `眯眼`, `睁大`），并禁用其余条目 |
| **仅启用嘴部**           | 启用源混合形状名称与嘴部相关关键字匹配的条目（`嘴`, `下颌`, `嘴唇`, `微笑`, `皱眉`），并禁用其余条目  |
| **仅启用眉部**           | 启用源混合形状名称与以下内容匹配的条目 `眉` 并禁用其余条目                              |
| {% endstep %}       |                                                              |

{% step %}

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

在 `ConvaiLipSyncComponent` 在“检视器”中，将您的新映射资源拖入 **映射** 字段中。

进入播放模式并对角色说话。所有已映射的混合形状都会动画化。检查 Unity 控制台中是否有关于未解析混合形状名称的警告。
{% endstep %}
{% endstepper %}

### 使用示例

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

**场景：** 一个模拟角色由艺术家绑定，其使用了 snake\_case 名称（`jaw_open`, `mouth_smile_left`）而非 ARKit 标准的 camelCase 名称（`jawOpen`, `mouthSmileLeft`).

**设置：**

* 创建 `ConvaiLipSyncMap_CustomRig_FromARKit.asset`
* 目标配置文件： `arkit`
* 允许未映射项： `否` （所有名称均不同）
* 为每个混合形状添加条目：

| 源混合形状             | 目标名称                |
| ----------------- | ------------------- |
| `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.