配置对话输入模式

在免提语音激活和按住说话之间进行选择，并为你的项目配置触发按键或按钮。

Unity 的 Convai SDK 支持两种对话输入模式： 免手持 （玩家自然说话，SDK 检测其何时停止）以及 按键发言 （玩家按住按键说话）。这两种模式都在 ConvaiRoomManager 。

设置位置

选择 ConvaiManager 层级视图中的 GameObject。在检查器中找到 ConvaiRoomManager。 轮流发言选项 部分包含所有输入模式设置。

输入模式对比

	免手持	按键发言
工作原理	SDK 自动检测说话结束	玩家按住按键说话，松开后发送
最适合	自然对话、信息亭体验、VR	嘈杂环境、多人游戏、精确控制
延迟	稍高一些（静音检测延迟）	较低（松开按键即发送）
玩家操作成本	无	必须按住按键

免手持模式

免手持是默认模式。将 模式 为 HandsFree.

轮流检测

控制 SDK 如何判断玩家已说完。

将	默认值	描述
TurnDetection	UseDefault	UseDefault = 服务器默认值， 已禁用 = 始终开启的流， 自定义 = 在下方配置

当 TurnDetection 设置为 自定义，则 智能轮流设置 会显示：

将	默认值	描述
StopSecs	3.0	轮次结束前的静默秒数
MaxDurationSecs	8.0	强制结束前的最大轮次时长
PreSpeechMs	0	要包含的语音开始前音频毫秒数

增加 StopSecs 可让玩家在句子中途停顿更久而不会触发轮次结束。适用于学习者在回答前需要思考的训练模拟。

按键发言模式

设置 模式 为 PushToTalk。默认按键是 T — 可通过以下方式更改： _pushToTalkKey 于 ConvaiRoomManager.

本地音频策略

控制玩家设备上的麦克风行为。

将	默认值	描述
StartMutedInPushToTalk	true	麦克风启动时为静音；按下按键后激活
EnableAcousticEchoCancellation	false	为免提扬声器使用启用 AEC（Android/iOS）
PushToTalkStartupMode	PrewarmMuted	PrewarmMuted = 麦克风开启但从一开始就是静音； OpenOnFirstPress = 麦克风仅在首次按下按键时打开

按键发言策略

控制玩家按下并松开按键发言键时会发生什么。

将	默认值	描述
InterruptBotOnPress	true	在角色说话时按下按键会立即打断它
EnableServerSttToggle	true	在玩家未按住按键时，暂停服务器端 Convai 的语音转文字。可降低服务器处理成本；如果你发现按键时识别延迟，请禁用此项。
RequireTurnCompletionBeforeNextPress	true	玩家必须等待角色说完后才能再次发言
TurnCompletionTimeoutMs	5000	如果完成事件始终未到达，则用于解锁按键发言的备用超时（毫秒）
AllowSpeechStoppedFallbackAfterSpeechStart	false	允许在语音开始后，使用语音停止事件清除等待状态

运行时模式切换

SetConversationInputModeAsync() 切换当前已连接会话的活动输入模式 — 无需重新连接。切换会立即在实时会话中生效，并且不会修改已配置的默认值或房间配置文件资源。

using System.Threading;
using Convai.Runtime.Components;
using Convai.Runtime.Room;
using UnityEngine;

public sealed class InputModeSwitcher : MonoBehaviour
{
    // 切换到免手持 — 从 UI 按钮或游戏事件调用
    public async void SwitchToHandsFree()
    {
        await ConvaiManager.ActiveManager
            .SetConversationInputModeAsync(ConversationInputMode.HandsFree, CancellationToken.None)
            .AsTask();
    }

    // 切换到按键发言 — 从 UI 按钮或游戏事件调用
    public async void SwitchToPushToTalk()
    {
        await ConvaiManager.ActiveManager
            .SetConversationInputModeAsync(ConversationInputMode.PushToTalk, CancellationToken.None)
            .AsTask();
    }
}

要读取当前活动模式或响应更改：

using Convai.Runtime.Room;

// 读取当前模式
ConversationInputMode current =
    ConvaiManager.ActiveManager.ActiveConversationInputMode;

// 通过房间连接服务订阅更改
if (ConvaiManager.ActiveManager.TryGetRoomConnectionService(out IConvaiRoomConnectionService roomService))
    roomService.ConversationInputModeChanged += OnModeChanged;

void OnModeChanged(ConversationInputMode newMode)
{
    // 更新 UI、分析、教程提示等
}

SetConversationInputModeAsync() 仅在房间处于活动状态时有效 已连接。在房间处于 已断开连接, 连接中, 重新连接中，或 Disconnecting 时调用会以 SessionErrorCodes.SessionInvalidState。请检查 ConvaiManager.IsConnected 后再调用。

连接时的 TurnTakingOptions 定义会话的基础策略（自定义轮流检测阈值、按键发言启动行为、AEC 偏好）。运行时切换只会更改活动模式 — 其他所有选项都会沿用已连接会话的配置。

使用示例

示例 1：医学培训 — 带延长静默的免手持

场景： 护理专业学生回答情景问题时，经常会在思考时停顿，因此默认的 3 秒静默阈值会导致轮次过早结束。

在检查器中的设置：

• 模式： HandsFree
• TurnDetection： 自定义
• StopSecs： 5.0
• MaxDurationSecs： 30.0

预期结果： 学生在回答过程中最多可停顿 5 秒而不会结束轮次。角色会一直等到学生说完。

示例 2：工业现场检查 — 按键发言

场景： 嘈杂制造环境中的工人使用按键发言来避免误触语音激活。他们按下 T 来询问设备状态。

在检查器中的设置：

• 模式： PushToTalk
• _pushToTalkKey 在 ConvaiRoomManager 上： KeyCode.T
• InterruptBotOnPress: true （工人可以打断较长的回复并提出后续问题）
• EnableAcousticEchoCancellation: true （存在机器噪音）

预期结果： 只有有意的按键按下才会将音频发送给 Convai。背景噪音不会触发回应。工人可以通过再次按下按键来打断较长的回答。

示例 3：从过场动画切换到游戏玩法模式

场景： 一段引导过场动画使用免手持模式。游戏开始时，游戏会在不重新加载场景的情况下切换到按键发言。

public async void OnCinematicEnd()
{
    if (ConvaiManager.ActiveManager.IsConnected)
    {
        await ConvaiManager.ActiveManager
            .SetConversationInputModeAsync(ConversationInputMode.PushToTalk, CancellationToken.None)
            .AsTask();
    }
}

预期结果： 模式可在会话中无缝切换。角色继续运行，不会中断。按键发言控制会立即生效。

下一步

输入模式配置完成后，请调整角色语音音量和音频播放设置。

配置角色音频