音频和麦克风问题

修复所有 Convai Unity SDK 平台上的麦克风输入失败和角色语音播放问题，包括 Android、iOS 和 WebGL。

Convai Unity SDK 中的音频故障分为两类：麦克风输入问题会阻止 SDK 捕获玩家的声音，以及音频输出问题会阻止角色的声音播放。这两类问题都会产生特定的错误代码和控制台消息，直接指向原因。本页涵盖这两类问题，并提供 Android、iOS 和 WebGL 的平台特定指导。

第一步检查

1

检查控制台中的音频错误代码

打开 Unity Console，并筛选 audio。音频故障会在以下会话错误中体现： ConvaiSessionEventRelay.OnSessionError。请查看以下错误代码：

• audio.mic_unavailable — 未找到麦克风设备
• audio.mic_permission_denied — 用户拒绝了权限，或平台要求用户手势
• audio.mic_publish_failed — 麦克风轨道无法发布到房间

此外，还要查看以以下内容为前缀的控制台消息： [RoomAudioRuntimeAdapter] 或 [AudioTrackManager] — 这些信息比单独的错误代码更详细。

2

确认 ConvaiAudioOutput 位于正确的 GameObject 上

ConvaiAudioOutput 必须位于 同一个 GameObject 上， ConvaiCharacter。该组件具有 [RequireComponent(typeof(ConvaiCharacter))] — 通过 Add Component 添加时，Unity 会强制执行这一点，但通过手动修改 prefab 或复制粘贴可能会违反。

如果 ConvaiAudioOutput 位于不同的 GameObject 上，你将在 Play 时看到此错误：

[ConvaiAudioOutput] 在 {gameObjectName} 上未找到 ConvaiCharacter 组件

该 GameObject 还需要一个 AudioSource 组件。Unity 会通过以下方式自动添加它： [RequireComponent(typeof(AudioSource))] 当你添加 ConvaiAudioOutput时，但请确认它存在且已启用。

ConvaiAudioOutput 用于原生平台（Windows、macOS、Linux、Android、iOS）上的角色语音播放。在 WebGL 上，音频通过浏览器音频上下文路由—— ConvaiAudioOutput 在 WebGL 构建中不会使用，也不需要存在。

3

检查 AudioSource 设置

选择 NPC GameObject 并检查 AudioSource 组件：

• 音量 必须大于 0
• 静音 必须未勾选
• AudioMixer 输出组（如果已分配）不能处于 −80 dB
• 空间混合 UI 风格角色应设为 0（2D），场景内定位角色应设为 1（3D）。如果空间混合为 1，而摄像机离角色很远，音频会被衰减。

另外还要检查 ConvaiAudioOutput NPC Inspector 中的字段：

字段	默认值	它控制什么
音量	1.0	角色语音增益（0–1）。在 AudioSource 音量之上应用。
是否静音	false	独立于 AudioSource 的静音切换来静音角色语音。
使用 3D 音频	true	启用 3D 空间音频。UI 风格角色应设为 false。
最小距离	1	音频开始衰减的距离。
最大距离	50	音频达到最小音量的距离。

4

确认用户手势触发连接（WebGL）

浏览器会在用户与页面交互之前阻止麦克风访问。在 WebGL 构建中， ConvaiManager.ConnectAsync() 必须在用户手势处理程序中调用（例如按钮 onClick 事件），而不能在场景加载时自动调用。

如果 SDK 在手势之前连接，麦克风发布将被中止，并出现：

[RoomAudioRuntimeAdapter] 因音频播放需要用户手势，麦克风发布已中止。

音频错误代码

错误代码	说明	常见原因
audio.mic_unavailable	未找到麦克风设备	未连接麦克风；WebGL 平台（始终返回没有设备）
audio.mic_permission_denied	访问麦克风的权限被拒绝	用户拒绝了系统权限对话框；WebGL 在用户手势之前调用
audio.mic_publish_failed	麦克风轨道无法发布到 LiveKit 房间	房间未连接；内部工厂未注册

ConvaiAudioOutput 设置错误

组件位于错误的 GameObject 上

控制台消息： [ConvaiAudioOutput] 在 {gameObjectName} 上未找到 ConvaiCharacter 组件

原因： ConvaiAudioOutput 不在与 ConvaiCharacter.

修复： 相同的 GameObject 上。请在 Hierarchy 中选择 NPC。确认 ConvaiAudioOutput, ConvaiCharacter，以及 AudioSource 都位于同一个 GameObject 上。如有需要，请移动 ConvaiAudioOutput 。

验证： 重新进入 Play Mode。 [ConvaiAudioOutput] 未找到 ConvaiCharacter 组件 错误不再出现在控制台中。

平台权限

Android

Android 需要 RECORD_AUDIO 权限。没有它，麦克风不可用，并且 audio.mic_permission_denied 会触发。

步骤 1 — 将权限添加到 AndroidManifest.xml：

如果你没有自定义的 AndroidManifest.xml，请在以下位置创建一个： Assets/Plugins/Android/AndroidManifest.xml。在 <manifest> 标签中添加以下行：

<uses-permission android:name="android.permission.RECORD_AUDIO" />

步骤 2 — 在 Player Settings 中设置麦克风使用说明：

