> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/audio-and-microphone-issues.md).

# 音频和麦克风问题

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

### 第一步检查

{% stepper %}
{% step %}

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

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

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

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

{% step %}

#### 确认 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`时，但请确认它存在且已启用。

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

{% step %}

#### 检查 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    | 音频达到最小音量的距离。                      |
| {% endstep %} |       |                                   |

{% step %}

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

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

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

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

### 音频错误代码

| 错误代码                          | 说明                    | 常见原因                         |
| ----------------------------- | --------------------- | ---------------------------- |
| `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 组件` 错误不再出现在控制台中。

### 平台权限

{% tabs %}
{% tab title="Android" %}
Android 需要 `RECORD_AUDIO` 权限。没有它，麦克风不可用，并且 `audio.mic_permission_denied` 会触发。

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

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

```xml
<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 中授予它。

{% hint style="warning" %}
如果权限对话框从未出现，请检查 `RECORD_AUDIO` 权限是否存在于 manifest 中。缺少权限会抑制对话框并静默拒绝访问。
{% endhint %}
{% endtab %}

{% tab title="iOS" %}
iOS 需要 `NSMicrophoneUsageDescription` 在 `Info.plist`。没有它，应用在首次访问麦克风时会立即崩溃。

**在 Player Settings 中设置该说明：**

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

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

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

{% hint style="danger" %}
如果向 App Store 提交 iOS 构建时没有 `NSMicrophoneUsageDescription` ，会导致自动拒绝。即使你的训练模拟或体验中麦克风访问是可选的，也要设置此字段。
{% endhint %}
{% endtab %}

{% tab title="WebGL" %}
WebGL 有两个会影响麦克风访问的限制：

**1. 不进行设备枚举。** `MicrophoneDeviceService.GetAvailableDevices()` 在 WebGL 上始终返回空列表。SDK 使用浏览器的默认输入设备——该平台不支持在 SDK 层级进行设备选择。

**2. 需要用户手势。** 浏览器强制规定，麦克风访问只能在用户手势处理程序中请求（按钮点击、按键等）。在场景加载时自动调用连接——且之前没有用户交互——会导致：

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

**WebGL 的推荐模式：**

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

```csharp
// 从 UI Button 的 onClick 事件调用——这就是一个用户手势
[SerializeField] private ConvaiManager _convaiManager;

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

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

### 排查音频故障

| 症状                                                                   | 可能原因                                               | 修复                                                                               | 验证                                          |
| -------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------- |
| `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；验证包版本是否为 <code class="expression">space.vars.unity\_sdk\_version</code> | 重新安装后麦克风发布无错误                               |
| 麦克风在 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。

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/debug-tools-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/audio-and-microphone-issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.