> 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-unreal-engine-plugin/getting-started/configure-the-microphone.md).

# 配置麦克风

选择采集设备、调整音量、测试麦克风，并处理 Android 权限，使玩家语音能够传达到 Convai 角色。

`UConvaiPlayerComponent` 通过 `UConvaiAudioCaptureComponent`. 默认情况下，它会在初始化时打开系统的默认捕获设备，然后重新应用玩家上次保存的设备和增益。使用位于 `UConvaiPlayerComponent` 的蓝图函数，在运行时枚举、选择并调整捕获设备。

### 默认行为

当 `UConvaiPlayerComponent` 初始化时，它会自动打开系统默认麦克风。此路径不需要额外配置。如果默认设备适合你的项目，请跳到 [配置角色音频](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-character-audio.md).

### 枚举可用设备

在一个 `UConvaiPlayerComponent` 引用上调用这些蓝图函数，以列出可用输入设备：

| 函数                                           | 返回值                            | 注意                                     |
| -------------------------------------------- | ------------------------------ | -------------------------------------- |
| `GetAvailableCaptureDeviceNames()`           | `TArray<FString>`              | 所有可用输入设备的名称。                           |
| `GetAvailableCaptureDeviceDetails()`         | `TArray<FCaptureDeviceInfoBP>` | 完整详情：名称、索引、长 ID、通道数、采样率、AEC 支持。        |
| `GetCaptureDeviceInfo(OutInfo, DeviceIndex)` | `bool`                         | 填充 `OutInfo` 位于以下索引的设备的 `DeviceIndex`. |
| `GetActiveCaptureDevice(OutInfo)`            | `void`                         | 填充 `OutInfo` 与当前活动设备一起。                |

该 `FCaptureDeviceInfoBP` 该结构体公开以下字段：

| 字段                     | 类型        | 描述            |
| ---------------------- | --------- | ------------- |
| `DeviceName`           | `FString` | 人类可读的设备名称。    |
| `DeviceIndex`          | `int`     | 用于选择的索引。      |
| `LongDeviceId`         | `FString` | 平台相关的设备标识符。   |
| `InputChannels`        | `int`     | 输入通道数量。       |
| `PreferredSampleRate`  | `int`     | 设备首选采样率。      |
| `bSupportsHardwareAEC` | `bool`    | 设备是否支持硬件回声消除。 |

### 选择捕获设备

若要从默认设备切换，请在 `UConvaiPlayerComponent`:

| 函数                                     | 按以下方式选择     | 返回值                     |
| -------------------------------------- | ----------- | ----------------------- |
| `SetCaptureDeviceByIndex(DeviceIndex)` | 枚举列表中的设备索引。 | `bool` — `true` 如果切换成功。 |
| `SetCaptureDeviceByName(DeviceName)`   | 设备名称字符串。    | `bool` — `true` 如果切换成功。 |

在音频捕获处于活动状态时调用任一函数（例如，在启用按键通话或 VAD 会话期间）。一种常见做法是构建一个设置菜单，列出 `GetAvailableCaptureDeviceNames()` 并调用 `SetCaptureDeviceByIndex()` 当玩家选择设备时。捕获开始前的设备选择可能要到下一次捕获会话才会生效。

### 跨会话保存选择

自 `4.0.0-beta.27`起，玩家选择的设备和增益会跨会话保留，而不会在每次启动时重置为系统默认值。 `UConvaiPlayerComponent` 通过 `UConvaiMicrophoneSubsystem`.

调用 `ApplySavedMicrophoneSettings()` 在设备更改后，如果需要还原未保存的更改——组件在 `BeginPlay`期间已自动调用它，因此 `SaveMicrophoneSettings()` 因此，从不调用 SaveMicrophoneSettings() 的项目行为与以往完全相同。请在 `SaveMicrophoneSettings()` on `UConvaiPlayerComponent` 玩家确认其选择后调用一次，例如通过 **“保存”** 设置菜单中的按钮：

| 函数                               | 返回值    | 描述                                |
| -------------------------------- | ------ | --------------------------------- |
| `SaveMicrophoneSettings()`       | `bool` | 持久保存组件当前的捕获设备和增益，以便在下次启动时恢复。      |
| `ApplySavedMicrophoneSettings()` | `bool` | 重新应用已持久保存的设备和增益；如果设备已不再插入，则跳过该设备。 |

完整的持久化设置蓝图接口请参见 [麦克风与音频捕获](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/microphone-and-audio-capture.md).

### 测试麦克风

`StartRecording()` 和 `FinishRecording()` on `UConvaiPlayerComponent` 录制一段短样本，并将其作为 `USoundWave`返回，因此设置菜单可以回放所选设备捕获的内容。

自 `4.0.0-beta.27`，这个测试录音在会话流已经打开时也同样可用——以前，在打开的流中调用 `StartRecording()` 时不会产生任何音频。测试录音期间，角色听不到它：流保持打开，但录音不会转发给它。 `FinishRecording()` 恢复项目的静音设置（ `bMute` 上的值 `UConvaiPlayerComponent`）为测试开始前的状态，而不是清除它。

