> 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` 检查器中进行配置。

### 在哪里找到这些设置

选择 `ConvaiManager` 层级视图中的 GameObject。在检查器中，找到 `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 | 嘈杂环境、多人游戏、精确控制 |
| **延迟**   | 略高（静音检测延迟）     | 较低（按键松开时发送）    |
| **玩家操作** | 无              | 必须按住按键         |

### 免手持模式

Hands Free 是默认模式。设置 **模式** 移动到 `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`         | `是`            | 麦克风初始为静音；按键按下时激活                                                         |
| `EnableAcousticEchoCancellation` | `否`            | 为免提通话启用 AEC（Android/iOS）                                                 |
| `PushToTalkStartupMode`          | `PrewarmMuted` | `PrewarmMuted` = 麦克风从一开始就打开但处于静音状态； `OpenOnFirstPress` = 仅在第一次按下按键时打开麦克风 |

#### 按键通话策略

控制玩家按下和松开按键通话键时会发生什么。

| 设置                                           | 默认     | 说明                                                            |
| -------------------------------------------- | ------ | ------------------------------------------------------------- |
| `InterruptBotOnPress`                        | `是`    | 角色说话时按下该键会立即打断它                                               |
| `EnableServerSttToggle`                      | `是`    | 在玩家未按住按键时，暂停服务器端的 Convai 语音转文本。可降低服务器处理成本；如果你在按键时观察到识别延迟，请禁用。 |
| `RequireTurnCompletionBeforeNextPress`       | `是`    | 玩家必须等待角色说完才能再次发言                                              |
| `TurnCompletionTimeoutMs`                    | `5000` | 如果完成事件始终未到达，用于解锁按键通话的备用超时（毫秒）                                 |
| `AllowSpeechStoppedFallbackAfterSpeechStart` | `否`    | 允许在语音开始后，通过 speech-stopped 事件清除等待状态                           |

### 运行时模式切换

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

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

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

    // 切换到 Push to Talk——可从 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()` 仅在房间处于活动状态时有效 **已连接**。当房间处于 `已断开连接`, `Connecting`, `重新连接中`，或 `断开连接中` 将失败并返回 `SessionErrorCodes.SessionInvalidState`。检查 `ConvaiManager.IsConnected` 后再调用。
{% endhint %}

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

### 使用示例

#### 示例 1：医学培训——带延长静音的免手持模式

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

**在检查器中的设置：**

* 模式： `HandsFree`
* TurnDetection： `Custom`
* StopSecs： `5.0`
* MaxDurationSecs： `30.0`

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

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

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

**在检查器中的设置：**

* 模式： `PushToTalk`
* `_pushToTalkKey` 在 ConvaiRoomManager 上： `KeyCode.T`
* `InterruptBotOnPress`: `是` （工人可以打断较长的回复来追问）
* `EnableAcousticEchoCancellation`: `是` （存在机器噪音）

**预期结果：** 只有有意按键时才会将音频发送给 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" %}
[配置角色音频](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.