# Audio System And Effect Chain

## 这篇指南解决什么问题

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

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

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

## 先建立正确心智模型

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

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

其中：

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

这和 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](../../XCEngine/Audio/AudioMixer/AudioMixer.md) 很像未来会成长为完整路由中枢的类型：

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

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

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

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

## 效果器链当前的现实状态

### 已有类型

- [Equalizer](../../XCEngine/Audio/Equalizer/Equalizer.md)
- [FFTFilter](../../XCEngine/Audio/FFTFilter/FFTFilter.md)
- [Reverbation](../../XCEngine/Audio/Reverbation/Reverbation.md)
- [HRTF](../../XCEngine/Audio/HRTF/HRTF.md)

### 当前成熟度差异

- `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](../../XCEngine/Audio/Audio.md)
2. 再读 [AudioSystem](../../XCEngine/Audio/AudioSystem/AudioSystem.md) 和 [IAudioBackend](../../XCEngine/Audio/IAudioBackend/IAudioBackend.md)
3. 然后对照 [AudioSourceComponent](../../XCEngine/Components/AudioSourceComponent/AudioSourceComponent.md) 与 [AudioListenerComponent](../../XCEngine/Components/AudioListenerComponent/AudioListenerComponent.md)
4. 最后再看 [AudioMixer](../../XCEngine/Audio/AudioMixer/AudioMixer.md) 和各个效果器页，理解哪些能力已经落地、哪些还在预留阶段