> 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`。默认情况下，它会在初始化时打开系统默认的采集设备，然后重新应用玩家上次保存的设备和增益。请使用……上的 Blueprint 函数 `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()` 在 `UConvaiPlayerComponent` 在玩家确认选择后一次，例如通过 **保存** 设置菜单中的按钮：

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

有关完整的持久化设置 Blueprint 接口，请参见 [麦克风和音频采集](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/microphone-and-audio-capture.md).

### 测试麦克风

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

自 `4.0.0-beta.27`，即使在对话流已经打开时，这个测试录音也能工作——以前，在打开的流中调用 `StartRecording()` 会产生无音频。测试录音时，角色不会听到它：流保持打开，但录音不会转发给它。 `FinishRecording()` 会恢复项目的静音设置（ `bMute` 上该值 `UConvaiPlayerComponent`）

### 调整麦克风音量

| 函数                              | 参数                                                    | 返回     | 说明                                                  |
| ------------------------------- | ----------------------------------------------------- | ------ | --------------------------------------------------- |
| `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 Permissions Granted**）并仅在确认授予后开始对话。

简化的 Blueprint 流程：

```
Event BeginPlay → Delay（0.5 秒）→ 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 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-unreal-engine-plugin/getting-started/configure-the-microphone.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.