> 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-unreal-engine-plugin/troubleshooting/audio-and-microphone-issues.md).

# 音频和麦克风问题

修复 Convai Unreal Engine 插件中的音频捕获失败、麦克风设备错误、Android 权限错误和音频播放问题。

使用此页面来解决插件无法捕获麦克风输入、使用了错误的音频设备，或无法播放角色音频的问题。连接和 API 密钥问题见 [连接和 API 密钥问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md).

### 一线检查

在排查具体症状之前，请先完成这四项检查。

{% stepper %}
{% step %}

#### 打开输出日志并按 ConvaiAudioLog 进行筛选

打开 **窗口 > 输出日志**，输入 `ConvaiAudioLog` 到搜索框中，并查找错误或警告条目。大多数音频捕获失败会在按下 Play 后立刻在这里显示一条消息。
{% endstep %}

{% step %}

#### 确认 AudioCapture 插件已启用

打开 **Edit > Plugins**，搜索 `Audio Capture`，并确认其已启用。 `Convai Audio Capture` 组件依赖于此引擎插件。如果它被禁用，将无法打开任何捕获设备。
{% endstep %}

{% step %}

#### 确认操作系统中已设置默认麦克风

在 Windows 上，打开 **声音设置 > 输入** ，并确认已选择默认录音设备且未静音。当未设置明确的设备索引时，Unreal Engine 会使用操作系统默认设备。
{% endstep %}

{% step %}

#### 在 Android 上——确认已授予麦克风权限

在设备上启动应用，前往 **设置 > 应用 > \[你的应用] > 权限**，并确认已授予麦克风访问权限。该插件声明了 `android.permission.RECORD_AUDIO` 在 `Convai_AndroidAPL.xml`，但用户仍需在设备上授予运行时权限。
{% endstep %}
{% endstepper %}

### 未检测到麦克风输入

**症状：** 角色始终不会回应语音。 `ConvaiAudioLog` 输出日志显示捕获设备警告，或者在 Play 开始后没有出现音频转发活动。

**原因—— `AudioCapture` 插件已禁用：** 该 `Convai Audio Capture` 组件依赖于引擎的 `AudioCapture` 插件。如果该插件被禁用，将无法打开任何捕获设备。

**修复：** 打开 **Edit > Plugins**，搜索 `Audio Capture`，启用它，并重启编辑器。

**验证：** 进入 Play 模式并说话。 `ConvaiAudioLog` 应显示音频数据正在被捕获并转发。

***

**原因——未连接麦克风或未设置默认设备：** 操作系统报告没有默认捕获设备，因此 `ConvaiAudioCaptureComponent` 无法打开流。在输出日志中你会看到：

```
ConvaiAudioLog: Warning: OpenStream returned false
```

**修复：** 连接一个麦克风，在操作系统声音设置中将其设为默认录音设备，并重启编辑器。

**验证：** 在输出日志中， `ConvaiAudioLog` 不应再显示 `OpenStream returned false` 警告，Play 开始后。

### 选择了错误的麦克风设备

**症状：** 音频是从错误的输入源捕获的——例如，使用的是内置摄像头麦克风而不是耳机。

**原因：** `ConvaiAudioCaptureComponent` 会打开系统默认设备，除非设置了明确的设备索引。如果操作系统默认设备不是期望的设备，输入就会来自错误的来源。

**修复：** 使用 `Get Available Capture Device Details` 在 `Convai Player` 组件来枚举可用设备。该节点返回一个 `FCaptureDeviceInfoBP` 结构体数组。每个结构体公开 `DeviceName`, `DeviceIndex`, `LongDeviceId`, `InputChannels`, `PreferredSampleRate`，以及 `bSupportsHardwareAEC`。传入正确设备的 `DeviceIndex` 到 `Set Capture Device By Index`，或者使用 `Set Capture Device By Name` ，当你希望按设备名称选择时使用。

