> 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).

# 配置麦克风

`UConvaiPlayerComponent` 通过麦克风捕获音频 `UConvaiAudioCaptureComponent`。默认情况下，它会在初始化时打开系统的默认采集设备。请使用 `UConvaiPlayerComponent` 上的 Blueprint 函数，以在运行时枚举、选择并调整采集设备。

### 默认行为

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

### 枚举可用设备

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

| 函数                                           | 返回                             | 说明                                 |
| -------------------------------------------- | ------------------------------ | ---------------------------------- |
| `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()` 当玩家选择设备时。采集开始前的设备选择可能要到下一次采集会话才生效。

### 调整麦克风音量

| 函数                              | Parameters                                            | 返回     | 说明                                                  |
| ------------------------------- | ----------------------------------------------------- | ------ | --------------------------------------------------- |
| `SetMicrophoneVolumeMultiplier` | `InVolumeMultiplier` (`float`), `Success` (`bool&`)   | `void` | 缩放捕获到的音频信号。 `1.0` 是默认值（不更改）；高于 `1.0` 的值会放大，低于的值会衰减。 |
| `GetMicrophoneVolumeMultiplier` | `OutVolumeMultiplier` (`float&`), `Success` (`bool&`) | `void` | 返回当前音量乘数。                                           |

使用 `SetMicrophoneVolumeMultiplier` 如果角色持续听不清音量较低的说话者，或者你的麦克风增益较低。

### Android 麦克风权限

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

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

#### 准备 Android 构建

{% stepper %}
{% step %}

#### 启用 Android Permission 插件

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

{% step %}

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

打开 **Edit > Project Settings > Platforms > Android > Advanced APK Packaging**中的内容。位于 **额外权限**点击 **+** 并添加：

```
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 权限** 针对该权限（或 **Request Android Permissions** ，使用一个包含 `android.permission.RECORD_AUDIO`).
3. 绑定到 **On Permission Request Complete** （或 **On Permissions Granted**），并且仅在确认授权后才开始对话。

简化的 Blueprint 流程：

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

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

在 Quest 设备上： **Settings > Apps > \[Your App] > Permissions > Microphone > Allow**.

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

### 故障排查

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

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

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

**修复：** 使用 `AndroidPermission` 引擎插件节点（见 [Android 麦克风权限](#android-microphone-permission) 上文）。调用 **检查 Android 权限** → 如果 `false`，则调用 **请求 Android 权限** → 绑定 **On Permission Request Complete** 并且仅在获得授权结果时开始对话。

**验证：** 授予权限后，进入 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:

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

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.