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

# 配置麦克风

在运行时选择一个活动麦克风设备，设置全项目默认值，并为 Android、iOS 和 WebGL 构建配置平台权限。

Unity 的 Convai SDK 会在会话开始时自动打开系统麦克风。可在运行时枚举并选择特定设备，设置项目范围的默认设备，并满足 Android、iOS 和 WebGL 的平台特定要求。

### 麦克风设备选择

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

```csharp
using System.Collections.Generic;
using System.Threading.Tasks;
using Convai.Runtime.Components;
using Convai.Shared.Abstractions;
using Convai.Shared.Types;
using UnityEngine;

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

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

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

在 WebGL 上， `GetAvailableDevices()` 在 Editor 之外会返回空列表。WebGL 上的麦克风访问通过浏览器的 Web Audio API 进行，不支持 Unity 的原生设备枚举。

### 设置项目范围的默认设备

`ConvaiSettings.DefaultMicrophoneDeviceId` 在任何脚本调用之前设置 SDK 使用的麦克风 `StartListeningAsync` 为特定的设备索引。空字符串将解析为系统默认设备。

{% stepper %}
{% step %}

#### 打开运行时默认值部分

打开 **Edit > Project Settings > Convai SDK**，或选择 **Convai > 设置** 在 Unity 编辑器菜单栏中。选择 **运行时默认值** 部分。
{% endstep %}

{% step %}

#### 选择设备

使用 **Microphone** 下拉框可按名称选择已连接的设备，或者保持为 **系统默认** 以遵循操作系统的设备顺序。
{% endstep %}

{% step %}

#### 如有需要，请刷新设备列表

选择 **刷新** 以便在打开窗口后，如果你插入或移除了设备，可重新枚举已连接的麦克风。
{% endstep %}
{% endstepper %}

### 平台特定设置

#### Android

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

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

中声明该权限。如果你的项目没有自定义 manifest，请创建一个，或者启用 **覆盖默认 Manifest** 中的 **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，将导致审核被拒。请在为 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` 返回 `是` 仅适用于 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.