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

# 配置麦克风

Unity 版 Convai 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);
}
```

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

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

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

{% hint style="warning" %}
`DefaultMicrophoneDeviceId` (string) 取代了基于整数的 `DefaultMicrophoneIndex` 在 SDK 版本 <code class="expression">space.vars.unity\_sdk\_version</code>中。Convai 不会自动迁移旧的索引值——如果你的项目之前设置了一个非零的 `DefaultMicrophoneIndex` 在升级前，请打开 **运行时默认值** 并重新选择该设备。
{% endhint %}

{% stepper %}
{% step %}

#### 打开 Runtime Defaults 部分

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

{% step %}

#### 选择设备

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

{% step %}

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

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

### 平台特定设置

#### Android

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

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

如果你的项目没有自定义清单，请创建一个或启用 **覆盖默认清单** 在 **玩家设置 > 发布设置**.

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

#### iOS

为你的 `Info.plist`添加麦克风用途说明。 **玩家设置 > 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` 返回 `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, 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.