> 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 密钥问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md).

### 初步检查

排查具体症状前，请先完成以下四项检查。

{% stepper %}
{% step %}

#### 打开输出日志并筛选 ConvaiAudioLog

打开 **窗口 > 输出日志**，在搜索框中输入 `ConvaiAudioLog` ，然后查找错误或警告条目。大多数音频捕获故障会在点击播放后立即在此处显示消息。
{% endstep %}

{% step %}

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

打开 **编辑 > 插件**，搜索 `Audio Capture`，并确认已启用。 `Convai Audio Capture` 组件依赖此引擎插件。如果该插件已禁用，则无法打开任何捕获设备。
{% endstep %}

{% step %}

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

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

{% step %}

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

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

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

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

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

**解决方法：** 打开 **编辑 > 插件**，搜索 `Audio Capture`，启用该插件，然后重启编辑器。

**验证：** 进入播放模式并说话。 `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 的蓝图中，选择 `Convai Player` 组件，并确认已设置聊天机器人组件引用。如果使用蓝图节点，请确保 `Start Talking` 节点收到对 `Convai Chatbot` 组件的有效引用。

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

***

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

**修复方法：** 确认调用 `Start Talking` 的蓝图或输入绑定，在 `Convai Player` 组件上能够正确触发。可在蓝图事件中临时添加 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. 打开 **编辑 > 插件**，搜索 `Android Permission`，并确认已启用。
2. 重新构建并部署。该插件通过 `android.permission.RECORD_AUDIO` 添加到 `Convai_AndroidAPL.xml`.
3. 首次启动时，在 Android 提示时授予麦克风权限。如果之前拒绝过该权限，请在 Android 应用设置中手动启用。

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

如果项目需要在启动场景前检查权限，请使用插件的 Android 权限辅助工具或 Unreal 的 Android 权限节点，并在权限被拒绝时向用户显示提示信息。
{% endtab %}

{% tab title="缺少本机库" %}
**原因：** 该插件捆绑了本机音频库（`libconvai_client.so`, `libconvai_http_helper.so`），这些库必须包含在 APK 中。如果 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`                                                                 | 警告 | 操作系统报告当前没有可用的采集设备 | 连接麦克风；检查操作系统音频设置     |
| `Audio capture components only support mono and stereo mic input - Audio might be mangeled` | 警告 | 设备拥有超过 2 个声道      | 在操作系统设置中将设备设为单声道/立体声 |
| `SetCaptureDevice: OpenStream failed for device index %d`                                   | 警告 | 无法打开请求的设备索引       | 重新枚举设备；索引可能已更改       |
| `PlayVoiceData: Failed to parse wav header, reason: %s`                                     | 警告 | 收到的音频数据格式错误       | 通常是暂时性的；请检查网络质量      |

### 后续步骤

{% content-ref url="/pages/aade7c9244e67877d732705a3f1075d5958e0a22" %}
[口型同步和动画问题](https://docs.convai.com/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" %}
[诊断和日志导出](https://docs.convai.com/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.
