添加口型同步

将 Convai 音频输出连接到角色的面部 BlendShape，同步口部动作与语音，并调整播放延迟。

Convai 的 Unity 版 SDK 包含一个实时口型同步系统，用于驱动 SkinnedMeshRenderer 与角色的语音音频同步的 blendshape。它支持三种行业标准的 blendshape 格式，并自动处理播放缓冲、平滑和淡出。

工作原理

当 Convai 发送语音音频时，它还会以角色的传输格式（ARKit、MetaHuman 或 CC4 Extended）流式传输一系列 blendshape 帧。SDK 会缓冲并插值这些帧，应用可选的平滑，并将结果写入角色的 SkinnedMeshRenderer 每一帧。

如果同一角色还拥有另一个驱动面部 blendshape 的模块——例如情绪控制器——Convai 会在内部将口型同步输出与该模块的输出合成后再写入网格，而不是让两者独立写入。默认的平衡会把嘴部几乎完全交给 ConvaiLipSyncComponent 在角色说话时。若角色上没有其他面部输出模块， ConvaiLipSyncComponent 会像上面所示直接写入目标网格。

快速设置

1

添加该组件

添加 ConvaiLipSyncComponent 添加到与您的 ConvaiCharacter 相同的 GameObject 上（或任意子 GameObject 上）。

2

设置 profile ID

在 Inspector 中，设置 锁定的 Profile ID 为角色使用的传输格式：

• arkit — Apple ARKit（61 个 blendshape）
• metahuman — Unreal MetaHuman（251 个 blendshape）
• cc4_extended — Character Creator 4 Extended（170 个 blendshape）

3

分配目标网格

在 目标网格 列表中，添加所有 SkinnedMeshRenderer 包含面部 blendshape 的组件。

4

进入播放模式

将 映射 留空——SDK 会自动为所选 profile 选择匹配的内置映射。进入 Play Mode 并与角色说话。

角色的嘴部会与其语音输出同步移动。

如果嘴部没有移动，请确认你的 SkinnedMeshRenderer blendshape 名称与所选 profile 的预期命名规范一致。ARKit 使用驼峰式名称（例如 jawOpen, mouthSmileLeft）。MetaHuman 使用 CTRL_expressions_ 前缀。如果你的绑定使用不同的名称，请使用自定义映射——参见 Profile 和映射.

内置 Profile

选择与角色绑定时所用 blendshape 格式相匹配的 profile。

Profile	锁定的 Profile ID	Blendshape	典型角色来源
ARKit	arkit	61	Apple 绑定的角色，部分自定义绑定
MetaHuman	metahuman	251	导出到 Unity 的 Unreal MetaHuman
CC4 Extended	cc4_extended	170	Reallusion Character Creator 4 角色

如果你的角色绑定使用非标准的 blendshape 名称，请创建自定义映射，将 SDK 的输出通道路由到绑定的实际名称。

配置文件与映射

播放设置

核心设置：

字段	默认	说明
_lockedProfileId	arkit	SDK 流式传输的传输格式（arkit, metahuman, cc4_extended)
_mapping	（无）	可选的自定义映射资源（留空则使用内置自动映射）
_targetMeshes	（空列表）	SkinnedMeshRenderer 用于写入 blendshape 的组件

播放与行为：

字段	默认	范围	说明
_smoothingFactor	0.5	0–0.9	每帧指数平滑（越高 = 越平滑但越慢）
_fadeOutDuration	0.2	0.05–2.0	当响应被中断或取消时，将所有 blendshape 淡出到 0 所需的秒数
_settleDuration	0.35	0.1–1.0	角色最后一个词结束后，嘴部恢复静止所需的秒数；它会延续动画已经留下的运动，而不是直接截断。参见 响应结束的方式.
_fadeInDuration	0.1	0–0.5	播放开始时，从播放前姿势过渡到首批采样帧所需的秒数，以消除响应开始时的首帧突变（0 会禁用它）
_timeOffset	0.0	-0.5–0.5	相对于音频调整播放时序（负值 = 更早）

流式传输与延迟：