### 调整麦克风音量

| 函数                              | Parameters                                       | 返回值    | 描述                                                     |
| ------------------------------- | ------------------------------------------------ | ------ | ------------------------------------------------------ |
| `SetMicrophoneVolumeMultiplier` | `InVolumeMultiplier` (`float`), `成功` (`bool&`)   | `void` | 按比例缩放捕获到的音频信号。 `1.0` 为默认值（不变）；高于 `1.0` 的值会放大，低于该值的会衰减。 |
| `GetMicrophoneVolumeMultiplier` | `OutVolumeMultiplier` (`float&`), `成功` (`bool&`) | `void` | 返回当前音量倍率。                                              |

在每个阶段加载时，对聊天机器人组件使用 `SetMicrophoneVolumeMultiplier` 如果角色持续听错声音较小的说话者，或者你的麦克风增益较低，可调整此项。

### Android 麦克风权限

在 Android 和独立 VR 构建（例如 Meta Quest）上，操作系统要求在音频捕获开始前显式授予运行时权限。Convai 插件依赖于 `AndroidPermission` 引擎插件——已随包捆绑并自动启用——来请求此权限。

{% hint style="warning" %}
在 Android 上没有麦克风权限时， `UConvaiPlayerComponent` 会初始化，但音频捕获会静默失败。角色不会收到任何语音输入。
{% endhint %}

#### 准备 Android 构建

{% stepper %}
{% step %}

#### 启用 Android Permission 插件

在 Unreal Editor 中，打开 **Edit > Plugins**，搜索 `Android Permission`，并确认它已启用。若提示，请重启编辑器。
{% endstep %}

{% step %}

#### 在项目设置中声明权限

打开 **Edit > Project Settings > Platforms > Android > Advanced APK Packaging**。在 **Extra Permissions**下，点击 **+** 并添加：

```
android.permission.RECORD_AUDIO
```

保存项目设置。
{% endstep %}
{% endstepper %}

#### 在运行时请求权限

请求 `android.permission.RECORD_AUDIO` 在应用程序中玩家即将开始对话的那个时刻——例如，在你的 Game Mode 或 Player Controller **BeginPlay** 事件中，或者当玩家进入对话区域时。

请使用 **Android Permission** 来自 `AndroidPermission` 引擎插件的

1. 调用 **检查 Android 权限** 使用 `android.permission.RECORD_AUDIO`.
2. 如果结果是 `false`，则调用 **请求 Android 权限** 该权限为 false（或者 **Request Android Permissions** 使用一个包含 `android.permission.RECORD_AUDIO`).
3. 绑定到 **权限请求完成时** （或 **On Permissions Granted**），并且仅在确认授予后才开始对话。

简化的蓝图流程：

```
Event BeginPlay → Delay (0.5s) → Check Android Permission (RECORD_AUDIO) → Branch
  → True：开始对话 / 启用语音输入
  → False：Request Android Permission → 确认授予后：开始对话
```

如果玩家之前拒绝了该权限，请启用 **麦克风** 在设备的应用设置中手动启用后再测试一次。

在 Quest 设备上： **设置 > 应用 > \[你的应用] > 权限 > 麦克风 > 允许**.

授予权限后，请重新构建并重新部署 Android 或 Quest 包，然后再在设备上测试语音输入。

### 故障排查

#### Android 上没有麦克风输入

**症状：** 角色始终收不到语音；玩家说话后对话也不会开始。

**原因：** 该 `android.permission.RECORD_AUDIO` 在初始化音频捕获之前未授予运行时权限。没有它， `UConvaiAudioCaptureComponent` 会静默初始化，但不会捕获任何内容。

**解决方法：** 使用 `AndroidPermission` 引擎插件节点（参见 [Android 麦克风权限](#android-microphone-permission) 上文）。调用 **检查 Android 权限** → 如果 `false`，则调用 **请求 Android 权限** → 绑定 **权限请求完成时** 并且只在结果为授予时开始对话。

**验证：** 授予权限后，进入 Play 模式并说话。角色应能接收并响应语音输入。

#### 设备选择返回 false

**症状：** `SetCaptureDeviceByIndex()` 或 `SetCaptureDeviceByName()` 返回 `false`.

**原因：** 请求的设备索引超出范围，或者设备名称与中的任何条目都不匹配 `GetAvailableCaptureDeviceNames()`.

**解决方法：** 调用 `GetAvailableCaptureDeviceNames()` 先进行枚举，并且只使用该列表中的名称和索引。如果设备被添加或移除，索引可能会在会话之间变化。

**验证：** 调用 `GetActiveCaptureDevice(OutInfo)` 在选择后并确认 `OutInfo.DeviceName` 与目标设备匹配。

### 下一步

{% content-ref url="/pages/2f681ae01ba11fe882d6b331cca0444e0a06402d" %}
[配置角色音频](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-character-audio.md)
{% endcontent-ref %}

{% content-ref url="/pages/9b983ed32e78e3fecceef1f1ca84663abe05edca" %}
[配置对话输入](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.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-unreal-engine-plugin/getting-started/configure-the-microphone.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.