麦克风和音频采集

Convai Player Component 上的麦克风设备枚举、选择和音量、音频采集组件以及 Android 权限参考。

UConvaiPlayerComponent 在以下类别下公开所有可由 Blueprint 调用的麦克风函数： Convai|Microphone 。内部它驱动一个 UConvaiAudioCaptureComponent 实例，该实例封装了 Unreal AudioCapture 引擎插件。在 Android 上， AndroidPermission 该插件负责运行时麦克风权限。

有关完整的 UConvaiPlayerComponent 属性集——身份、会话、凝视注意力和音频处理——请参见 Convai Player Component.

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.

ConvaiAudioCaptureComponent

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

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

该组件声明了一个 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 角色将收不到语音输入。插件不会记录权限被拒绝的消息，不过流打开失败仍可能产生捕获警告。

请求 android.permission.RECORD_AUDIO ，然后再调用 StartSession 或 UnmuteStreamingAudio。如果权限被拒绝，音频捕获将静默地产生无数据输出。

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

1. 调用 检查 Android 权限 使用权限字符串 android.permission.RECORD_AUDIO.
2. 如果返回值为 false，则调用 请求 Android 权限 ，并使用相同的字符串。
3. 绑定到 On Permission Request Complete 委托，并且仅在确认授予权限后再开始对话。

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

相关参考

玩家组件页面涵盖完整属性面；操作指南页面则会引导你在发布前选择并测试设备。

Convai Player 组件配置麦克风