> 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 平台上的麦克风输入失败和角色语音播放问题，包括 Android、iOS 和 WebGL。

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

### 首要检查

{% stepper %}
{% step %}

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

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

如果 `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 构建中不使用，也不需要存在。
{% 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] Microphone publish aborted because audio playback requires a user gesture.`
{% endstep %}
{% endstepper %}

### 音频错误代码

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

### 平台权限

{% 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 字段：**

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

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

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

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

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

打开 **编辑 → 项目设置 → Player → iOS → 其他设置**。将 **麦克风使用说明** 设置为面向用户的说明，例如： `“用于与 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. 单一占位设备。** SDK 的 WebGL 麦克风源工厂（`WebGLMicrophoneSourceFactory.GetAvailableDevices()`）只返回一个占位条目， `“默认麦克风”`，而不是每个物理设备返回一个条目。浏览器会在其自身的 `getUserMedia` 权限提示中处理实际设备选择——SDK 无法在此平台上枚举或选择特定的物理麦克风。

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

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

**WebGL 的推荐模式：**

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

```csharp
// 由 UI 按钮 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` 在连接时不再触发            |
| `[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；确认包版本为 <code class="expression">space.vars.unity\_sdk\_version</code> | 重新安装后麦克风无错误发布                               |
| 麦克风在 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。

{% 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.