XCEngine/docs/api/_guides/Audio/Audio-System-And-Effect-Chain.md

Audio System And Effect Chain

这篇指南解决什么问题

只看 Audio 模块的单个 API 页，很容易知道“有哪些类”，但不容易知道：

• 当前真正的播放主链路是什么
• AudioMixer 和各种效果器现在到底有没有接入
• AudioSourceComponent、AudioListenerComponent 和 AudioSystem 分别该怎么理解
• 这个设计和 Unity 风格音频体系的关系是什么

这篇指南专门解释这些问题。

先建立正确心智模型

当前引擎音频系统更适合理解成：

场景组件层 + 全局混音系统层 + 平台输出后端层

其中：

• AudioSourceComponent 负责每个声源的播放状态和样本生成。
• AudioListenerComponent 负责把监听器 transform 推送到系统。
• AudioSystem 负责收集活跃声源、混音并提交给输出后端。
• IAudioBackend 负责真正的设备和平台输出。

这和 Unity 的 AudioSource + AudioListener + AudioMixer 心智模型有明显对应关系，但当前版本还没有 Unity 那种完整的 mixer graph、bus、snapshot 和 effect routing 体系。

当前真实播放链路

按当前代码，主链路可以简化成：

1. AudioSourceComponent::Play() 把自己注册到 AudioSystem
2. Scene 更新期间，AudioListenerComponent 更新监听器 transform
3. AudioSystem::Update() 为当前帧分配一个浮点混音 buffer
4. AudioSystem 遍历活跃 AudioSourceComponent
5. 每个 AudioSourceComponent::ProcessAudio() 直接把自己的样本叠加到同一个 buffer
6. AudioSystem 调用后端 ProcessAudio()
7. Windows 后端把浮点样本转成 int16 并交给系统播放

这条链路已经能支撑基础声音播放，但它仍然是比较直接的“源混到总线，再送后端”模型。

为什么 AudioMixer 现在不能按 Unity AudioMixer 理解

从接口形状上看，AudioMixer 很像未来会成长为完整路由中枢的类型：

• 有效果器槽
• 有输出 mixer
• 有 3D 参数
• 有每声道音量

但按当前实现，它真正处理的只有总音量和静音。效果器数组、输出 mixer、3D 参数和每声道音量现在都只是被记录，没有自动进入主链路。

所以最准确的理解方式是：

• 它是架构方向正确的扩展点
• 但还不是完整 mixer graph

效果器链当前的现实状态

已有类型

• Equalizer
• FFTFilter
• Reverbation
• HRTF

当前成熟度差异

• Equalizer 和 Reverbation 会真实改写音频样本。
• FFTFilter 当前更像 analyzer，不会回写处理结果。
• HRTF 是独立空间化处理器，不是 IAudioEffect 派生效果器。

当前没接上的地方

• AudioMixer 不会自动遍历 effect slots
• AudioSystem 也不会自动经过 AudioMixer
• AudioSourceComponent::outputMixer 当前没有形成实际路由

这就是为什么文档会一再强调“接口存在”和“主链路已生效”不是一回事。

当前 Windows 后端到底是什么

类名叫 WASAPIBackend，但当前实现实际上依赖的是 waveOut* 这套 WinMM API，而不是 Core Audio WASAPI COM 接口。

为什么要特别说明这点？

• 因为名字会让人以为这是现代 Windows 音频栈的标准 WASAPI 后端
• 但当前实现的设备模型、线程模型和缓冲策略其实更接近传统 waveOut 风格

这不一定是问题，但文档必须准确。

为什么要保留这些“还没完全接上”的接口

从引擎设计角度看，这其实是合理的演进路径：

1. 先打通最基础的播放链路
2. 再把 mixer、effects、spatialization 的抽象搭出来
3. 之后逐步把这些节点正式接入主混音图

这样做的好处是 API 方向能尽早稳定，编辑器和脚本层也能先围绕目标架构设计。代价是文档必须明确当前成熟度，否则用户会把“未来形状”误读成“当前能力”。

你现在最该注意的限制

1. AudioSourceComponent 不是完整商用级 AudioSource

它已经能解码、播放和基础混音，但 pause/resume、3D 参数、output mixer 和序列化都还不完整。

2. AudioListenerComponent 主要只做监听器 transform 和 master volume / mute

其他高级参数现在大多是存值或预留位。

3. AudioMixer 还没有成为主链路中枢

不要把它当成已经具备完整 bus routing 的 Unity AudioMixer 替代品。

4. AudioSystem 和内建后端之间的 buffer size 语义还需要收敛

当前调用方和实现方对 bufferSize 的理解并不完全一致。

5. 这个模块当前缺少足够的直接单元测试

很多行为需要以源码而不是测试保证为准。

推荐阅读顺序

1. 先读 Audio
2. 再读 AudioSystem 和 IAudioBackend
3. 然后对照 AudioSourceComponent 与 AudioListenerComponent
4. 最后再看 AudioMixer 和各个效果器页，理解哪些能力已经落地、哪些还在预留阶段