> 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()` 作为公共运行时方法。这些操作现在只能在资源的检查器中运行——请参见 **填充映射条目** 下方。现有的映射资源仍可照常工作；只是从你自己的 C# 代码中调用这些操作的能力被移除了。
{% endhint %}

{% stepper %}
{% step %}

#### 创建资源

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

{% step %}

#### 配置顶层字段

选择新资源以在检查器中打开它，并展开 **配置** 部分。

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

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

{% step %}

#### 填充映射条目

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

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

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

**从映射文本：** 点击 **导入映射文件...** 以从磁盘加载映射文件，或者 **粘贴映射文本** 以导入剪贴板中已有的 JSON。两者都只接受规范的 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）                          |
| **启用**           | `true`  | 在不删除的情况下切换此条目的开关                               |
| **限制最小值**        | `0.0`   | 最小输出值（0–1）                                     |
| **限制最大值**        | `1.0`   | 最大输出值（0–1）                                     |
| **使用覆盖值**        | `false` | 启用时，总是写入 **覆盖值** 而不是流值                         |
| **覆盖值**          | `0.0`   | 在以下情况下写入的固定值 **使用覆盖值** 处于开启状态                  |
| **忽略全局修饰**       | `false` | 跳过 **全局乘数** 和 **全局偏移** 对此条目                    |
| {% endstep %}    |         |                                                |

{% step %}

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

在 `ConvaiLipSyncComponent` 检查器，将你的新映射资源拖入 **Mapping** 字段。

进入 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.