轮流发言模式

TurnTakingOptions、SmartTurnSettings 和 PushToTalkPolicy 的参考——用于免提语音检测和按住说话模式的字段说明。

轮流发言决定谁说话、轮次何时结束，以及 SDK 如何处理用户发言与角色回应之间的过渡。SDK 支持两种模式：免手持自动检测和明确的按住说话。选择合适的模式——并正确调优——会直接影响你的训练模拟、交互体验或游戏中的对话自然度和可靠性。

有关基于 Inspector 的设置步骤，请参见 配置对话输入模式。本页是完整的字段参考。

---

模式对比

模式	ConversationInputMode 值	最适合
免手持	HandsFree (0)	具有自然对话、环境交互、优先无障碍体验的训练模拟
按住说话	PushToTalk (1)	嘈杂环境、工厂安全演练、必须防止误触发的场景

---

TurnTakingOptions — 根字段

TurnTakingOptions 是顶层配置对象。将其设置在 ConvaiRoomManager 的 Inspector 中（内联），或通过一个 ConvaiRoomManagerProfile 资源，或将其传递给 RoomSessionConnectOptions 以覆盖单次连接的设置。

字段	类型	默认值	说明
模式	ConversationInputMode	HandsFree	为此会话设置活动对话模式。
TurnDetection	TurnDetectionMode	UseDefault	控制自动轮次结束检测。仅适用于免手持模式。
CustomTurnDetection	SmartTurnSettings	见下文	精细调优的智能轮次参数。仅在 TurnDetection 为 自定义.
InitialServerStt	ServerSttInitialState	UseDefault	控制会话开始时是否启用后端语音转文本。
LocalAudioPolicy	LocalAudioPolicy	见下文	此设备上的麦克风行为。适用于两种模式。
PushToTalkPolicy	PushToTalkPolicy	见下文	按住说话交互规则。仅适用于 PushToTalk 模式。

---

免手持模式

在免手持模式下，SDK 会持续采集麦克风音频，并检测用户何时说完。无需按按钮。

TurnDetectionMode

控制如何检测轮次结束。

值	行为
UseDefault	Convai 默认的服务器端语音活动检测。适用于大多数情况。
已禁用	无自动轮次检测。SDK 不会自动结束用户轮次。仅当你完全在代码中管理轮次过渡时使用。
自定义	使用 SmartTurnSettings 以自行配置检测参数。

SmartTurnSettings

在 TurnDetection 被设置为 自定义.

字段	类型	默认值	说明
StopSecs	float	3.0	SDK 结束用户轮次前所需的静音秒数。降低可更快响应；在嘈杂环境中提高。
PreSpeechMs	int	0	在检测到语音起点之前，需包含到捕获轮次中的音频毫秒数。如果轮次的第一个词经常被截断，可增加此值。
MaxDurationSecs	float	8.0	单次用户轮次的硬性上限（秒）。无论用户是否停止说话，轮次都会结束。

var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.HandsFree,
    TurnDetection = TurnDetectionMode.Custom,
    CustomTurnDetection = new SmartTurnSettings
    {
        StopSecs = 2.0f,       // 医疗评估流程中更快的响应
        PreSpeechMs = 100,
        MaxDurationSecs = 10.0f
    }
};

设置 StopSecs 过低会在用户句中停顿时导致轮次过早结束。在学习者思考后再回答的训练模拟中，请将 StopSecs 保持在 2.5 或更高。

---

按住说话模式

在按住说话模式下，用户通过按下和释放一个控件（按钮、按键或 UI 元素）明确地开始和结束自己的轮次。SDK 不使用语音活动检测来结束轮次。

PushToTalkPolicy

控制所有按住说话交互规则。将 RequireTurnCompletionBeforeNextPress = true 用于大多数训练模拟——它会强制自然的对话节奏，让角色先说完，学习者再回应。

字段	类型	默认值	说明
EnableServerSttToggle	bool	true	在按住说话控件被按下和释放时，静音和取消静音后端语音转文本。可降低服务器成本，并防止意外处理背景音频。
InterruptBotOnPress	bool	true	如果角色在用户按下按住说话时正在讲话，角色会立即被打断，以便用户开始发言。
RequireTurnCompletionBeforeNextPress	bool	true	用户必须等角色完整回答结束后，才能再次按下按住说话。防止轮次重叠。
TurnCompletionTimeoutMs	int	5000	回退超时（毫秒）。如果角色的轮次完成事件从未到达（例如网络小故障），则会在超时后释放按住说话锁。
AllowSpeechStoppedFallbackAfterSpeechStart	bool	false	如果启用，在语音实际开始后，来自角色的 speech-stopped 事件也可释放按住说话等待状态。适用于轮次完成事件丢失等边缘情况的恢复。

var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    PushToTalkPolicy = new PushToTalkPolicy
    {
        InterruptBotOnPress = false,       // 让角色先说完，用户再发言
        RequireTurnCompletionBeforeNextPress = true,
        TurnCompletionTimeoutMs = 8000
    }
};

---

本地音频策略

LocalAudioPolicy 控制本地设备上的麦克风行为。适用于免手持和按住说话两种模式。

