> 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 构建配置平台权限。

Convai Unity 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()` 在编辑器外会返回一个空列表。WebGL 上的麦克风访问通过浏览器的 Web Audio API 进行，不支持 Unity 的原生设备枚举。

### 设置全项目默认设备

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

{% stepper %}
{% step %}

#### 打开 Runtime Defaults 部分

打开 **编辑 > 项目设置 > Convai SDK**，或者选择 **Convai > Settings** 在 Unity 编辑器菜单栏中。选择 **Runtime Defaults** 部分。
{% endstep %}

{% step %}

#### 选择设备

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

{% step %}

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

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

### 平台特定设置

#### Android

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

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

如果你的项目没有自定义清单，请创建一个或启用 **Override Default 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` 返回 `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 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-unity-sdk/getting-started/configure-microphone.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.