> 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 控制台，并筛选 `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))]` 属性——通过“添加组件”添加时，Unity 会强制满足此要求；但手动编辑预制件或复制粘贴时可能会破坏这一要求。

如果 `ConvaiAudioOutput` 位于其他 GameObject 上，点击 Play 时会看到以下错误：

`[ConvaiAudioOutput] ConvaiCharacter component not found on {gameObjectName}`

该 GameObject 还需要一个 `AudioSource` 组件。添加 `[RequireComponent(typeof(AudioSource))]` 时，Unity 会自动添加该组件； `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 检视面板中的自身字段：

| 字段            | 默认值   | 控制项                                 |
| ------------- | ----- | ----------------------------------- |
| **音量**        | 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` 与 `ConvaiCharacter`.

**修复方法：** 在 Hierarchy 中选择 NPC。确认 `ConvaiAudioOutput`, `ConvaiCharacter`，以及 `AudioSource` 都位于同一个 GameObject 上。移动 `ConvaiAudioOutput` （如有必要）。

**验证：** 重新进入播放模式。控制台中不再出现  `[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：无需配置播放器设置字段：**

Android 的播放器设置中没有 **麦克风使用说明** 字段，该字段仅适用于 iOS 和 macOS 构建。SDK 会在运行时通过  `RECORD_AUDIO`  权限自动发起请求，具体由  `ConvaiPermissionService` 使用 Unity 的  `Permission.RequestUserPermission`  API 完成。除了步骤 1 中的清单条目外，无需进行其他播放器设置配置。

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

如果权限对话框始终没有出现，请检查清单中是否包含  `RECORD_AUDIO`  权限。缺少该权限会导致对话框不显示，并在没有提示的情况下拒绝访问。
{% endtab %}

{% tab title="iOS" %}
iOS 要求在  `NSMicrophoneUsageDescription`  所在的  `Info.plist` 中设置该项。否则，应用在首次访问麦克风时会立即崩溃。

**在播放器设置中设置说明：**

打开 **编辑 → 项目设置 → 播放器 → iOS → 其他设置**。将 **麦克风使用说明** 设置为面向用户的说明，例如： `"Used for voice interaction with AI characters."`

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

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

{% hint style="danger" %}
提交 iOS 构建版本到 App Store 时，如果缺少 `NSMicrophoneUsageDescription` ，系统会自动拒绝该版本。即使训练模拟或体验中的麦克风访问是可选的，也要设置此字段。
{% endhint %}
{% endtab %}

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

**1. 仅提供一个占位设备。** SDK 的 WebGL 麦克风源工厂（`WebGLMicrophoneSourceFactory.GetAvailableDevices()`）会返回一个占位条目 `"Default Microphone"`，而不是为每个实体设备各返回一个条目。实际设备选择由浏览器在其自身的 `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 上               | 将其移至与 `ConvaiCharacter`                                                          | 点击 Play 后，错误不再显示在 Console 中                 |
| 角色转录内容已显示，但没有音频播放                                                                                      | `AudioSource` 已静音、音量为 0，或混音器设为 −80 dB                | 检查 NPC 上的 `AudioSource` 组件                                                       | 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` 状态后，麦克风发布不再报错                |
| `[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> | 重新安装后，麦克风发布成功                               |
| 麦克风在编辑器中正常工作，但在构建版本中无法使用                                                                               | 缺少构建权限                                               | 检查上文的平台权限设置                                                                      | 麦克风在设备构建版本中正常启用                             |

### 控制台日志参考

这些是音频子系统输出的确切消息。在控制台中筛选 `RoomAudioRuntimeAdapter` 或 `AudioTrackManager` 即可直接查看这些消息。

| 消息                                                                                                     | 级别 | 含义                                     |
| ------------------------------------------------------------------------------------------------------ | -- | -------------------------------------- |
| `[RoomAudioRuntimeAdapter] Microphone publish aborted because audio playback requires a user gesture.` | 警告 | WebGL：在用户手势触发前就调用了 connect             |
| `[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 已成功注册（仅在编辑器或开发构建版本中可见）     |
| `[ConvaiAudioOutput] ConvaiCharacter component not found on {name}`                                    | 错误 | `ConvaiAudioOutput` 位于错误的 GameObject 上 |

### 后续步骤

有关如何启用详细音频日志记录，以及如何使用 `Audio` 日志类别覆盖项查看所有 SDK 音频消息，请参阅《调试工具参考》。

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
