配置角色音频

设置角色音量、启用空间音频，并通过 ConvaiAudio 外观接口控制 NPC 播放，实现脚本化静音和取消静音。

该 ConvaiAudioOutput 该组件控制角色的声音在场景中的播放方式。请将其与 ConvaiAudio 上的门面 ConvaiManager 用于通过脚本在运行时控制静音状态、每个角色的音量以及音频事件。

角色音频输出

添加 ConvaiAudioOutput 与……在同一个 GameObject 上 ConvaiCharacter。一个 AudioSource 必须位于同一个 GameObject 上。

检查器字段：

字段	默认值	说明
音量	1.0	播放音量（0–1）
是否静音	false	将此角色的音频输出静音
_use3DAudio	true	启用 Unity 空间音频
_minDistance	1	音频达到最大音量的距离
_maxDistance	50	音频降为零的距离

禁用 _use3DAudio 适用于非位置场景——例如，自助终端界面，在这种情况下，无论玩家站在哪里，角色听起来始终都“在场”。

音频门面

若要通过脚本控制音频，请使用 ConvaiAudio 通过……访问的门面 ConvaiManager.Audio。这是运行时音频管理的推荐 API。

麦克风控制

// 将本地麦克风静音/取消静音
ConvaiManager.ActiveManager.Audio.SetMicMuted(true);

// 切换并获取新状态
bool isMuted = ConvaiManager.ActiveManager.Audio.ToggleMicMuted();

// 手动开始麦克风采集（如果 ConnectOnStart 为 false）
await ConvaiManager.ActiveManager.Audio.StartListeningAsync();

按角色播放控制

string characterId = character.CharacterId;

// 将特定角色静音
ConvaiManager.ActiveManager.Audio.MuteCharacter(characterId);

// 取消静音
ConvaiManager.ActiveManager.Audio.UnmuteCharacter(characterId);

// 检查静音状态
bool muted = ConvaiManager.ActiveManager.Audio.IsCharacterMuted(characterId);

// 完全禁用某个角色的远程音频
ConvaiManager.ActiveManager.Audio.SetRemoteAudioEnabled(characterId, false);

音频事件

void OnEnable()
{
    ConvaiManager.ActiveManager.Audio.OnMicMuteChanged += HandleMicMuteChanged;
}

void OnDisable()
{
    ConvaiManager.ActiveManager.Audio.OnMicMuteChanged -= HandleMicMuteChanged;
}

void HandleMicMuteChanged(bool isMuted)
{
    muteButton.SetIsOnWithoutNotify(isMuted);
}

使用示例

示例 1：静音切换 UI 按钮

场景： 一个企业入职培训模拟在屏幕角落包含一个麦克风静音按钮。

public class MuteButtonController : MonoBehaviour
{
    [SerializeField] private Toggle _muteToggle;

    void OnEnable()
    {
        _muteToggle.onValueChanged.AddListener(OnMuteToggled);
        ConvaiManager.ActiveManager.Audio.OnMicMuteChanged += OnMicMuteChanged;
    }

    void OnDisable()
    {
        _muteToggle.onValueChanged.RemoveListener(OnMuteToggled);
        ConvaiManager.ActiveManager.Audio.OnMicMuteChanged -= OnMicMuteChanged;
    }

    void OnMuteToggled(bool muted) =>
        ConvaiManager.ActiveManager.Audio.SetMicMuted(muted);

    void OnMicMuteChanged(bool muted) =>
        _muteToggle.SetIsOnWithoutNotify(muted);
}

预期结果： 该切换开关会与实际麦克风状态保持同步。按下它会将麦克风静音或取消静音。外部更改（例如来自按键通话逻辑）也会自动更新该切换开关。

示例 2：多讲师场景中的按角色音量

场景： 一个语言学习模拟有两位 AI 讲师——一位主教师和一位对话伙伴。玩家可以分别独立调整它们的音量。

public class CharacterVolumeController : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;
    [SerializeField] private Slider _volumeSlider;

    void Start()
    {
        var audioOutput = _character.GetComponent<ConvaiAudioOutput>();
        _volumeSlider.value = audioOutput.Volume;
        _volumeSlider.onValueChanged.AddListener(v => audioOutput.Volume = v);
    }
}

预期结果： 每个角色的音量滑块只控制该角色的 AudioSource 音量。两个角色可以以不同音量独立听到。

下一步

配置麦克风设备和平台特定的音频权限。

配置麦克风