> 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` 上的 Blueprint 函数，可在运行时枚举、选择采集设备并调整增益。

### 默认行为

当 `UConvaiPlayerComponent` 初始化时，它会自动打开系统默认麦克风。此路径无需额外配置。如果默认设备适用于你的项目，请跳转到 [配置角色音频](https://docs.convai.com/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()` ：玩家选择设备时调用。开始采集前选择的设备可能要到下一次采集会话才会生效。

### 跨会话保存选择

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

调用 `ApplySavedMicrophoneSettings()` 可在更改设备后恢复未保存的更改——组件已在 `BeginPlay`期间自动调用此函数，因此从不调用 `SaveMicrophoneSettings()` 的项目，其行为与之前完全相同。玩家确认选择后（例如在设置菜单中点击 `SaveMicrophoneSettings()` 时），在 `UConvaiPlayerComponent` 上调用 **保存** 按钮）：

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

有关已保存设置的完整蓝图接口，请参阅 [麦克风和音频采集](https://docs.convai.com/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 编辑器中，打开 **编辑 > 插件**，搜索 `Android Permission`，并确认已启用。如果系统提示，请重启编辑器。
{% endstep %}

{% step %}

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

打开 **编辑 > 项目设置 > 平台 > Android > 高级 APK 打包**。在 **额外权限**下，点击 **+** 并添加：

```
android.permission.RECORD_AUDIO
```

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

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

在玩家即将开始对话的位置请求 `android.permission.RECORD_AUDIO` ，例如在游戏模式或玩家控制器中的 **BeginPlay** 事件中，或在玩家进入对话区域时。

使用 **Android Permission** 引擎插件中的节点： `AndroidPermission` ：

1. 调用 **检查 Android 权限** 与 `android.permission.RECORD_AUDIO`.
2. 如果结果为 `false`，请调用 **请求 Android 权限** 来请求该权限（或者调用 **请求 Android 权限** 并传入包含以下内容的字符串数组： `android.permission.RECORD_AUDIO`).
3. 绑定到 **权限请求完成时** （或者 **权限已授予时**），并且仅在确认权限已授予后才开始对话。

简化的蓝图流程：

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

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

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

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

### 故障排查

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

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

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

**解决方法：** 使用 `AndroidPermission` 引擎插件节点在运行时请求权限（请参阅上文的 [Android 麦克风权限](#android-microphone-permission) ）。调用 **Check Android Permission** → 如果结果为 `false`，请调用 **Request Android Permission** → 绑定到 **On Permission Request Complete** 并且仅在权限已授予时才开始对话。

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

#### 设备选择返回 false

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

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

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

**验证：** 调用 `GetActiveCaptureDevice(OutInfo)` 进行选择后，确认 `OutInfo.DeviceName` 与预期设备相符。

### 后续步骤

{% content-ref url="/pages/2f681ae01ba11fe882d6b331cca0444e0a06402d" %}
[配置角色音频](https://docs.convai.com/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" %}
[配置对话输入](https://docs.convai.com/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.
