> 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/blueprint-reference/microphone-and-audio-capture.md).

# 麦克风和音频捕获

Convai Player Component 和麦克风子系统中麦克风设备枚举、选择、音量以及持久化设置的参考。

`UConvaiPlayerComponent` 在以下项下公开所有可供 Blueprint 调用的麦克风函数： `Convai|Microphone` 类别。其内部驱动一个 `UConvaiAudioCaptureComponent` 实例，该实例封装了 Unreal `AudioCapture` 引擎插件，并通过 `UConvaiMicrophoneSubsystem`在会话之间持久保存玩家选择的设备和增益。在 Android 上， `AndroidPermission` 插件负责处理运行时麦克风权限。

完整的 `UConvaiPlayerComponent` 属性集合——身份、会话、凝视注意力和音频处理——请参见 [Convai Player Component](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md).

### FCaptureDeviceInfoBP

`FCaptureDeviceInfoBP` 是一个 `BlueprintType` 结构体由设备枚举和选择函数返回。所有字段均为 `EditAnywhere`, `BlueprintReadWrite`, `Category = "Convai|Microphone"`.

| 字段                     | 类型        | 默认      | 说明                                                |
| ---------------------- | --------- | ------- | ------------------------------------------------- |
| `DeviceName`           | `FString` | `""`    | 显示在设备菜单中的人类可读名称。                                  |
| `DeviceIndex`          | `int`     | `0`     | 捕获设备列表中的从零开始索引。设备被添加或移除时，索引可能在会话之间发生变化。           |
| `LongDeviceId`         | `FString` | `""`    | 平台特定的设备标识符。在 Windows 上，它比 `DeviceIndex` 在会话之间更稳定。 |
| `InputChannels`        | `int`     | `0`     | 设备报告的输入通道数。                                       |
| `PreferredSampleRate`  | `int`     | `0`     | 设备首选的采样率，单位 Hz。                                   |
| `bSupportsHardwareAEC` | `bool`    | `false` | `true` 当设备支持硬件回声消除时。                              |

### Convai|Microphone 函数

这些 `BlueprintCallable` 函数全部位于 `UConvaiPlayerComponent` (Blueprint 显示名称 **Convai Player**).

#### 设备枚举

