配置麦克风

选择采集设备、调整音量，并处理 Android 麦克风权限，使玩家语音能正确传达到 Convai 角色。

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

默认行为

当 UConvaiPlayerComponent 初始化时，它会自动打开系统默认麦克风。此路径无需额外配置。如果默认设备适合你的项目，请跳到 配置角色音频.

枚举可用设备

在一个 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 引擎插件——已自动打包并启用——来请求该权限。

在 Android 上如果没有麦克风权限， UConvaiPlayerComponent 会初始化，但音频采集会静默失败。角色将不会收到任何语音输入。

准备 Android 构建

1

启用 Android Permission 插件

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

2

在项目设置中声明权限

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

android.permission.RECORD_AUDIO

保存项目设置。

在运行时请求权限

请求 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 权限 → 如果 false，则调用 请求 Android 权限 → 绑定 On Permission Request Complete 并且仅在获得授权结果时开始对话。

验证： 授予权限后，进入 Play 模式并说话。角色应该能够接收并响应语音输入。

设备选择返回 false

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

原因： 请求的设备索引超出范围，或者设备名称与 GetAvailableCaptureDeviceNames().

修复： 调用 GetAvailableCaptureDeviceNames() 请先枚举设备，并且只使用该列表中的名称和索引。如果设备被添加或移除，索引可能会在会话之间发生变化。

验证： 调用 GetActiveCaptureDevice(OutInfo) 在选择后并确认 OutInfo.DeviceName 与目标设备一致。

下一步

配置角色音频配置对话输入