> 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 通道（来自传输流）路由到你角色上的实际 blendshape 名称 `SkinnedMeshRenderer`。当你的绑定使用的 blendshape 名称与捆绑的直通映射所预期的不同时，或者当你需要为特定角色调整权重时，请创建自定义映射。

{% stepper %}
{% step %}

#### 创建资源

在 Project 窗口中，导航到你想存储该映射的文件夹。右键单击并选择 **Create > Convai > Lip Sync > Lip Sync Map**。为资源起一个具有描述性的名称——例如， `ConvaiLipSyncMap_MyRig_FromARKit`.
{% endstep %}

{% step %}

#### 配置顶层字段

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

| 字段         | 默认    | 说明                                                                                                               |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------------- |
| **目标配置文件** | *（无）* | 列出此映射所针对的已注册唇形同步配置文件的弹出列表（例如， `arkit`, `MetaHuman`，或你的自定义配置文件）。如果没有注册任何配置文件，Inspector 会回退为一个 **目标配置文件 ID** 文本字段。 |
| **说明**     | *（空）* | 可选的设计备注——运行时不使用                                                                                                  |

下方 **说明**，一个 **全局修饰器** 小节分为三个字段：

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

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

{% step %}

#### 填充映射条目

展开 **工具** 部分即可添加映射条目。每个映射操作——清空、初始化默认值，以及从网格自动检测——都在 Inspector 中执行。

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

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

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

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

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

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

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

| 条目字段             | 默认      | 说明                                             |
| ---------------- | ------- | ---------------------------------------------- |
| **源 Blendshape** | *（空）*   | 通道从 Convai 传入时的名称（例如， `jawOpen`)               |
| **目标名称**         | *（空列表）* | 你角色上的 blendshapes 名称 `SkinnedMeshRenderer` 以驱动 |
| **乘数**           | `1.0`   | 在全局乘数之前应用于每个条目的缩放（0–5）                         |
| **偏移量**          | `0.0`   | 每个条目的偏移量（-1–1）                                 |
| **响应曲线**         | `1.0`   | 在缩放前应用于输入值的指数（0.25–4）                          |
| **已启用**          | `true`  | 在不删除的情况下切换此条目的启用或禁用                            |
| **最小夹紧值**        | `0.0`   | 最小输出值（0–1）                                     |
| **最大夹紧值**        | `1.0`   | 最大输出值（0–1）                                     |
| **使用覆盖值**        | `false` | 启用后，始终写入 **覆盖值** 而不是流值                         |
| **覆盖值**          | `0.0`   | 当……时写入的固定值 **使用覆盖值** 处于开启状态                    |
| **忽略全局修饰器**      | `false` | 跳过 **全局修饰器** **乘数** 和 **偏移量** 对于此条目的           |

**批量操作：** 展开 **批量操作** 部分（默认折叠）可一次性将更改应用于所有映射条目，而不是逐个编辑：

| 按钮                  | 效果                                                                              |
| ------------------- | ------------------------------------------------------------------------------- |
| **全部启用** / **全部禁用** | 将……设置为 **已启用** 在每个条目上                                                           |
| **重置乘数**            | 将每个条目的 **乘数** 改回 `1.0`                                                          |
| **重置偏移量**           | 将每个条目的 **偏移量** 改回 `0.0`                                                         |
| **重置曲线**            | 将每个条目的 **响应曲线** 改回 `1.0`                                                        |
| **仅启用眼部**           | 启用其源 blendshape 名称匹配眼部相关关键词的条目（`Eye`, `Blink`, `Look`, `Squint`, `Wide`）并禁用其余条目 |
| **仅启用口部**           | 启用其源 blendshape 名称匹配口部相关关键词的条目（`Mouth`, `Jaw`, `Lip`, `Smile`, `Frown`）并禁用其余条目  |
| **仅启用眉部**           | 启用其源 blendshape 名称匹配 `Brow` 并禁用其余条目                                             |
| {% 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`
* 目标配置文件： `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 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-unity-sdk/getting-started/add-lip-sync/create-a-custom-blendshape-map.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.