| 函数                                 | 参数                                                       | 返回                             | 说明                                                                                                                                                              |
| ---------------------------------- | -------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetAvailableCaptureDeviceNames`   | —                                                        | `TArray<FString>`              | 所有可用输入设备的名称。将这些字符串用作显示标签以及 `DeviceName` 参数，传入 `SetCaptureDeviceByName`.                                                                                         |
| `GetAvailableCaptureDeviceDetails` | —                                                        | `TArray<FCaptureDeviceInfoBP>` | 完全 `FCaptureDeviceInfoBP` 为每个可用设备返回结构体。包括索引、长 ID、通道数、采样率和 AEC 标志。                                                                                               |
| `GetDefaultCaptureDeviceInfo`      | `OutInfo (FCaptureDeviceInfoBP)` 输出                      | `bool`                         | **当前源码：** 会验证 `AudioCaptureComponent`，然后始终返回 `false` 而不填充 `OutInfo`。不要依赖此节点返回的 `OutInfo` 。请使用 `GetAvailableCaptureDeviceDetails` 或 `GetActiveCaptureDevice` 替代。 |
| `GetCaptureDeviceInfo`             | `OutInfo (FCaptureDeviceInfoBP)` 输出， `DeviceIndex (int)` | `bool`                         | 为位于以下位置的设备填充 `OutInfo` 信息 `DeviceIndex`。返回 `false` 当索引超出范围时。                                                                                                    |
| `GetActiveCaptureDevice`           | `OutInfo (FCaptureDeviceInfoBP)` 输出                      | —                              | 为位于以下位置的设备填充 `OutInfo` 与当前选定的捕获设备对应。                                                                                                                            |

#### 设备选择

| 函数                        | 参数                     | 返回     | 说明                                                      |
| ------------------------- | ---------------------- | ------ | ------------------------------------------------------- |
| `SetCaptureDeviceByIndex` | `DeviceIndex (int)`    | `bool` | 打开位于以下位置的捕获设备 `DeviceIndex`。返回 `false` 当索引超出范围或设备无法打开时。 |
| `SetCaptureDeviceByName`  | `DeviceName (FString)` | `bool` | 打开枚举列表中其最后一个 `DeviceName` 与输入匹配的设备。若未找到匹配项则返回 `false` 。 |

这两个选择函数都可以在游戏开始前或进行中调用。调用成功后， `GetActiveCaptureDevice` 会反映新设备。

#### 音量

| 函数                              | 参数                           | 返回                                        | 说明                                                        |
| ------------------------------- | ---------------------------- | ----------------------------------------- | --------------------------------------------------------- |
| `SetMicrophoneVolumeMultiplier` | `InVolumeMultiplier (float)` | `成功（bool）`                                | 缩放捕获到的音频信号。 `Success` 表示是否有可用的捕获组件，而不是麦克风捕获当前是否正在流式传输或录音。 |
| `GetMicrophoneVolumeMultiplier` | —                            | `OutVolumeMultiplier (float)`, `成功（bool）` | 读取当前音量倍率。 `Success` 表示捕获组件是否可用。                           |

`InVolumeMultiplier` 在 API 中没有强制范围。值为 `1.0` 时不应用增益变化。高于 `1.0` 的值会放大信号；低于 `1.0` 的值会衰减信号。值为 `0.0` 时会使捕获到的音频静音，同时保持捕获会话处于活动状态。

#### 流式传输和录音状态

| 函数                                       | 类别       | 返回           | 说明     |
| ---------------------------------------- | -------- | ------------ | ------ |
| `GetIsStreaming` (显示名称 **Is Streaming**) | \`Convai | Microphone\` | `bool` |
| `GetIsRecording` (显示名称 **Is Recording**) | \`Convai | Microphone\` | `bool` |

`StartRecording`, `FinishRecording`, `UnmuteStreamingAudio`，以及 `MuteStreamingAudio` 在以下项下有文档说明： **音频流式传输和录音** 部分，位于 [Convai Player Component](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md).

#### 已持久化设置

| 函数                             | 参数 | 返回     | 说明                                                                                                                        |
| ------------------------------ | -- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `SaveMicrophoneSettings`       | —  | `bool` | 拍摄玩家组件当前的捕获设备和增益快照，然后通过 `UConvaiMicrophoneSubsystem`将其持久化。玩家提交设备选择后请调用此函数——仅选择设备只会在当前会话中应用，直到调用此函数为止。若子系统不可用则返回 `false` 。 |
| `ApplySavedMicrophoneSettings` | —  | `bool` | 重新应用已持久化的设备（如果该设备已不再连接则跳过）和增益到玩家组件。会在以下过程中自动调用 `BeginPlay`；如果需要从 UI 中还原未保存的更改，请再次调用它。返回 `false` 。                         |

这两个函数都会委托给 `UConvaiMicrophoneSubsystem`，其文档如下。

### UConvaiMicrophoneSubsystem

`UConvaiMicrophoneSubsystem` (Blueprint 显示名称 **Convai 麦克风子系统**）是一个 `UGameInstanceSubsystem` 负责在会话之间保存玩家的麦克风设备和增益偏好，因此每次启动时选择不再重置为系统默认值。其上每个可供 Blueprint 访问的成员都使用 `Category = "Convai|Microphone"`.

| 节点                                                                  | Kind                     | 参数                                         | 返回                            | 说明                                                                                                                     |
| ------------------------------------------------------------------- | ------------------------ | ------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Get` (显示名称 **Get**，派生自——无显式 `DisplayName` 元数据)                     | `BlueprintPure`，静态       | `WorldContextObject`                       | `UConvaiMicrophoneSubsystem*` | 返回当前游戏实例的子系统实例。                                                                                                        |
| `GetMicrophoneSettings` (显示名称 **获取麦克风设置**)                          | `BlueprintPure`          | —                                          | `FConvaiMicrophoneSettings`   | 返回子系统当前持有的设置。                                                                                                          |
| `HasSavedMicrophoneSettings` (显示名称 **是否存在已保存的麦克风设置**)               | `BlueprintPure`          | —                                          | `bool`                        | `true` 当本次会话在磁盘上找到已保存记录时返回真，而不是回退到默认值。                                                                                 |
| `SaveMicrophoneSettings` (显示名称 **保存麦克风设置**)                         | `BlueprintCallable`      | `InSettings (FConvaiMicrophoneSettings)`   | —                             | 替换当前持有的设置并将其写入共享记录。广播 `OnMicrophoneSettingsChanged`。接收一个显式的设置值——这与 `UConvaiPlayerComponent`上同名节点不同，后者读取的是组件当前活动的设备和增益。 |
| `SaveMicrophoneSettingsFromPlayerComponent` (显示名称 **从玩家组件保存麦克风设置**) | `BlueprintCallable`      | `PlayerComponent (UConvaiPlayerComponent)` | `bool`                        | 拍摄 `PlayerComponent`的当前捕获设备和增益快照，然后将其持久化。这就是 `UConvaiPlayerComponent::SaveMicrophoneSettings` 在内部调用的内容。                |
| `ResetMicrophoneSettingsToDefaults` (显示名称 **将麦克风设置重置为默认值**)         | `BlueprintCallable`      | —                                          | —                             | 忘记已保存的选择并删除共享记录。                                                                                                       |
| `GetAvailableMicrophoneNames` (显示名称 **获取可用麦克风名称**)                  | `BlueprintCallable`      | —                                          | `TArray<FString>`             | 当前存在的设备名称，命名方式与 `UConvaiPlayerComponent::GetAvailableCaptureDeviceNames`.                                              |
| `IsSavedMicrophoneAvailable` (显示名称 **已保存麦克风是否可用**)                  | `BlueprintCallable`      | —                                          | `bool`                        | `true` 当某个设备已保存且当前已连接时。 `false` 没有保存内容是正常的“跟随系统默认值”情况，而不是错误。                                                           |
| `ApplySavedSettingsToPlayerComponent` (显示名称 **将已保存设置应用到玩家组件**)      | `BlueprintCallable`      | `PlayerComponent (UConvaiPlayerComponent)` | `bool`                        | 将已保存的增益以及已保存的设备（如果它仍然可用）应用到 `PlayerComponent`。返回 `true` 仅在已保存的设备被解析并选中时。                                               |
| `OnMicrophoneSettingsChanged` (显示名称 **当麦克风设置变更时**)                  | `BlueprintAssignable` 事件 | `NewSettings (FConvaiMicrophoneSettings)`  | —                             | 每当以下情况时广播 `SaveMicrophoneSettings` 在子系统上运行。                                                                            |

