> 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).

# 音频和麦克风问题

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

### 第一步检查

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

{% stepper %}
{% step %}

#### 打开 Output Log，并按 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` Output Log 显示捕获设备警告，或者在 Play 开始后没有出现音频转发活动。

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

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

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

***

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

```
ConvaiAudioLog: Warning: OpenStream 返回 false
```

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

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

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

**症状：** 音频来自错误的输入——例如，内置摄像头麦克风而不是耳机麦克风。

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

**修复：** 使用 `获取可用捕获设备详情` 在 `Convai 玩家` 组件来枚举可用设备。该节点返回一个结构体数组 `FCaptureDeviceInfoBP` 结构体。每个结构体公开 `DeviceName`, `DeviceIndex`, `LongDeviceId`, `InputChannels`, `PreferredSampleRate`，以及 `bSupportsHardwareAEC`。传入 `DeviceIndex` 正确设备的 `按索引设置捕获设备`，或者使用 `按名称设置捕获设备` ，当你希望按设备名称选择时使用。

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

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

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

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

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

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

***

**原因——未按住按键说话键，或说话触发器未触发：** Player 组件默认不会持续捕获；必须激活一个触发器。

**修复：** 确认调用 `开始说话` 在 `Convai 玩家` 组件的 Blueprint 或输入绑定是否正常触发。向 Blueprint 事件添加一个临时 Print String 以验证执行。

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

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

**症状：** 音频捕获已打开，但语音质量下降、杂乱或无声。Output Log 显示：

```
ConvaiAudioLog: Warning: 音频捕获组件仅支持单声道和立体声麦克风输入 - 音频可能会被损坏
```

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

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

**验证：** 该警告不再出现在 `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="缺少原生库" %}
**原因：** 该插件打包了原生音频库（`libconvai_client.so`, `libconvai_http_helper.so`），它们必须存在于 APK 中。如果 ProGuard 或自定义打包步骤将其移除，则设备上的音频初始化会失败，且游戏输出中不会有明确的日志消息。

**修复：** 使用 `adb logcat` 用于读取设备上的系统日志——在未额外处理的已部署 APK 上，游戏 Output Log 不会被写入。筛选与 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 面部同步` 组件在播放动画（嘴巴移动），这表明响应已到达，但角色没有播放任何音频。Output Log 可能包含：

```
ConvaiAudioStreamerLog: Warning: PlayVoiceData: 无法解析 wav 头，原因：<detail>
```

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

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

1. 检查到……连接上的网络质量和丢包情况 `realtime-api.convai.com`.
2. 确认 API 密钥有效——身份验证失败可能导致响应数据格式错误。
3. 重新进入 Play 模式以建立一个新会话。

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

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

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

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

**修复：** 调用 `按索引设置捕获设备` 在 `Convai 玩家` 带有新的 `DeviceIndex` 在连接新设备后。请先使用以下方式枚举当前设备列表： `获取可用捕获设备详情` 以获取新设备的正确索引。

**验证：** 调用后 `按索引设置捕获设备`，对着新设备说话并确认 `ConvaiAudioLog` 显示来自更新后设备的数据。

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

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

### Output Log 参考—— `ConvaiAudioLog` 消息

| 日志消息                                        | 级别 | 含义              | Action               |
| ------------------------------------------- | -- | --------------- | -------------------- |
| `OpenStream returned false`                 | 警告 | 操作系统报告没有可用的捕获设备 | 连接麦克风；检查操作系统音频设置     |
| `音频捕获组件仅支持单声道和立体声麦克风输入 - 音频可能会被损坏`          | 警告 | 设备通道数 > 2       | 在操作系统设置中将设备设为单声道/立体声 |
| `SetCaptureDevice: 设备索引 %d 的 OpenStream 失败` | 警告 | 无法打开请求的设备索引     | 重新枚举设备；索引可能已更改       |
| `PlayVoiceData: 无法解析 wav 头，原因：%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 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-unreal-engine-plugin/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.