> 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/configure-conversation-input-mode.md).

# 配置对话输入模式

选择免提语音激活或按键通话，配置触发键或控制器按钮，并在运行时切换两种模式。

适用于 Unity 的 Convai SDK 支持两种对话输入模式： **免提** （玩家自然说话，SDK 会检测他们何时停止说话）和 **按住说话** （玩家按住按键说话）。这两种模式都在 `ConvaiRoomManager` 的 Inspector 中配置。

### 设置位置

在 Hierarchy 中选择 `ConvaiManager` GameObject。在 Inspector 中找到 `ConvaiRoomManager`。 **轮次交接选项** 部分包含所有输入模式设置。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-61999a4cb219e6882cf3f3a22c14e788cf2426e4%2Fimage.png?alt=media" alt="ConvaiRoomManager Inspector with the Turn-Taking Options section expanded, showing the Mode dropdown for Hands Free and Push to Talk"><figcaption></figcaption></figure>

### 输入模式对比

|          | 免提            | 按住说话             |
| -------- | ------------- | ---------------- |
| **工作方式** | SDK 自动检测语音结束  | 玩家按住按键说话，松开按键后发送 |
| **适用场景** | 自然对话、信息亭体验、VR | 嘈杂环境、多人游戏、精确控制   |
| **延迟**   | 略高（静音检测延迟）    | 较低（松开按键时发送）      |
| **玩家操作** | 无             | 必须按住按键           |

### 免提模式

免提是默认模式。将 **模式** 设为 `HandsFree`.

#### 轮次检测

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

| 设置              | 默认值          | 说明                                                           |
| --------------- | ------------ | ------------------------------------------------------------ |
| `TurnDetection` | `UseDefault` | `UseDefault` = 服务器默认值， `Disabled` = 始终开启的流， `Custom` = 在下方配置 |

当 `TurnDetection` 设为 `Custom`时， **智能轮次设置** 将会显示：

| 设置                | 默认值   | 说明            |
| ----------------- | ----- | ------------- |
| `StopSecs`        | `3.0` | 回合结束前的静音秒数    |
| `MaxDurationSecs` | `8.0` | 强制结束前的最长回合时长  |
| `PreSpeechMs`     | `0`   | 纳入语音开始前的音频毫秒数 |

{% hint style="info" %}
增加 `StopSecs` 可让玩家在句中停顿更久，而不会触发回合结束。这适用于训练模拟场景，让学习者有时间思考后再回答。
{% endhint %}

### 按键通话模式

将 **模式** 设为 `PushToTalk`。默认按键是 **T** —可通过 `_pushToTalkKey` 在 `ConvaiRoomManager`.

在 Meta Quest 上，按键通话通过 Unity 的 XR 输入 API 读取 A、B、X 和 Y 按钮，而不是键盘按键。如果无法读取当前活动的 XR 控制器，或控制器在按键期间断开连接，SDK 会采取安全关闭措施，停止采集麦克风音频，而不是让麦克风保持开启。键盘和非 XR 摇杆的行为不变。

#### 本地音频策略

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

| 设置                               | 默认值            | 说明                                                                        |
| -------------------------------- | -------------- | ------------------------------------------------------------------------- |
| `StartMutedInPushToTalk`         | `true`         | 麦克风启动时处于静音状态；按下按键后激活                                                      |
| `EnableAcousticEchoCancellation` | `false`        | 使用扬声器通话时启用 AEC（Android/iOS）                                               |
| `PushToTalkStartupMode`          | `PrewarmMuted` | `PrewarmMuted` = 麦克风从启动时起便已开启但处于静音状态； `OpenOnFirstPress` = 仅在首次按下按键时开启麦克风 |

#### 按键通话策略

控制玩家按下和松开按键通话键时的行为。

| 设置                                           | 默认值     | 说明                                                                 |
| -------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `InterruptBotOnPress`                        | `true`  | 角色说话时按下按键，会立即打断角色                                                  |
| `EnableServerSttToggle`                      | `true`  | 玩家未按住按键时，暂停 Convai 服务器端的语音转文字处理。此设置可降低服务器处理成本；如果发现按下按键后识别延迟，请将其禁用。 |
| `RequireTurnCompletionBeforeNextPress`       | `true`  | 玩家必须等待角色说完后才能再次讲话                                                  |
| `TurnCompletionTimeoutMs`                    | `5000`  | 如果未收到回合完成事件，用于解除按键通话锁定的备用超时时间（毫秒）                                  |
| `AllowSpeechStoppedFallbackAfterSpeechStart` | `false` | 语音开始后，允许通过语音停止事件清除等待状态                                             |

### 运行时模式切换

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

```csharp
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();
    }
}
```

读取当前活动模式或响应模式变化：

```csharp
using Convai.Runtime.Room;

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

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

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

{% hint style="warning" %}
`SetConversationInputModeAsync()` 仅在房间处于活动的 **已连接**状态时有效。在房间处于 `Disconnected`, `Connecting`, `Reconnecting`或 `Disconnecting` 状态时调用会失败，并返回 `SessionErrorCodes.SessionInvalidState`。调用前请检查 `ConvaiManager.IsConnected` 。
{% endhint %}

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

### 使用示例

#### 示例 1：医疗培训——免提模式并延长静音时长

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

**在 Inspector 中设置：**

* 模式： `HandsFree`
* 轮次检测： `Custom`
* 停止秒数： `5.0`
* 最长时长（秒）： `30.0`

**预期结果：** 学生在回答过程中最多可以停顿 5 秒，而不会结束当前轮次。角色会等待学生说完。

#### 示例 2：工业现场检查——按键通话

**场景：** 在嘈杂的制造环境中，工人使用按键通话，以避免意外触发语音。他们按下 **T** 来询问设备状态。

**在 Inspector 中设置：**

* 模式： `PushToTalk`
* `_pushToTalkKey` （在 ConvaiRoomManager 上）： `KeyCode.T`
* `InterruptBotOnPress`: `true` （工人可以打断过长的回复，以便提出后续问题）
* `EnableAcousticEchoCancellation`: `true` （存在机器噪声）

**预期结果：** 只有有意按下按键时，音频才会发送到 Convai。背景噪声不会触发响应。工人可以通过再次按键打断冗长的回答。

#### 示例 3：从电影式过场切换到游戏模式

**场景：** 新手引导过场使用免提模式。游戏开始时，无需重新加载场景即可切换到按键通话模式。

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

**预期结果：** 模式可在会话进行中无缝切换。角色会持续运行，不会中断。按键通话控件会立即启用。

### 后续步骤

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

{% content-ref url="/pages/dc31c15bb8798169a403a964c726a9122812a736" %}
[配置角色音频](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-character-audio.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
