# Equalizer

**命名空间**: `XCEngine::Audio`

**类型**: `class`

**头文件**: `XCEngine/Audio/Equalizer.h`

**描述**: 一个多段参数均衡器效果，实现上使用按频段串行处理的 IIR 型滤波系数。

## 角色概述

`Equalizer` 是当前 `IAudioEffect` 派生效果器里最像“真实音频处理器”的一个。它提供：

- 可调频段数量
- 每段频率
- 每段增益
- 每段 Q 值

从设计思路上，它对应的是常见商用引擎里的基础 EQ 效果，而不是完整母带级处理器。

## 当前实现行为

### 1. 会直接原地修改 buffer

`ProcessAudio()` 当前会：

- 检查启用状态和参数合法性
- 按通道遍历
- 对每个频段顺序执行滤波
- 直接回写到输入 buffer

因此，它是一个真正会改写音频样本的效果器。

### 2. 参数更新会重算滤波系数

以下接口都会触发 `ComputeCoefficients()`：

- `SetBandFrequency()`
- `SetBandGain()`
- `SetBandQ()`

当前实现里还包含基础 clamp：

- 频率 `20Hz ~ 20000Hz`
- 增益 `-24dB ~ 24dB`
- Q 值 `0.1 ~ 10.0`

### 3. 默认带数和初始频点

构造函数默认创建 4 段 EQ，并把中心频率初始化为：

- `100Hz`
- `500Hz`
- `2000Hz`
- `8000Hz`

## `wetMix` 的现实状态

虽然类型覆写了 `SetWetMix()` / `GetWetMix()`，但当前 `ProcessAudio()` 并没有按 dry/wet 混合输出，它是直接把处理结果覆盖回 buffer。

所以 `wetMix` 目前更像被保存下来的参数，而不是已接入的混合控制。

## 通道语义

当前实现通过 `m_bandStates[ch * m_bandCount + band]` 管理状态，但 `SetBandCount()` 里把状态数组固定 resize 为 `count * 2`。这说明当前实现默认按双声道思路写的：

- 对单声道和立体声更合理
- 对多于 2 个通道的音频没有看到可靠保障

## 线程语义

- 当前实现没有内部加锁。
- 参数修改和样本处理不应默认认为可跨线程并发。

## 当前实现限制

- `wetMix` 当前不参与真正的干湿混合。
- 样本率固定按 `48000` 计算系数，没有看到从实际流配置动态同步采样率。
- 通道状态数组当前按双声道规模预设，多通道支持不完整。
- 没有看到该类型的直接单元测试。

## 相关方法

- [Constructor](Constructor.md)
- [Destructor](Destructor.md)
- [ProcessAudio](ProcessAudio.md)
- [SetBandCount](SetBandCount.md)
- [GetBandCount](GetBandCount.md)
- [SetBandFrequency](SetBandFrequency.md)
- [GetBandFrequency](GetBandFrequency.md)
- [SetBandGain](SetBandGain.md)
- [GetBandGain](GetBandGain.md)
- [SetBandQ](SetBandQ.md)
- [GetBandQ](GetBandQ.md)
- [SetEnabled](SetEnabled.md)
- [IsEnabled](IsEnabled.md)
- [SetWetMix](SetWetMix.md)
- [GetWetMix](GetWetMix.md)

## 相关文档

- [当前模块](../Audio.md)
- [IAudioEffect](../IAudioEffect/IAudioEffect.md)
- [AudioMixer](../AudioMixer/AudioMixer.md)
- [API 总索引](../../../main.md)