音频和麦克风问题
修复 Convai Unreal Engine 插件中的音频采集失败、错误的麦克风设备、Android 权限错误和音频播放问题。
使用此页面解决插件无法捕获麦克风输入、使用了错误的音频设备，或无法播放角色音频的问题。连接和 API 密钥问题在 连接和 API 密钥问题.
第一步检查
在调查具体症状之前，请先完成这四项检查。
未检测到麦克风输入
症状： 角色从不对语音作出响应。 ConvaiAudioLog Output Log 显示捕获设备警告，或者在 Play 开始后没有出现音频转发活动。
原因—— AudioCapture 插件已禁用： 该 Convai Audio Capture 组件依赖于引擎的 AudioCapture 插件。如果该插件被禁用，则无法打开任何捕获设备。
修复： 打开 Edit > Plugins，搜索 Audio Capture，启用它，并重启编辑器。
验证： 进入 Play 模式并说话。 ConvaiAudioLog 应显示音频数据正在被捕获并转发。
原因——未连接麦克风或未设置默认设备： 操作系统报告没有默认捕获设备，因此 ConvaiAudioCaptureComponent 无法打开流。在 Output Log 中你会看到：
ConvaiAudioLog: Warning: OpenStream 返回 false修复： 连接麦克风，在操作系统声音设置中将其设为默认录音设备，并重启编辑器。
验证： 在 Output Log 中， ConvaiAudioLog 应不再显示 OpenStream returned false 警告，在 Play 开始后。
选择了错误的麦克风设备
症状： 音频来自错误的输入——例如，内置摄像头麦克风而不是耳机麦克风。
原因： ConvaiAudioCaptureComponent 除非设置了明确的设备索引，否则会打开系统默认设备。如果操作系统默认设备不是你想要的设备，输入就会来自错误的来源。
修复： 使用 获取可用捕获设备详情 在 Convai 玩家 组件来枚举可用设备。该节点返回一个结构体数组 FCaptureDeviceInfoBP 结构体。每个结构体公开 DeviceName, DeviceIndex, LongDeviceId, InputChannels, PreferredSampleRate，以及 bSupportsHardwareAEC。传入 DeviceIndex 正确设备的 按索引设置捕获设备，或者使用 按名称设置捕获设备 ，当你希望按设备名称选择时使用。
验证： 选择设备后，说话并在 ConvaiAudioLog 中确认流已在正确的设备名称上打开。
Player 组件不会将音频转发给聊天机器人
症状： 麦克风已被检测到且似乎正在捕获，但角色仍然没有响应。在 ConvaiPlayerLog.
原因—— Convai 玩家 组件未链接到聊天机器人： UConvaiPlayerComponent 必须关联到 UConvaiChatbotComponent 它正在对话的对象。没有该链接，捕获的音频不会转发到任何角色会话。
修复： 在玩家 Pawn 的 Blueprint 中，选择 Convai 玩家 组件，并确认已设置聊天机器人组件引用。如果你正在使用 Blueprint 节点，请确保 开始说话 节点接收到一个有效的 Convai 聊天机器人 组件。
验证： 进入 Play 模式并触发说话动作。 ConvaiPlayerLog 应显示音频正在发送，且 ConvaiChatbotComponentLog 应显示正在接收响应。
原因——未按住按键说话键，或说话触发器未触发： Player 组件默认不会持续捕获；必须激活一个触发器。
修复： 确认调用 开始说话 在 Convai 玩家 组件的 Blueprint 或输入绑定是否正常触发。向 Blueprint 事件添加一个临时 Print String 以验证执行。
验证： 当按住触发键时， ConvaiPlayerLog 应显示音频帧正在入队。
音频通道不匹配警告
症状： 音频捕获已打开，但语音质量下降、杂乱或无声。Output Log 显示：
原因： 捕获设备报告的输入通道超过两个（例如，多通道音频接口）。该插件仅处理单声道或立体声流；多通道输入虽然可被接受，但可能产生错误输出。
修复： 在操作系统音频设置中，在打开流之前将捕获设备配置为单声道或立体声格式。或者，选择一个原生以单声道或立体声呈现的其他设备。
验证： 该警告不再出现在 ConvaiAudioLog 在重启捕获流后。
Android 上没有音频
症状： 该插件在 Windows 上工作正常，但当应用运行在 Android 设备上时，无法接收到麦克风输入。
原因： Android 需要 android.permission.RECORD_AUDIO 权限需要在清单中声明并在运行时授予。
修复：
打开 Edit > Plugins，搜索
Android Permission，并确认它已启用。重新构建并部署。该插件会添加
android.permission.RECORD_AUDIO通过Convai_AndroidAPL.xml.首次启动时，当 Android 提示时授予麦克风权限。如果之前已拒绝该权限，请在 Android 应用设置中手动启用它。
验证： 在 Android 设备上，按提示授予麦克风权限。授予权限后，角色应对语音作出响应。
如果你的项目需要在开始场景前检查权限，请使用该插件的 Android 权限辅助工具或 Unreal 的 Android 权限节点，并在权限被拒绝时向用户显示消息。
原因： 该插件打包了原生音频库（libconvai_client.so, libconvai_http_helper.so），它们必须存在于 APK 中。如果 ProGuard 或自定义打包步骤将其移除，则设备上的音频初始化会失败，且游戏输出中不会有明确的日志消息。
修复： 使用 adb logcat 用于读取设备上的系统日志——在未额外处理的已部署 APK 上，游戏 Output Log 不会被写入。筛选与 Convai 相关的条目：
如果你看到 UnsatisfiedLinkError 或 dlopen failed 引用 libconvai_client.so，确认 Convai_AndroidAPL.xml 未被移除或覆盖，并且你的 Android 构建仍然打包了该插件的原生库。
验证： 在重新干净打包后，运行 adb shell ls /data/app/<your.package>/lib/arm64/ 以确认 libconvai_client.so 已存在于已安装的 APK 中。
角色音频不播放——嘴巴在动但没有声音
症状： 该 Convai 面部同步 组件在播放动画（嘴巴移动），这表明响应已到达，但角色没有播放任何音频。Output Log 可能包含：
原因： 从 Convai 接收的音频数据无法解码。这通常是暂时性的网络问题——部分或损坏的数据包——而不是配置问题。
修复： 此错误通常会在下一轮自动解决。如果它持续出现在多轮中：
检查到……连接上的网络质量和丢包情况
realtime-api.convai.com.确认 API 密钥有效——身份验证失败可能导致响应数据格式错误。
重新进入 Play 模式以建立一个新会话。
验证： 在下一次成功轮次中，音频应正常播放，且警告不应再次出现。
音频设备热插拔未生效
症状： 在应用运行时更改当前活动捕获设备——例如插入耳机——不会切换输入。该插件会继续使用之前的设备。
原因——未显式触发设备切换： 较新的插件版本支持麦克风热插拔。不过，设备切换必须通过 Blueprint 显式触发；该插件不会自动检测硬件变化。
修复： 调用 按索引设置捕获设备 在 Convai 玩家 带有新的 DeviceIndex 在连接新设备后。请先使用以下方式枚举当前设备列表： 获取可用捕获设备详情 以获取新设备的正确索引。
验证： 调用后 按索引设置捕获设备，对着新设备说话并确认 ConvaiAudioLog 显示来自更新后设备的数据。
UE 版本说明——音频捕获 API 差异
在 Unreal Engine 5.3 及更高版本中，该插件使用 OpenAudioCaptureStream()。在 UE 5.2 及更早版本中，它使用 OpenCaptureStream()。在 UE 5.2 及更早版本中，设备偶发故障可能产生退化的（零长度）音频缓冲区；该插件会静默丢弃这些缓冲区。如果你在较旧引擎版本上看到间歇性的音频中断，升级到 UE 5.3 或更高版本可解决此类问题。
Output Log 参考—— ConvaiAudioLog 消息
ConvaiAudioLog 消息OpenStream returned false
警告
操作系统报告没有可用的捕获设备
连接麦克风；检查操作系统音频设置
音频捕获组件仅支持单声道和立体声麦克风输入 - 音频可能会被损坏
警告
设备通道数 > 2
在操作系统设置中将设备设为单声道/立体声
SetCaptureDevice: 设备索引 %d 的 OpenStream 失败
警告
无法打开请求的设备索引
重新枚举设备；索引可能已更改
PlayVoiceData: 无法解析 wav 头，原因：%s
警告
接收到的音频数据格式错误
通常是暂时性的；检查网络质量
下一步
口型同步与动画问题诊断与日志导出最后更新于
这有帮助吗？