音频 API

ConvaiAudio 的脚本参考——麦克风静音、按角色音频控制、音频播放解锁和监听状态管理。

ConvaiAudio 是音频外观门面 ConvaiManager，提供对麦克风采集、按角色远程音频输出以及音频播放解锁的脚本化控制。它清晰地分离了关注点：麦克风输入（你发送给 Convai 的内容）、角色音频输出（你从角色那里听到的内容）以及 WebGL 音频播放闸门。

访问： ConvaiManager.ActiveManager.Audio

var audio = ConvaiManager.ActiveManager?.Audio;
if (audio == null) return; // 管理器尚未引导完成

---

麦克风控制

属性

属性	类型	描述
IsMicMuted	bool	当麦克风已静音且未向 Convai 发送音频时为 True
RequiresUserGesture	bool	当音频播放因等待用户交互而被阻止时为 True（仅 WebGL）
IsAudioPlaybackActive	bool	当音频播放当前处于活动且已解锁时为 True
CanEnableAudioPlayback	bool	当 EnableAudioPlayback() 可被调用以解锁音频

方法

方法	返回	描述
SetMicMuted(bool muted)	void	显式设置麦克风静音状态
ToggleMicMuted()	bool	切换麦克风静音状态。返回新的静音状态。
StartListeningAsync(int microphoneIndex = 0, CancellationToken ct = default)	IConvaiOperation<Unit>	在指定的设备索引上开始麦克风采集
StopListeningAsync(CancellationToken ct = default)	IConvaiOperation<Unit>	停止麦克风采集

该 microphoneIndex 参数在 StartListeningAsync 对应于 返回的列表中的一个索引. 使用 ConvaiManager.ActiveManager.TryGetMicrophoneDeviceService(out var svc) 在选择索引之前按名称枚举设备。索引 0 使用系统默认麦克风。

事件

事件	签名	触发时机
OnMicMuteChanged	Action<bool>	麦克风静音状态发生变化。参数：新的静音状态（true = 静音）。

using Convai.Runtime.Facades;
using UnityEngine;

public class MicMuteIndicator : MonoBehaviour
{
    [SerializeField] private GameObject _muteIcon;

    private void OnEnable()
    {
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio == null) return;
        audio.OnMicMuteChanged += OnMuteChanged;
        _muteIcon.SetActive(audio.IsMicMuted);
    }

    private void OnDisable()
    {
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio != null)
            audio.OnMicMuteChanged -= OnMuteChanged;
    }

    private void OnMuteChanged(bool isMuted) => _muteIcon.SetActive(isMuted);
}

---

按角色音频控制

这些方法控制特定角色的音频输出是否在本地播放。使用来自 ConvaiCharacter.CharacterId 或 ConvaiManager.ActiveManager.Characters.

方法	返回	描述
SetCharacterMuted(string characterId, bool muted)	bool	设置特定角色的静音状态。返回 true 如果更改已应用。
MuteCharacter(string characterId)	bool	使特定角色的音频输出静音。返回 true 如果已应用。
UnmuteCharacter(string characterId)	bool	取消特定角色音频输出的静音。返回 true 如果已应用。
IsCharacterMuted(string characterId)	bool	返回 true 如果该角色的音频输出当前处于静音状态。
SetRemoteAudioEnabled(string characterId, bool enabled)	bool	启用或禁用某个角色的远程音频输出。返回 true 如果已应用。
IsRemoteAudioEnabled(string characterId)	bool	返回 true 如果该角色的远程音频输出已启用。

静音 vs. 启用远程音频： 这两者是独立的控制。启用/禁用远程音频控制 SDK 是否 საერთოდ为该角色流式输出音频。静音控制本地接收到的音频是否通过你的音频输出设备播放。禁用远程音频可节省带宽；静音只是本地范围的音量控制。

事件

事件	签名	触发时机
OnRemoteAudioEnabledChanged	Action<string, bool>	某个角色的远程音频启用状态发生变化。参数：characterId，isEnabled。

---

音频播放 — WebGL

在 WebGL 上，浏览器会阻止音频播放，直到用户与页面交互为止。SDK 会在这一要求之下对音频输出进行门控。

成员	类型	描述
RequiresUserGesture	bool	当音频因等待用户交互而被阻止时为 True
CanEnableAudioPlayback	bool	当 EnableAudioPlayback() 可被调用
IsAudioPlaybackActive	bool	当音频播放已解锁并处于活动状态时为 True
EnableAudioPlayback()	void	解锁音频播放。 必须在用户手势处理程序内调用 （按钮点击等）。

在 WebGL 上，在 EnableAudioPlayback() 用户手势处理程序之外调用 Start() 或 OnEnable()）不会产生任何效果——浏览器会阻止解锁。将其绑定到 UI 按钮的 onClick 事件，或在 OnPointerClick.

using Convai.Runtime.Facades;
using UnityEngine;
using UnityEngine.UI;

public class WebGLStartButton : MonoBehaviour
{
    [SerializeField] private Button     _startButton;
    [SerializeField] private GameObject _startPanel;

