麦克风和音频捕获

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

UConvaiPlayerComponent 将所有可由蓝图调用的麦克风函数暴露在 Convai|Microphone 类别下。其内部驱动一个 UConvaiAudioCaptureComponent 实例，该实例封装了 Unreal AudioCapture 引擎插件，并通过 UConvaiMicrophoneSubsystem。在 Android 上， AndroidPermission 插件处理运行时麦克风权限。

若要查看完整的 UConvaiPlayerComponent 属性集——身份、会话、注视注意力和音频处理——请参阅 Convai Player 组件.

FCaptureDeviceInfoBP

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

字段	Type	默认值	描述
DeviceName	FString	""	在设备菜单中显示的人类可读名称。
DeviceIndex	int	0	采集设备列表中的从零开始索引。设备在添加或移除时，索引可能会在不同会话之间变化。
LongDeviceId	FString	""	平台相关的设备标识符。在 Windows 上，它比 DeviceIndex 在会话之间更稳定。
InputChannels	int	0	设备报告的输入通道数量。
PreferredSampleRate	int	0	设备的首选采样率，单位 Hz。
bSupportsHardwareAEC	布尔值	false	true 当设备支持硬件声学回声消除时。

Convai|Microphone 函数

这些 BlueprintCallable 函数都在 UConvaiPlayerComponent （蓝图显示名称 Convai Player).

设备枚举

函数	Parameters	返回值	描述
GetAvailableCaptureDeviceNames	—	TArray<FString>	所有可用输入设备的名称。请将这些字符串用作显示标签以及 DeviceName 的参数 SetCaptureDeviceByName.
GetAvailableCaptureDeviceDetails	—	TArray<FCaptureDeviceInfoBP>	完整的 FCaptureDeviceInfoBP 每个可用设备的结构体。包含索引、长 ID、通道数、采样率和 AEC 标志。
GetDefaultCaptureDeviceInfo	OutInfo（FCaptureDeviceInfoBP） 输出	布尔值	当前来源： 会验证 AudioCaptureComponent，然后始终返回 false 而不填充 OutInfo。不要依赖 OutInfo 来自此节点。请使用 GetAvailableCaptureDeviceDetails 或 GetActiveCaptureDevice 代替。
GetCaptureDeviceInfo	OutInfo（FCaptureDeviceInfoBP） 输出， DeviceIndex（int）	布尔值	填充 OutInfo 位于以下索引的设备的 DeviceIndex。返回 false 索引超出范围时。
GetActiveCaptureDevice	OutInfo（FCaptureDeviceInfoBP） 输出	—	填充 OutInfo 与当前选择的采集设备一起。

设备选择

函数	Parameters	返回值	描述
SetCaptureDeviceByIndex	DeviceIndex（int）	布尔值	打开位于以下索引的采集设备 DeviceIndex。返回 false 当索引超出范围或设备无法打开时返回。
SetCaptureDeviceByName	DeviceName（FString）	布尔值	打开枚举列表中最后一个其 DeviceName 与输入匹配的设备。若未找到匹配项则返回 false 当未找到匹配项时。

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

音量

函数	Parameters	返回值	描述
SetMicrophoneVolumeMultiplier	InVolumeMultiplier（float）	Success（bool）	按比例缩放捕获到的音频信号。 成功 反映的是采集组件是否可用，而不是麦克风采集当前是否正在流式传输或录制。
GetMicrophoneVolumeMultiplier	—	OutVolumeMultiplier（float）, Success（bool）	读取当前音量倍增值。 成功 反映采集组件可用性。

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

流式传输与录制状态

函数	类别	返回值	描述
GetIsStreaming （显示名称 是否正在流式传输)	`Convai	麦克风`	布尔值
GetIsRecording （显示名称 是否正在录制)	`Convai	麦克风`	布尔值

StartRecording, FinishRecording, UnmuteStreamingAudio，以及 MuteStreamingAudio 的文档见 音频流式传输与录制 部分 Convai Player 组件.

持久化设置

函数	Parameters	返回值	描述
SaveMicrophoneSettings	—	布尔值	快照保存玩家组件当前的采集设备和增益，然后通过 UConvaiMicrophoneSubsystem将其持久化。在玩家确认设备选择后调用此函数——仅选择设备只会在当前会话中生效，直到调用此函数。若 false 子系统不可用时返回。
ApplySavedMicrophoneSettings	—	布尔值	将已持久化的设备（如果已不再插入则跳过）和增益重新应用到玩家组件。会在 BeginPlay期间自动调用；若 UI 需要还原未保存的更改，可再次调用它。返回 false 子系统不可用时返回。

这两个函数都委托给 UConvaiMicrophoneSubsystem，如下所述。

UConvaiMicrophoneSubsystem

UConvaiMicrophoneSubsystem （蓝图显示名称 Convai 麦克风子系统）是一个 UGameInstanceSubsystem ，它在多个会话之间维护玩家的麦克风设备和增益偏好，因此选择不会再在每次启动时重置为系统默认值。其上所有暴露给蓝图的成员都使用 类别 = "Convai|Microphone".