打开 Edit → Project Settings → Player → Android → Other Settings。将 Microphone Usage Description 设置为面向用户的说明，例如： “用于与 AI 角色进行语音交互。”

运行时行为： Android 在第一次请求麦克风时会显示系统权限对话框。如果用户拒绝， audio.mic_permission_denied 会触发。SDK 不会自动重新请求该权限——如果用户最初拒绝了，你的应用必须引导用户在设备 Settings 中授予它。

如果权限对话框从未出现，请检查 RECORD_AUDIO 权限是否存在于 manifest 中。缺少权限会抑制对话框并静默拒绝访问。

iOS

WebGL

排查音频故障

症状	可能原因	修复	验证
audio.mic_permission_denied 在 Android 上	RECORD_AUDIO 缺少于 AndroidManifest.xml	添加权限；重新构建	应用在启动时请求麦克风权限；声音到达角色
audio.mic_permission_denied 在 iOS 上	NSMicrophoneUsageDescription Player Settings 中缺少	设置说明；重新构建	应用在首次启动时请求麦克风权限；声音到达角色
audio.mic_permission_denied 在 WebGL 上	在连接前没有用户手势	通过 UI 按钮点击触发连接	audio.mic_permission_denied 不再触发；麦克风输入已激活
audio.mic_unavailable	机器未连接麦克风	连接麦克风；检查操作系统音频设备	audio.mic_unavailable 连接时不再触发
audio.mic_unavailable 在 WebGL 上	平台始终返回空设备列表	预期如此——SDK 使用浏览器默认设备	无需操作；麦克风通过浏览器默认设备发布
[ConvaiAudioOutput] 在 X 上未找到 ConvaiCharacter 组件	ConvaiAudioOutput 位于错误的 GameObject 上	将其移动到与 ConvaiCharacter	在 Play 时错误不再出现在控制台中
角色文本出现但没有播放音频	AudioSource 静音、音量为 0，或混音器为 −80 dB	检查 AudioSource 组件在 NPC 上的	角色语音通过 NPC 播放 AudioSource
角色音频在 3D 中只从一只耳朵播放	AudioSource.spatialBlend 设为 1 且摄像机距离过远	降低 AudioSource 的 Max Distance 或将摄像机靠近一些	音频在合适距离下能在双耳播放
[RoomAudioRuntimeAdapter] 因房间音频路径尚未初始化，麦克风发布已中止。	ConnectAsync 在调用麦克风发布时尚未完成	在发布麦克风之前等待 OnSessionStateChanged 其带有 已连接 完成	在 已连接 状态
[AudioTrackManager] PublishMicrophoneAsync 已中止：LocalParticipant 为空	尝试发布时房间未连接	在任何音频发布之前确保处于完整的 Connected 状态	麦克风发布无错误
[AudioTrackManager] PublishMicrophoneAsync 失败：轨道为空	轨道创建在内部失败	检查 SDK 版本；重新安装包	重新安装后麦克风发布无错误
[RoomAudioRuntimeAdapter] 麦克风发布失败：未注册 IMicrophoneSourceFactory。	SDK 内部连接失败	重新安装 SDK；验证包版本是否为 4.2.0	重新安装后麦克风发布无错误
麦克风在 Editor 中正常，但在构建中不工作	缺少构建权限	检查上面的平台权限设置	设备构建中麦克风已激活

控制台日志参考

这些是音频子系统中的精确消息。在控制台中筛选 RoomAudioRuntimeAdapter 或 AudioTrackManager 可直接看到它们。

消息	级别	其含义
[RoomAudioRuntimeAdapter] 因音频播放需要用户手势，麦克风发布已中止。	警告	WebGL：在用户手势之前触发了连接
[RoomAudioRuntimeAdapter] 因房间音频路径尚未初始化，麦克风发布已中止。	警告	在房间音频路径准备好之前调用了麦克风发布
[RoomAudioRuntimeAdapter] 麦克风发布失败：未注册 IMicrophoneSourceFactory。	错误	缺少内部工厂——SDK 安装问题
[RoomAudioRuntimeAdapter] 在创建麦克风源时麦克风发布失败：{exception}	错误	创建麦克风源期间发生异常——请检查异常消息
[AudioTrackManager] PublishMicrophoneAsync 已中止：LocalParticipant 为空	错误	房间未连接；没有本地参与者
[AudioTrackManager] PublishMicrophoneAsync 失败：轨道为空	错误	麦克风轨道创建返回空值
[AudioTrackManager] PublishMicrophoneAsync 中发生异常：{exception}	错误	意外异常——请检查异常详情
[AudioTrackManager] SetMicMuted 设置 MicrophoneSource 静音失败：{exception}	错误	静音操作失败——通常是时序问题
[ConvaiAudioOutput] 已为角色 '{characterId}' 注册 AudioSource	调试	AudioSource 注册成功（仅在 Editor 或 Development Build 中可见）
[ConvaiAudioOutput] 在 {name} 上未找到 ConvaiCharacter 组件	错误	ConvaiAudioOutput 位于错误的 GameObject 上

下一步

有关如何启用详细音频日志并使用 音频 日志类别覆盖以查看所有 SDK 音频消息，请参阅 Debug Tools Reference。

调试工具参考