> 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/getting-started/configure-microphone.md).

# 配置麦克风

Convai 的 Unity SDK 会在会话开始时自动打开系统麦克风。本页介绍如何在运行时枚举并选择特定设备，以及如何满足 Android、iOS 和 WebGL 的平台特定要求。

### 麦克风设备选择

要列出可用的麦克风设备并让玩家选择一个：

```csharp
using Convai.Runtime.Settings;

// 从 SDK 获取麦克风设备服务
if (ConvaiManager.ActiveManager.TryGetMicrophoneDeviceService(out IMicrophoneDeviceService micService))
{
    // 列出所有可用设备
    IReadOnlyList<ConvaiMicrophoneDevice> devices = micService.GetAvailableDevices();

    foreach (var device in devices)
    {
        Debug.Log($"{device.Name} (ID: {device.Id}, Index: {device.Index})");
    }

    // 使用特定的设备索引开始监听
    await ConvaiManager.ActiveManager.Audio.StartListeningAsync(microphoneIndex: device.Index);
}
```

{% hint style="warning" %}
在 WebGL 上， `GetAvailableDevices()` 在编辑器之外会返回空列表。WebGL 上的麦克风访问通过浏览器的 Web Audio API 进行，不支持 Unity 的原生设备枚举。
{% endhint %}

### 平台特定设置

#### Android

SDK 会在录音开始时自动在运行时请求麦克风权限。你必须在你的 `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

如果你的项目没有自定义清单，请创建一个，或启用 **覆盖默认清单** 在 **Player Settings > Publishing Settings**.

当 SDK 请求该权限时，Android 会显示其标准权限对话框。如果玩家授予权限，录音会自动开始。如果被拒绝，SDK 会记录警告，麦克风将保持未激活状态。

#### iOS

向你的应用添加麦克风使用说明，放在你的 `Info.plist`。在 Unity 中，可通过以下路径设置： **Player Settings > iOS > Other Settings > Microphone Usage Description**:

```
"此应用使用麦克风来支持与 AI 角色的语音对话。"
```

SDK 会使用 Unity 的 `Application.RequestUserAuthorization`自动请求授权。应用无需直接调用任何权限 API。

{% hint style="danger" %}
如果在提交到 App Store 时没有麦克风使用说明，将导致 App Store 审核拒绝。请在为 iOS 分发构建之前设置此值。
{% endhint %}

#### WebGL

在用户与页面交互之前，浏览器会阻止音频播放和麦克风访问。SDK 提供两种方法，取决于你的使用场景：

* **`Audio.EnableAudioPlayback()`** — 仅解锁浏览器音频输出。 当你希望角色语音播放，但暂时还不启动麦克风时使用（例如，在玩家开口前的教程阶段）。
* **`ConvaiManager.EnableAudioAndStartListening()`** — 解锁浏览器音频输出 **和** 并打开麦克风。当玩家准备开始完整对话时使用。

```csharp
// 从 UI 按钮的 onClick 事件调用
public void OnStartButtonClicked()
{
    // 选项 A：仅解锁音频（暂不启用麦克风）
    if (ConvaiManager.ActiveManager.Audio.RequiresUserGesture)
    {
        ConvaiManager.ActiveManager.Audio.EnableAudioPlayback();
    }

    // 选项 B：一步同时解锁音频并打开麦克风
    // ConvaiManager.ActiveManager.EnableAudioAndStartListening();
}
```

如果你在 WebGL 上跳过这一步，即使 Convai 发送了音频数据，角色的声音也不会播放。 `RequiresUserGesture` 返回 `true` 仅在 WebGL 上。

### 下一步

音频配置完成后，添加一个转录 UI 以显示对话文本。

{% content-ref url="/pages/674d9ab1d00b5f445771b7fa3360d5d499e8dee2" %}
[添加聊天 UI](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-chat-ui.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-unity-sdk/getting-started/configure-microphone.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.