配置对话输入

在按住说话和免手持语音采集模式之间切换，调节 VAD 设置，并在没有麦克风的情况下向角色发送文本消息。

UConvaiPlayerComponent 支持三种输入模式。请查看下面的比较，选择最适合你的交互设计的模式，然后按照该模式的选项卡进行操作。

输入模式比较

	按住说话	免按键	发送文本
工作原理	玩家按住一个键来传输语音。	语音活动检测自动触发。	文本字符串直接发送给聊天机器人。
适用于	可控输入、游戏 UX、共享麦克风场景。	环境型 NPC、自助终端安装、始终在线体验。	无障碍功能、文本聊天界面、自动化测试。
需要麦克风	是	是	否
默认值	是 — 启用按住说话 为 true 在 BP_ConvaiPlayerComponent 在 详细信息 面板	否 — 禁用 启用按住说话 或调用 UpdateVadBP(true)	否 — 调用 SendText() 根据需要。
配置位置	详细信息 面板中 BP_ConvaiPlayerComponent 在……下的 Convai 类别，或者 Blueprint 节点	相同 详细信息 面板 — 设置 启用按住说话 到 false，或者调用 UpdateVadBP(true)	蓝图 SendText() 节点

配置你的模式

在 BP_ConvaiPlayerComponent，打开 详细信息 面板并展开 Convai 类别。该 启用按住说话 复选框控制默认输入模式：

• 启用按住说话 选中（true）— 按住说话已启用。
• 启用按住说话 未选中（false）— 免按键（VAD）模式已启用。

你可以在……中更改此项 详细信息 面板中无需编辑 Blueprint 图，就能更改此项，或者按照下方每个选项卡所述，使用 Blueprint 节点在运行时覆盖它。

按住说话

按住说话是默认模式。玩家按住一个键即可流式传输语音输入；松开按键则停止传输。

BP_ConvaiPlayerComponent 随附按住说话输入，并在其 Blueprint 图中预先接好了默认说话键。要更改按键，请打开玩家 Pawn Blueprint，选择 BP Convai Player 组件，然后在组件的事件图中编辑输入绑定——或者用你自己的输入动作替换默认绑定。

你也可以设置 启用按住说话 到 true 在 详细信息 面板下的 Convai 类别，以确认按住说话模式已启用。

要手动连接按住说话，请调用：

函数	返回	描述
UnmuteStreamingAudio()	bool — true 如果已开始流式传输。	开始将麦克风音频流式传输到当前聊天机器人。在按键按下时调用。
MuteStreamingAudio()	void	停止音频流式传输。在按键松开时调用。

在玩家 Pawn 的 Blueprint 事件图中，将这些与你的输入动作连接起来。

你也可以在不更改模式的情况下切换静音：将……设置为 bMute 上的属性 UConvaiPlayerComponent 到 true 以使输入静音，并将 false 设置为以恢复它。

免按键

发送文本

微调语音活动检测

免按键模式使用语音活动检测（VAD）来判断玩家何时开始和停止说话。默认 VAD 设置在大多数环境下都能正常工作。如果角色会被背景噪音触发，或者漏掉较轻的说话声，请调整 FConvaiVADSettings 结构体。

访问 VAD 设置

使用以下可从……调用的 Blueprint 函数 UConvaiUtils （无需组件引用——可将其作为工具函数调用）：

函数	类别	描述
GetVADSettings()	Convai|Settings	返回当前的 FConvaiVADSettings 结构体。BlueprintPure。
SetVADSettings(VADSettings)	Convai|Settings	将新的 FConvaiVADSettings 应用于 VAD 管线。

VAD 设置字段

字段	类型	默认值	描述
bUseServerDefault	bool	true	当 true，则使用服务器的默认 VAD 参数，所有其他字段都会被忽略。设置为 false 以应用本地覆盖。
Confidence	float	0.7	语音置信度阈值（0.0–1.0）。数值越高，角色开始监听前所需的确定性越高。提高此值可减少背景噪音造成的误触发。
StartSecs	float	0.2	监听器激活前所需的连续说话秒数。提高此值可避免被很短的声音触发。
StopSecs	float	2.2	监听器关闭音频流前的静默秒数。提高此值可避免对句中停顿的说话者过早截断。
MinVolume	float	0.6	被视为语音的最低音量级别（0.0–1.0）。提高此值可过滤较轻的环境噪音。

设置 bUseServerDefault 到 false 在设置任何其他字段之前——否则服务器会忽略所有本地值。你也可以在整个项目范围内在……中配置 VAD 默认值 Edit > Project Settings > Plugins > Convai > Audio Settings | VAD （从插件版本 4.0.0-beta.20 起可用）。

录制和状态检查

对于希望在发送前先捕获完整音频片段的工作流——而不是实时流式传输——请使用录制 API：

函数	返回	描述
StartRecording()	void	开始将麦克风音频录制到缓冲区中。
FinishRecording()	USoundWave*	停止录制，并将捕获的音频作为 Sound Wave 资源返回。

你可以处理或播放返回的 USoundWave，或者将其传递给其他 Blueprint。此路径与流式传输管线是分开的，并且不会与当前聊天机器人会话交互。

若要随时检查流式传输和录制状态：

函数	返回	描述
GetIsStreaming()	bool	true 音频正在流式传输到聊天机器人时。
GetIsRecording()	bool	true 手动录制进行中时。

有关内置聊天覆盖层、3D 场景内小部件以及连接自定义转录 UI 的完整详情，请参阅 添加聊天 UI.

故障排查

免按键模式会被背景噪音触发

症状： 当无人说话时，角色开始监听——环境声音、键盘点击声或音乐都会触发它。

原因： VAD Confidence 或 MinVolume 阈值对于当前环境来说太低了。

修复： 调用 GetVADSettings()，将……设为 bUseServerDefault 到 false，提高 Confidence （试试 0.85–0.95）并提高 MinVolume 高于默认值 0.6 （试试 0.7–0.8），然后通过 SetVADSettings().

验证： 在安静的环境中进入 Play 模式，并确认角色不再被环境噪音触发。

免按键模式会在玩家说到一半时中断

症状： 当玩家仍在说话时，角色就中断了监听——这在说话时思路之间会停顿的人身上很常见。

原因： StopSecs 对

修复： 调用 GetVADSettings()，将……设为 bUseServerDefault 到 false，增加 StopSecs 高于默认值 2.2 （试试 3.0–4.0 秒），然后通过 SetVADSettings().

验证： 说话时自然停顿，并确认角色会等你说完。

按住说话没有响应

症状： 玩家按住按键并说话，但角色始终没有响应。

原因： UnmuteStreamingAudio() 未连接到按键按下事件，或者 bMute 为 true 在玩家组件上。

修复： 请确认你的输入动作调用了 UnmuteStreamingAudio() 在按键按下时调用，并在 MuteStreamingAudio() 在按键松开时调用。请确认 bMute 为 false 在 详细信息 面板。

验证： 按住按住说话按键，说话，并确认 GetIsStreaming() 返回 true.

下一步

添加聊天 UI验证你的设置