> 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="/files/1ce2ac7229c7da730e2545d53f1b96edf14b2ead" alt=""><figcaption></figcaption></figure>

### 输入模式对比

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

### 免手持模式

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

#### 轮流检测

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

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

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

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

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

### 按键发言模式

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

```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()` 仅在房间处于活动状态时有效 **已连接**。在房间处于 `已断开连接`, `连接中`, `重新连接中`，或 `Disconnecting` 时调用会以 `SessionErrorCodes.SessionInvalidState`。请检查 `ConvaiManager.IsConnected` 后再调用。
{% endhint %}

连接时的 `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：从过场动画切换到游戏玩法模式

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

```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:

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

The question should be specific, self-contained, and written in natural language.
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.