音频和麦克风问题

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

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

首要检查

1

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

打开 Unity Console 并筛选 音频。音频故障会以会话错误的形式出现在 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 会强制执行这一点，但手动编辑预制体或复制粘贴可能会违反这一要求。

如果 ConvaiAudioOutput 位于不同的 GameObject 上，运行时你会看到此错误：

[ConvaiAudioOutput] ConvaiCharacter component not found on {gameObjectName}

该 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] Microphone publish aborted because audio playback requires a user gesture.

音频错误代码

错误代码	描述	常见原因
audio.mic_unavailable	未找到麦克风设备	机器未连接麦克风
audio.mic_permission_denied	访问麦克风的权限被拒绝	用户拒绝了系统权限对话框；WebGL 在用户手势之前被调用
audio.mic_publish_failed	麦克风轨道无法发布到 LiveKit 房间	房间未连接；内部工厂未注册

ConvaiAudioOutput 设置错误

组件位于错误的 GameObject 上

控制台消息： [ConvaiAudioOutput] ConvaiCharacter component not found on {gameObjectName}

原因： ConvaiAudioOutput 不位于与以下对象相同的 GameObject 上： ConvaiCharacter.

修复： 在 Hierarchy 中选中 NPC。确认 ConvaiAudioOutput, ConvaiCharacter，以及 AudioSource 都位于同一个 GameObject 上。将 ConvaiAudioOutput 在需要时移到此处。

验证： 重新进入 Play 模式。 [ConvaiAudioOutput] ConvaiCharacter component not found 错误不再出现在控制台中。

平台权限

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 字段：

Android 没有 麦克风使用说明 字段——该字段仅存在于 iOS 和 macOS 构建中。SDK 会通过 RECORD_AUDIO 在运行时自动请求该权限，使用 ConvaiPermissionService，并使用 Unity 的 Permission.RequestUserPermission API。除步骤 1 中的 manifest 条目外，无需额外的 Player Settings 配置。

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

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

iOS

iOS 需要 NSMicrophoneUsageDescription 位于 Info.plist。如果没有它，应用在首次访问麦克风时会立即崩溃。

在 Player Settings 中设置说明：

打开 编辑 → 项目设置 → Player → iOS → 其他设置。将 麦克风使用说明 设置为面向用户的说明，例如： “用于与 AI 角色进行语音交互。”

Unity 会将此值写入 Info.plist ，在构建期间。

运行时行为： iOS 在首次访问麦克风时会显示系统权限对话框。如果用户拒绝， audio.mic_permission_denied 会触发。SDK 不会重新请求该权限——请引导用户进入 iOS 设置 → 隐私与安全 → 麦克风 以重新启用它。

如果向 App Store 提交 iOS 构建时没有 NSMicrophoneUsageDescription 会导致自动拒绝。即使在你的训练模拟或体验中麦克风访问是可选的，也请设置此字段。

WebGL

WebGL 有两个会影响麦克风访问的限制：

1. 单一占位设备。 SDK 的 WebGL 麦克风源工厂（WebGLMicrophoneSourceFactory.GetAvailableDevices()）只返回一个占位条目， “默认麦克风”，而不是每个物理设备返回一个条目。浏览器会在其自身的 getUserMedia 权限提示中处理实际设备选择——SDK 无法在此平台上枚举或选择特定的物理麦克风。

2. 需要用户手势。 浏览器强制规定，麦克风访问只能在用户手势处理程序中请求（按钮点击、按键等）。在没有先前用户交互的情况下于场景加载时自动调用 connect，将导致：

[RoomAudioRuntimeAdapter] Microphone publish aborted because audio playback requires a user gesture.

WebGL 的推荐模式：

添加一个 开始对话 按钮到场景中。将其 onClick 连接到调用你的连接逻辑。不要在 Start() 或 Awake().

// 由 UI 按钮 onClick 事件调用——这就是用户手势
[SerializeField] private ConvaiManager _convaiManager;