字段	类型	默认值	说明
StartMutedInPushToTalk	bool	true	在按住说话模式激活时，麦克风默认静音。仅在按住说话控件被按住时才采集音频。
EnableAcousticEchoCancellation	bool	false	启用声学回声消除。适用于 Android 和 iOS，在使用设备扬声器（免提）而非耳机时。
PushToTalkStartupMode	PushToTalkMicStartupMode	PrewarmMuted	控制按住说话模式开始时麦克风如何初始化。

PushToTalkMicStartupMode

值	行为	权衡
PrewarmMuted	会话开始时打开并预热麦克风，但在用户按下控件之前保持静音。	消除首次按下的延迟；占用少量后台资源。
OpenOnFirstPress	直到用户第一次按下按住说话之前，麦克风都不会打开。	节省资源；第一次按下时会带来短暂延迟（约 100–300 ms），因为麦克风需要初始化。

var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    LocalAudioPolicy = new LocalAudioPolicy
    {
        EnableAcousticEchoCancellation = true,   // 工厂车间场景，设备扬声器
        PushToTalkStartupMode = PushToTalkMicStartupMode.PrewarmMuted
    }
};

---

ServerSttInitialState

控制会话开始时是否启用 Convai 的语音转文本。

值	行为
UseDefault	服务器端默认：免手持启用 STT，按住说话禁用。
已启用	无论模式如何，STT 都会在启动时启用。
已禁用	无论模式如何，STT 都会在启动时禁用。这是高级选项——当前公开 API 未暴露手动 STT 控制。

---

运行时模式切换

无需断开会话即可在免手持和按住说话之间切换：

// 在会话中切换到按住说话
await _manager.SetConversationInputModeAsync(ConversationInputMode.PushToTalk);

SetConversationInputModeAsync 会返回一个 IConvaiOperation<Unit>。切换后的活动模式可通过 _manager.ActiveConversationInputMode.

运行时模式切换会应用新模式的 LocalAudioPolicy 默认设置。如果切换到按住说话，麦克风会根据 StartMutedInPushToTalk静音。会话不会重新连接。

---

使用示例

示例 1：医疗培训模拟器——免手持，严格轮次检测

学习者进行患者评估。AI 角色扮演患者。较短的静音阈值让对话更流畅。

var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.HandsFree,
    TurnDetection = TurnDetectionMode.Custom,
    CustomTurnDetection = new SmartTurnSettings
    {
        StopSecs = 2.0f,
        PreSpeechMs = 80,
        MaxDurationSecs = 12.0f   // 学习者可以给出更长的回答
    }
};

预期结果： 学习者停止说话后大约 2 秒，角色会做出回应。学习者的更长回答（描述症状、提问）最多可捕获 12 秒。

---

示例 2：工厂安全演练——带回声消除的按住说话

一位安全培训员在嘈杂的工厂模拟环境中与 AI 安全官互动。按住说话可防止环境噪声触发意外轮次。使用的是扬声器，因此启用 AEC。

var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    PushToTalkPolicy = new PushToTalkPolicy
    {
        InterruptBotOnPress = true,
        RequireTurnCompletionBeforeNextPress = false,   // 安全场景中的紧急覆盖
        TurnCompletionTimeoutMs = 6000
    },
    LocalAudioPolicy = new LocalAudioPolicy
    {
        EnableAcousticEchoCancellation = true,
        PushToTalkStartupMode = PushToTalkMicStartupMode.PrewarmMuted
    }
};

预期结果： 培训员可随时通过按按钮打断 AI。无设备扬声器回声反馈。

---

示例 3：通过 UI 按钮在模式之间运行时切换

一个以免手持开始，但允许主持人在直播会话中切换到按住说话的场景。

public class InputModeToggle : MonoBehaviour
{
    [SerializeField] private ConvaiManager _manager;
    private bool _isPushToTalk;

    public async void ToggleMode()
    {
        _isPushToTalk = !_isPushToTalk;
        var mode = _isPushToTalk
            ? ConversationInputMode.PushToTalk
            : ConversationInputMode.HandsFree;

        await _manager.SetConversationInputModeAsync(mode);
    }
}

预期结果： 模式在会话中切换，不会中断连接。检查 _manager.ActiveConversationInputMode 以确认切换后的活动模式。

---

故障排查

症状	可能原因	修复
角色在用户说完之前就插话回应	StopSecs 对于此场景的节奏来说太低了	增加 StopSecs 调到 2.5–3.0，在 SmartTurnSettings
用户轮次的第一个词被截断	语音起点捕获得太晚	增加 PreSpeechMs 调到 80–150 ms，在 SmartTurnSettings
角色说完后，按住说话按钮仍被锁定	未收到轮次完成事件（网络小故障）	TurnCompletionTimeoutMs 超时后释放锁；降低该值，或设置 AllowSpeechStoppedFallbackAfterSpeechStart = true
背景噪音在免手持模式下触发响应	环境对自动语音检测来说太嘈杂	切换到按住说话模式，或提高 StopSecs
首次按住说话按下时有短暂延迟	PushToTalkMicStartupMode 为 OpenOnFirstPress — 麦克风在首次按下时初始化	切换为 PrewarmMuted

---

下一步

你现在已经拥有轮流发言配置的完整字段参考。接下来阅读事件系统，了解如何在运行时对语音、转录和情绪事件做出响应。

事件系统功能