**验证：** 选择设备后，说话并在 `ConvaiAudioLog` 中确认流已在正确的设备名称上打开。

### Player 组件不会将音频转发给聊天机器人

**症状：** 麦克风已被检测到，似乎也在捕获，但角色仍然没有回应。 `ConvaiPlayerLog`.

**原因—— `Convai Player` 组件未与聊天机器人关联：** `UConvaiPlayerComponent` 必须与 `UConvaiChatbotComponent` 它正在对话的对象关联。没有这种关联，捕获到的音频不会被转发到任何角色会话。

**修复：** 在玩家 Pawn 的 Blueprint 中，选择 `Convai Player` 组件，并确认已设置聊天机器人组件引用。如果你使用 Blueprint 节点，请确保 `Start Talking` 节点接收到一个有效的 `Convai 聊天机器人` 组件。

**验证：** 进入 Play 模式并触发说话动作。 `ConvaiPlayerLog` 应显示音频正在发送，而 `ConvaiChatbotComponentLog` 应显示已收到响应。

***

**原因——未按住按键说话或说话触发未生效：** 默认情况下，玩家组件不会持续捕获；必须有一个触发器处于激活状态。

**修复：** 确认调用 `Start Talking` 在 `Convai Player` 组件的 Blueprint 或输入绑定确实在正常触发。在 Blueprint 事件中添加一个临时 Print String 以验证执行。

**验证：** 在按住触发器时， `ConvaiPlayerLog` 应显示音频帧正在入队。

### 音频通道不匹配警告

**症状：** 音频捕获已打开，但语音质量下降、乱码或无声。输出日志显示：

```
ConvaiAudioLog: Warning: Audio capture components only support mono and stereo mic input - Audio might be mangeled
```

**原因：** 捕获设备报告的输入通道数超过两个（例如，多通道音频接口）。该插件仅处理单声道或立体声流；多通道输入会被接受，但可能产生不正确的输出。

**修复：** 在操作系统音频设置中，在打开流之前将捕获设备配置为单声道或立体声格式。或者，选择一个原生以单声道或立体声呈现的其他设备。

**验证：** 该警告不再出现在 `ConvaiAudioLog` 中，捕获流重启后。

### Android 上没有音频

**症状：** 该插件在 Windows 上工作正常，但当应用运行在 Android 设备上时却收不到麦克风输入。

{% tabs %}
{% tab title="未授予权限" %}
**原因：** Android 需要 `android.permission.RECORD_AUDIO` 需要在清单中声明权限并在运行时授予。

**修复：**

1. 打开 **Edit > Plugins**，搜索 `Android Permission`，并确认其已启用。
2. 重新构建并部署。该插件会添加 `android.permission.RECORD_AUDIO` 到 `Convai_AndroidAPL.xml`.
3. 首次启动时，当 Android 提示时授予麦克风权限。如果之前已拒绝，请在 Android 应用设置中手动启用。

**验证：** 在 Android 设备上，当提示时授予麦克风权限。权限授予后，角色应能响应语音。

如果你的项目需要在开始场景前检查权限，请使用插件的 Android 权限辅助功能或 Unreal 的 Android 权限节点，并在权限被拒绝时向用户显示消息。
{% endtab %}

{% tab title="缺少原生库" %}
**原因：** 该插件捆绑了必须存在于 APK 中的原生音频库（`libconvai_client.so`, `libconvai_http_helper.so`）。如果 ProGuard 或自定义打包步骤将它们移除，设备上的音频初始化将失败，而且游戏输出中不会有清晰的日志信息。

**修复：** 使用 `adb logcat` 以读取设备上的系统日志——在已部署的 APK 上，游戏输出日志不会在没有额外步骤的情况下写入。按 Convai 相关条目筛选：

```
adb logcat -s ConvaiAudioLog:V LogConvai:V
```