字段	默认	范围	说明
_latencyMode	平衡	—	控制缓冲深度与响应速度的预设
_maxBufferedSeconds	3.0	1–10	环形缓冲区容量（秒）
_minResumeHeadroomSeconds	0.12	0.05–0.3	缓冲耗尽后的重新填充阈值
_deliverChunksAhead	否	—	用于索引 NeuroSync 分块的预览开关

延迟模式选项：

模式	使用场景
平衡	默认。建议用于大多数部署
超低延迟	延迟最低；在不稳定连接上容易出现缓冲耗尽
网络安全	高缓冲；最适合不可靠或高延迟网络
Custom	解锁对上述缓冲字段的手动控制

响应结束的方式

当响应正常结束时，嘴部会在 恢复静止时长 (0.35 秒）而不是突然闭合或保持最后的形状。闭合会延续最后几帧已经在进行的动作——下颌如果还在上抬，就会平滑地回落，不会出现明显的折角；如果已经在闭合，就会继续闭合。这与 Fade Out Duration不同，后者是在响应被中断或取消、而不是自然结束时使用的更快切断。

如果你直接驱动 LipSyncPlaybackEngine 而不是通过 ConvaiLipSyncComponent，请调用 SettleToRest() 从你自己的代码触发同样的收拢效果，并读取 IsSettling 来检查当前的淡出是否是收拢，而不是定时切断。

提前分块投递预览

Ahead Chunk Delivery（预览） 使 SDK 能够在索引 NeuroSync 分块的播放位置之前请求它们。普通项目请保持禁用。仅当你在测试已经使用 ConvaiLipSyncComponent.

当 _deliverChunksAhead 已启用时，SDK 会发送 deliver_chunks_ahead=true 到房间连接的口型同步配置中。默认请求不包含此字段，因此除非你开启预览选项，否则现有口型同步行为保持不变。

SDK 会按帧索引缓存提前分块，并等待这些帧从响应开始处连续后再开始把它们送入播放引擎。视觉输出仍会等待角色音频播放信号，因此在可听语音开始之前嘴部不会开始移动。如果 Convai 取消当前 NeuroSync 时间线，或因为中断而结束角色轮次，SDK 会在下一次响应前清空已缓存的嘴部帧。

使用示例

示例 1：ARKit 角色

场景： 一个企业培训模拟使用了由 Apple ARKit blendshape 绑定的角色。

设置：

1. 添加 ConvaiLipSyncComponent 添加到 NPC GameObject（与 ConvaiCharacter).
2. 设置 _lockedProfileId 移动到 arkit.
3. 在 目标网格 列表中，添加 SkinnedMeshRenderer 来自 avatar 头部网格的
4. 将 _mapping 留空——内置的 ARKit 自动映射覆盖标准驼峰式 ARKit blendshape 名称（jawOpen, mouthSmileLeft，等等）。

预期结果： 头像的嘴唇和下颌会在对话期间与角色的语音同步动画。每次响应结束后，嘴部都会平滑地恢复静止（_settleDuration = 0.35 秒默认）。

示例 2：MetaHuman 角色

场景： 一个高保真医疗模拟使用了导出到 Unity 的 Unreal MetaHuman 角色。

设置：

1. 添加 ConvaiLipSyncComponent 添加到 NPC GameObject。
2. 设置 _lockedProfileId 移动到 metahuman.
3. 在 目标网格 列表中，添加所有 SkinnedMeshRenderer MetaHuman 头部和牙齿网格上的组件——MetaHuman 将它们分成多个渲染器。
4. 将 _mapping 留空——内置的 MetaHuman 映射针对 CTRL_expressions_ 带前缀的 blendshape。
5. 提高 _smoothingFactor 移动到 0.7 以在高多边形绑定上获得更流畅的动画。

预期结果： 所有面部区域都会一起动画——嘴唇、下颌、脸颊和舌头形状——产生高度逼真的嘴部运动。平滑会减少高分辨率网格上可见的逐帧抖动。

下一步

配置好口型同步后，选择玩家如何与角色对话。

配置对话输入模式

或者探索 Features 部分，为你的角色添加 Actions、Emotion、Long-Term Memory 或 Vision。

功能

查阅 Core Concepts，以更深入地理解会话生命周期和事件系统。

核心概念