节点	类型	Parameters	返回值	描述
获取 （显示名称 获取，派生——无显式 DisplayName 元数据）	BlueprintPure，静态	WorldContextObject	UConvaiMicrophoneSubsystem*	返回当前 GameInstance 的子系统实例。
GetMicrophoneSettings （显示名称 获取麦克风设置)	BlueprintPure	—	FConvaiMicrophoneSettings	返回子系统当前持有的设置。
HasSavedMicrophoneSettings （显示名称 是否已有保存的麦克风设置)	BlueprintPure	—	布尔值	true 当本会话在磁盘上找到了已保存记录，而不是回退到默认值时返回。
SaveMicrophoneSettings （显示名称 保存麦克风设置)	BlueprintCallable	InSettings（FConvaiMicrophoneSettings）	—	替换当前持有的设置并将其写入共享记录。广播 OnMicrophoneSettingsChanged。采用显式设置值——这与在 UConvaiPlayerComponent上同名节点不同，后者读取的是组件当前的设备和增益。
SaveMicrophoneSettingsFromPlayerComponent （显示名称 从玩家组件保存麦克风设置)	BlueprintCallable	PlayerComponent（UConvaiPlayerComponent）	布尔值	快照保存 PlayerComponent的当前采集设备和增益，然后将其持久化。这就是 UConvaiPlayerComponent::SaveMicrophoneSettings 在内部调用的内容。
ResetMicrophoneSettingsToDefaults （显示名称 将麦克风设置重置为默认值)	BlueprintCallable	—	—	忘记已保存的选择并删除共享记录。
GetAvailableMicrophoneNames （显示名称 获取可用麦克风名称)	BlueprintCallable	—	TArray<FString>	当前存在的设备名称，命名方式与 UConvaiPlayerComponent::GetAvailableCaptureDeviceNames.
IsSavedMicrophoneAvailable （显示名称 已保存的麦克风是否可用)	BlueprintCallable	—	布尔值	true 当某个设备已保存且当前已插入时返回。 false 没有任何已保存内容属于正常的“跟随系统默认值”情况，并非错误。
ApplySavedSettingsToPlayerComponent （显示名称 将已保存设置应用到玩家组件)	BlueprintCallable	PlayerComponent（UConvaiPlayerComponent）	布尔值	将已保存的增益，以及（如果仍可用的话）已保存的设备，应用到 PlayerComponent。返回 true 仅当已解析并选择了已保存的设备时。
OnMicrophoneSettingsChanged （显示名称 麦克风设置已更改)	BlueprintAssignable 事件	NewSettings（FConvaiMicrophoneSettings）	—	每当 SaveMicrophoneSettings 在子系统上运行时广播。

FConvaiMicrophoneSettings

FConvaiMicrophoneSettings (BlueprintType, 类别 = "Convai|Microphone"）是一个结构体 UConvaiMicrophoneSubsystem 会持久化。

字段	Type	默认值	描述
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 中。

在大多数蓝图中，请使用 UConvaiPlayerComponent 上的麦克风函数，而不是直接与 UConvaiAudioCaptureComponent 直接交互。玩家组件在内部进行委托，并提供上文各节中所述的更高级流式 API。

该组件声明了一个 Convai 特有的可由蓝图配置的属性；继承的 USynthComponent 属性同样适用。

属性	Type	类别	约束	描述
JitterLatencyFrames	int32	延迟	ClampMin = 0, ClampMax = 1024	为人为抖动缓冲声明的延迟设置。在当前插件源码中，Convai 采集实现不会读取此属性，因此更改它没有经过验证的运行时效果。

大多数设备枚举和设备切换行为都通过 UConvaiPlayerComponent ——上面列出的蓝图函数会委托到底层的 UConvaiAudioCaptureComponent 在内部，除了 GetDefaultCaptureDeviceInfo 玩家组件上的该方法，它目前不会转发到采集组件。

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

插件依赖

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

插件	已启用	目的
AudioCapture	true	Unreal Engine 内置插件，提供 FAudioCapture 和 USynthComponent-based 采集。Win64 和 Android 上所有麦克风输入都需要它。
AndroidPermission	true	Unreal Engine 内置插件，提供用于检查和请求 Android 运行时权限的蓝图节点。Android 上的麦克风访问需要它。

Android 麦克风权限

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

请求 android.permission.RECORD_AUDIO 在调用 StartSession 或 UnmuteStreamingAudio之前。若权限被拒绝，音频采集会静默地产生空数据。

请使用 AndroidPermission 蓝图节点来请求该权限：

1. 调用 检查 Android 权限 使用该权限字符串 android.permission.RECORD_AUDIO.
2. 如果返回值是 false，则调用 请求 Android 权限 针对同一字符串。
3. 绑定到 权限请求完成时 委托，并在确认已授予权限后再开始对话。

该 AndroidPermission 插件节点位于 Android Permission 蓝图类别中。它们在 Win64 上不起作用——同一蓝图图表无需平台分支即可在两个平台上工作。

相关参考

玩家组件页面涵盖完整的属性集；操作指南页面则逐步讲解在发布前选择和测试设备。

Convai 玩家组件配置麦克风