> 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 %}

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

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

{% step %}

#### 选择设备

使用 **麦克风** 下拉菜单按名称选择已连接的设备，或保留 **系统默认** 以遵循操作系统的设备顺序。
{% 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 中，通过以下位置设置此项： **播放器设置 > iOS > 其他设置 > 麦克风使用说明**:

```
“此应用使用麦克风，以支持与 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` 仅在 WebGL 上返回 `true` 。

### 后续步骤

配置好音频后，添加转录文本 UI，以显示对话内容。

{% content-ref url="/pages/674d9ab1d00b5f445771b7fa3360d5d499e8dee2" %}
[添加聊天 UI](https://docs.convai.com/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.
