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

# 麦克风和音频捕获

`UConvaiPlayerComponent` 在以下类别下公开所有可由 Blueprint 调用的麦克风函数： `Convai|Microphone` 。内部它驱动一个 `UConvaiAudioCaptureComponent` 实例，该实例封装了 Unreal `AudioCapture` 引擎插件。在 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 玩家**).

#### 设备枚举

| 函数                                 | Parameters                                               | 返回                             | 说明                                                                                                                                                              |
| ---------------------------------- | -------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` 与当前选中的捕获设备一起。                                                                                                                                       |

#### 设备选择

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

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

#### 音量

| 函数                              | Parameters                   | 返回                                              | 说明                                                        |
| ------------------------------- | ---------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| `SetMicrophoneVolumeMultiplier` | `InVolumeMultiplier (float)` | `Success (bool)`                                | 缩放捕获到的音频信号。 `Success` 反映的是是否存在捕获组件，而不是麦克风捕获当前是否正在流式传输或录制。 |
| `GetMicrophoneVolumeMultiplier` | —                            | `OutVolumeMultiplier (float)`, `Success (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).

### 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. 绑定到 `On Permission Request Complete` 委托，并且仅在确认授予权限后再开始对话。

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