public void OnStartButtonClicked()
{
    _ = _convaiManager.ConnectAsync();
}

麦克风访问需要 HTTPS。 浏览器只会在 HTTPS 页面上授予麦克风访问权限。HTTP 部署将静默失败，无法获取麦克风，从而导致 audio.mic_permission_denied。唯一的例外是 localhost —— 大多数浏览器允许在 http://localhost 上进行本地开发时访问麦克风。

排查音频故障

症状	可能原因	修复方法	验证
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 在连接时不再触发
[ConvaiAudioOutput] ConvaiCharacter component not found on X	ConvaiAudioOutput 位于错误的 GameObject 上	将其移动到与以下对象相同的 GameObject： ConvaiCharacter	播放时错误不再出现在控制台中
角色转写出现，但没有音频播放	AudioSource 已静音、音量为 0，或混音器为 −80 dB	检查 AudioSource NPC 上的组件	角色语音通过 NPC 播放 AudioSource
3D 中角色音频只从一侧耳朵播放	AudioSource.spatialBlend 设为 1，且相机距离过远	减小 AudioSource 的 Max Distance，或将相机移近	在合适距离下，音频可在双耳中播放
[RoomAudioRuntimeAdapter] Microphone publish aborted because the room audio path is not initialized.	ConnectAsync 在调用麦克风发布时尚未完成	等待 OnSessionStateChanged 中，且 Connected 后再发布麦克风	麦克风在之后无错误发布 Connected state
[AudioTrackManager] PublishMicrophoneAsync aborted: LocalParticipant is null	在尝试发布时，房间尚未连接	在进行任何音频发布前，确保处于完整的 Connected 状态	麦克风无错误发布
[AudioTrackManager] PublishMicrophoneAsync failed: track is null	轨道创建在内部失败	检查 SDK 版本；重新安装包	重新安装后麦克风无错误发布
[RoomAudioRuntimeAdapter] Microphone publish failed: IMicrophoneSourceFactory not registered.	SDK 内部接线失败	重新安装 SDK；确认包版本为 4.6.0	重新安装后麦克风无错误发布
麦克风在 Editor 中可用，但在构建中不可用	缺少构建权限	检查上面的平台权限设置	麦克风在设备构建中激活

控制台日志参考

这些是音频子系统的确切消息。在 Console 中筛选 RoomAudioRuntimeAdapter 或 AudioTrackManager 会直接显示它们。

消息	级别	含义
[RoomAudioRuntimeAdapter] Microphone publish aborted because audio playback requires a user gesture.	警告	WebGL：在用户手势之前触发了连接
[RoomAudioRuntimeAdapter] Microphone publish aborted because the room audio path is not initialized.	警告	在房间音频路径就绪之前调用了麦克风发布
[RoomAudioRuntimeAdapter] Microphone publish failed: IMicrophoneSourceFactory not registered.	错误	缺少内部工厂——SDK 安装问题
[RoomAudioRuntimeAdapter] Microphone publish failed while creating microphone source: {exception}	错误	创建麦克风源时发生异常——检查异常消息
[AudioTrackManager] PublishMicrophoneAsync aborted: LocalParticipant is null	错误	房间未连接；没有本地参与者
[AudioTrackManager] PublishMicrophoneAsync failed: track is null	错误	麦克风轨道创建返回 null
[AudioTrackManager] Exception in PublishMicrophoneAsync: {exception}	错误	意外异常——检查异常详细信息
[AudioTrackManager] SetMicMuted failed to set mute on MicrophoneSource: {exception}	错误	静音操作失败——通常是时序问题
[ConvaiAudioOutput] Registered AudioSource for character '{characterId}'	调试	AudioSource 注册成功（仅在 Editor 或 Development Build 中可见）
[ConvaiAudioOutput] ConvaiCharacter component not found on {name}	错误	ConvaiAudioOutput 位于错误的 GameObject 上

下一步

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

调试工具参考