如果你看到 `UnsatisfiedLinkError` 或 `dlopen failed` 引用了 `libconvai_client.so`，请确认 `Convai_AndroidAPL.xml` 没有被移除或覆盖，并且你的 Android 构建仍然打包了该插件的原生库。

**验证：** 在重新干净地打包后，运行 `adb shell ls /data/app/<your.package>/lib/arm64/` 以确认 `libconvai_client.so` 已存在于已安装的 APK 中。
{% endtab %}
{% endtabs %}

### 角色音频不播放——嘴在动但没有声音

**症状：** 该 `Convai Face Sync` 组件会播放动画（嘴在动），这表明响应已经到达，但角色没有发出音频。输出日志中可能包含：

```
ConvaiAudioStreamerLog: Warning: PlayVoiceData: Failed to parse wav header, reason: <detail>
```

**原因：** 从 Convai 接收到的音频数据无法解码。这通常是一个短暂的网络问题——部分数据包或损坏的数据包——而不是配置问题。

**修复：** 此错误通常会在下一轮自动恢复。如果它在多轮中持续出现：

1. 检查到 `realtime-api.convai.com`.
2. 确认 API 密钥有效——认证失败可能导致响应数据格式异常。
3. 重新进入 Play 模式以建立新的会话。

**验证：** 在下一次成功的轮次中，音频应正常播放，且该警告不应再次出现。

### 音频设备热插拔未生效

**症状：** 在应用运行时更改活动捕获设备——例如插入耳机——不会切换输入。插件会继续使用之前的设备。

**原因——未显式触发设备切换：** 较新的插件版本支持麦克风热插拔。然而，设备切换必须通过 Blueprint 显式触发；插件不会自动检测硬件变化。

**修复：** 调用 `Set Capture Device By Index` 在 `Convai Player` 带有新的 `DeviceIndex` 在新设备连接后。首先使用 `Get Available Capture Device Details` 枚举当前设备列表，以获取新设备的正确索引。

**验证：** 调用 `Set Capture Device By Index`后，对新设备说话并确认 `ConvaiAudioLog` 显示来自更新后设备的数据。

### UE 版本说明——音频捕获 API 差异

{% hint style="info" %}
在 Unreal Engine 5.3 及更高版本中，插件使用 `OpenAudioCaptureStream()`。在 UE 5.2 及更早版本中，它使用 `OpenCaptureStream()`。在 UE 5.2 及更早版本中，偶尔的设备异常会产生退化的（零长度）音频缓冲区；插件会静默丢弃这些缓冲区。如果你在较旧的引擎版本中看到间歇性的音频空白，升级到 UE 5.3 或更高版本可解决这类问题。
{% endhint %}

### 输出日志参考—— `ConvaiAudioLog` 消息

| 日志消息                                                      | 级别 | 含义              | 操作                   |
| --------------------------------------------------------- | -- | --------------- | -------------------- |
| `OpenStream returned false`                               | 警告 | 操作系统报告没有可用的捕获设备 | 连接一个麦克风；检查操作系统音频设置   |
| `音频捕获组件仅支持单声道和立体声麦克风输入 - 音频可能会失真`                         | 警告 | 设备通道数 > 2       | 在操作系统设置中将设备设为单声道/立体声 |
| `SetCaptureDevice: OpenStream failed for device index %d` | 警告 | 请求的设备索引无法打开     | 重新枚举设备；索引可能已更改       |
| `PlayVoiceData: Failed to parse wav header, reason: %s`   | 警告 | 收到的音频数据格式损坏     | 通常是暂时性的；检查网络质量       |

### 下一步

{% content-ref url="/pages/aade7c9244e67877d732705a3f1075d5958e0a22" %}
[口型同步和动画问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/lip-sync-and-animation-issues.md)
{% endcontent-ref %}

{% content-ref url="/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a" %}
[诊断和日志导出](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.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-unreal-engine-plugin/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.