配置麦克风

选择当前活动的麦克风设备，并为 Android、iOS 和 WebGL 构建配置平台特定权限。

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

麦克风设备选择

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

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 的原生设备枚举。

平台特定设置

Android

SDK 会在录音开始时自动在运行时请求麦克风权限。你必须在你的 AndroidManifest.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。

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

WebGL

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

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

// 从 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 以显示对话文本。

添加聊天 UI