    private void OnEnable()  => _startButton.onClick.AddListener(OnStartClicked);
    private void OnDisable() => _startButton.onClick.RemoveListener(OnStartClicked);

    private void OnStartClicked()
    {
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio == null) return;

        // 在用户手势中解锁音频
        if (audio.CanEnableAudioPlayback)
            audio.EnableAudioPlayback();

        // 连接并开始监听
        ConvaiManager.ActiveManager.EnableAudioAndStartListening();

        _startPanel.SetActive(false);
    }
}

---

使用示例

示例 1 — 训练模拟 HUD 中的静音按钮

一款军事训练模拟在 HUD 中提供了一个按键式麦克风静音功能，因此受训者可以在向观察员发言前将自己静音，而无需断开连接。

using Convai.Runtime.Facades;
using TMPro;
using UnityEngine;
using UnityEngine.UI;

public class MuteButton : MonoBehaviour
{
    [SerializeField] private Button   _button;
    [SerializeField] private TMP_Text _label;

    private void OnEnable()
    {
        _button.onClick.AddListener(OnClicked);
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio != null)
        {
            audio.OnMicMuteChanged += RefreshLabel;
            RefreshLabel(audio.IsMicMuted);
        }
    }

    private void OnDisable()
    {
        _button.onClick.RemoveListener(OnClicked);
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio != null)
            audio.OnMicMuteChanged -= RefreshLabel;
    }

    private void OnClicked() => ConvaiManager.ActiveManager?.Audio?.ToggleMicMuted();

    private void RefreshLabel(bool isMuted) =>
        _label.text = isMuted ? "取消静音" : "静音";
}

示例 2 — 多 NPC 评估场景中的按角色音频切换

一个企业入职培训模拟有两名 AI 讲师。评估管理脚本会在主讲师的评估环节中使副讲师静音，然后再恢复两者。

using Convai.Runtime.Components;
using Convai.Runtime.Facades;
using System.Collections;
using UnityEngine;

public class AssessmentAudioManager : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _primaryInstructor;
    [SerializeField] private ConvaiCharacter _secondaryInstructor;

    public void BeginPrimaryEvaluation()
    {
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio == null) return;

        // 让副讲师静音，这样只会听到主讲师
        audio.MuteCharacter(_secondaryInstructor.CharacterId);
        audio.UnmuteCharacter(_primaryInstructor.CharacterId);
    }

    public void RestoreBothInstructors()
    {
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio == null) return;

        audio.UnmuteCharacter(_primaryInstructor.CharacterId);
        audio.UnmuteCharacter(_secondaryInstructor.CharacterId);
    }
}

示例 3 — 连接前选择麦克风设备

一个交互式体验允许用户在会话开始前从下拉菜单中选择自己偏好的麦克风，然后在所选设备上开始监听。

using Convai.Runtime.Facades;
using System.Collections.Generic;
using TMPro;
using UnityEngine;

public class MicrophoneSelector : MonoBehaviour
{
    [SerializeField] private TMP_Dropdown _dropdown;

    private List<string> _deviceNames = new();

    private void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null || !manager.TryGetMicrophoneDeviceService(out var svc)) return;

        _deviceNames.Clear();
        _dropdown.ClearOptions();

        foreach (var device in svc.GetAvailableDevices())
        {
            _deviceNames.Add(device.Name);
            _dropdown.options.Add(new TMP_Dropdown.OptionData(device.Name));
        }

        _dropdown.RefreshShownValue();
    }

    public async void OnConfirmDevice()
    {
        int index = _dropdown.value;
        var audio = ConvaiManager.ActiveManager?.Audio;
        if (audio == null) return;

        await audio.StartListeningAsync(index, destroyCancellationToken);
        Debug.Log($"正在监听：{_deviceNames[index]}");
    }
}

---

故障排查

症状	可能原因	修复方法
WebGL 上没有音频输出	EnableAudioPlayback() 未在用户手势中调用	绑定 EnableAudioPlayback() 到按钮的 onClick；不要在 Start() 或 Awake()
ToggleMicMuted() 返回 true 但角色仍能听到玩家	IsMicMuted 控制的是 SDK 的静音——请确认角色会话已连接且音频管线正在运行	检查 IsSessionConnected 在当前激活的角色上；静音只会在会话中生效
MuteCharacter() 返回 false	未识别角色 ID——该角色可能尚未注册	验证 ID 是否匹配 ConvaiCharacter.CharacterId；该角色必须位于 ConvaiManager.Characters
StartListeningAsync 在移动端失败	平台麦克风权限未授予	使用 TryGetPermissionService 在调用之前请求麦克风权限 StartListeningAsync
IsRemoteAudioEnabled 返回 false 在连接后	EnableRemoteAudioOnStart 在角色上的是 false	设置 ConvaiCharacter.EnableRemoteAudioOnStart = true 在 Inspector 中，或调用 character.EnableRemoteAudio() 在会话开始后

---

下一步

有关按角色音频事件和会话控制，请参阅 角色与玩家 API。有关 WebGL 特定的音频要求和限制，请参阅 WebGL 平台指南。有关连接和会话控制，请参阅 ConvaiManager API.