如何在RealityKit中控制空间化音频的音量？

问题背景 #

现有代码可在RealityView的程序化Entity上正常播放音频，但无法通过volumeSFX（0.0-1.0范围）控制音量，尝试以下方法均未解决：

1. Entity的spatialAudio属性始终为nil，无法设置增益
2. 不明确AudioMixGroup和AudioMixGroupComponent的使用方式
3. 使用prepareAudio获取AudioController并设置gain为0.0-1.0的值时，音频始终以全音量播放

解决方案 #

1. 解决spatialAudio为nil的问题

spatialAudio是SpatialAudioComponent的快捷属性，Entity默认不会自动添加该组件，必须手动添加后才能使用：

// 可在Entity初始化时或播放音频前添加组件
onEntity.components.set(SpatialAudioComponent())

// 之后即可设置增益（gain为线性增益，0=静音，1=原音量，>1为放大）
onEntity.spatialAudio?.gain = Float(volumeSFX)
onEntity.playAudio(resource)

2. 正确使用AudioController控制单音频音量

你参考的HappyBeam示例中gain=15是放大音量的用法，gain的取值范围是0到任意正数（线性增益），0.5确实对应半音量。之前设置无效果可能是代码执行逻辑问题，正确写法如下：

if let onEntity, let resource = sfxResource[effect] {
    // 先停止该Entity上可能正在播放的同资源音频（可选，避免叠加）
    onEntity.stopAudio(resource)
    // 获取音频控制器并设置音量
    let audioController = onEntity.prepareAudio(resource)
    audioController.gain = Float(volumeSFX)
    audioController.play()
}

3. 使用AudioMixGroup批量控制音效音量

如果需要统一控制多个音效的音量，AudioMixGroup是更高效的方案：

// 全局创建一个音效混音组（可在音频管理器初始化时创建）
let sfxMixGroup = AudioMixGroup()

// 给需要播放音效的Entity添加混音组组件（可在Entity初始化时做）
onEntity.components.set(AudioMixGroupComponent(mixGroup: sfxMixGroup))

// 控制整个组的音量，所有关联该组的音频都会同步生效
sfxMixGroup.gain = Float(volumeSFX)

// 播放音频时无需单独设置音量
onEntity.playAudio(resource)

内容的提问来源于stack exchange，提问作者livingtech