### FConvaiMicrophoneSettings

`FConvaiMicrophoneSettings` (`BlueprintType`, `Category = "Convai|Microphone"`）是该结构体 `UConvaiMicrophoneSubsystem` 持久化。

| 字段                | 类型        | 默认    | 说明                                                                                        |
| ----------------- | --------- | ----- | ----------------------------------------------------------------------------------------- |
| `InputDeviceName` | `FString` | `""`  | 空表示系统默认设备。否则为一个 `DeviceName` 来自 `UConvaiPlayerComponent::GetAvailableCaptureDeviceNames`. |
| `InputGain`       | `float`   | `1.0` | 应用到麦克风输入增益的倍率。 `1.0` 保持不变；编辑器 UI 会将该字段钳制到 `0.0`–`2.0` 范围内。                                |

### ConvaiAudioCaptureComponent

`UConvaiAudioCaptureComponent` （C++ 类， `ClassGroup = Synth`）继承自 `USynthComponent` 并封装 `FConvaiAudioCaptureSynth`，而后者又封装 Unreal `FAudioCapture` 对象。 `UConvaiPlayerComponent` 会自动创建并拥有一个实例；你无需手动将 `UConvaiAudioCaptureComponent` 添加到你的 Actor。

{% hint style="info" %}
在大多数 Blueprint 中，请使用 `UConvaiPlayerComponent` 上的麦克风函数，而不是直接与 `UConvaiAudioCaptureComponent` 交互。玩家组件在内部进行委托，并提供上文各节所述的更高层级流式传输 API。
{% endhint %}

该组件声明了一个 Convai 特有的可供 Blueprint 配置的属性；继承的 `USynthComponent` 属性也同样适用。

| 属性                    | 类型      | 类别   | 约束                                | 说明                                                                |
| --------------------- | ------- | ---- | --------------------------------- | ----------------------------------------------------------------- |
| `JitterLatencyFrames` | `int32` | `延迟` | `ClampMin = 0`, `ClampMax = 1024` | 用于诱发抖动缓冲的声明式延迟设置。在当前插件源代码中，Convai 捕获实现不会读取此属性，因此更改它不会产生已验证的运行时效果。 |

大多数设备枚举和设备切换行为都通过 `UConvaiPlayerComponent` 来驱动——上面列出的 Blueprint 函数都会委托给底层的 `UConvaiAudioCaptureComponent` 在内部处理，除了 `GetDefaultCaptureDeviceInfo` 位于玩家组件上的那个，它目前不会转发到捕获组件。

在 C++ 层， `UConvaiAudioCaptureComponent::GetDefaultCaptureDeviceInfo` 确实会填充系统默认设备。该方法未向 Blueprint 暴露。该组件的其他设备方法（`GetCaptureDevicesAvailable`, `GetCaptureDeviceInfo`, `GetActiveCaptureDevice`, `SetCaptureDevice`）也都是 C++ 内部方法。

### 插件依赖项

这两个依赖项都声明在 `ConvAI.uplugin` 中，并会在安装 Convai 插件时自动启用。无需手动激活插件。

| 插件                  | 已启用    | 用途                                                                                           |
| ------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `AudioCapture`      | `true` | Unreal Engine 内置插件，提供 `FAudioCapture` 和 `USynthComponent`基于的捕获。Win64 和 Android 上所有麦克风输入都需要它。 |
| `AndroidPermission` | `true` | Unreal Engine 内置插件，提供用于检查和请求 Android 运行时权限的 Blueprint 节点。Android 上的麦克风访问需要它。                 |

#### Android 麦克风权限

在 Android 上，操作系统要求授予运行时权限才能进行音频捕获。没有它， `UConvaiAudioCaptureComponent` 会初始化但不会捕获任何音频——Convai 角色将接收不到语音输入。插件不会记录权限被拒绝的消息，不过流打开失败仍可能产生捕获警告。

{% hint style="warning" %}
请求 `android.permission.RECORD_AUDIO` 在调用之前 `StartSession` 或 `UnmuteStreamingAudio`。如果权限被拒绝，音频捕获会静默地产生无数据输出。
{% endhint %}

使用 `AndroidPermission` 用于请求权限的 Blueprint 节点：

1. 调用 `检查 Android 权限` 与权限字符串 `android.permission.RECORD_AUDIO`.
2. 如果返回值为 `false`的情况下推送一个值，请调用 `请求 Android 权限` 针对相同的字符串。
3. 绑定到 `权限请求完成` 委托，并且只有在确认已授予权限之后才开始对话。

该 `AndroidPermission` 插件节点位于 `Android Permission` Blueprint 类别中。在 Win64 上它们是无操作——同一 Blueprint 图表无需平台保护即可在两个平台上工作。

### 相关参考

玩家组件页面涵盖完整的属性表面；使用说明页面则演示在发布前如何选择并测试设备。

{% content-ref url="/pages/7882b4c0154c419a4eb6df2db3b2035b55cacb03" %}
[Convai 玩家组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md)
{% endcontent-ref %}

{% content-ref url="/pages/ddab80eff30a95a57bb3cec04bc4566233e30263" %}
[配置麦克风](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-the-microphone.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/blueprint-reference/microphone-and-audio-capture.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.