CamillaDSP 滤波器文档

本文档基于 src/camilladsp/config.ts 中的定义，列出了 CamillaDSP GUI 中支持的各种滤波器及其参数。

1. Biquad (双二阶滤波器)

Biquad 滤波器是最常用的 IIR 滤波器类型，广泛用于均衡、分频和修正。

子类型 (Subtype)	描述	用途/作用	参数
Lowpass	低通滤波器	允许低频通过，衰减高频。常用于低音炮分频或去除高频噪声。	`freq` (频率), `q` (Q值)
Highpass	高通滤波器	允许高频通过，衰减低频。常用于保护高音单元或去除低频隆隆声。	`freq` (频率), `q` (Q值)
Lowshelf	低频搁架滤波器	调整低于特定频率的增益。常用于增加或减少低音量感。	`gain` (增益), `freq` (频率), `slope` (斜率) 或 `q` (Q值)
Highshelf	高频搁架滤波器	调整高于特定频率的增益。常用于增加或减少高音量感。	`gain` (增益), `freq` (频率), `slope` (斜率) 或 `q` (Q值)
LowpassFO	一阶低通滤波器	6dB/oct 的低通滤波器，相位变化较平缓。	`freq` (频率)
HighpassFO	一阶高通滤波器	6dB/oct 的高通滤波器，相位变化较平缓。	`freq` (频率)
LowshelfFO	一阶低频搁架滤波器	6dB/oct 的低频搁架。	`gain` (增益), `freq` (频率)
HighshelfFO	一阶高频搁架滤波器	6dB/oct 的高频搁架。	`gain` (增益), `freq` (频率)
Peaking	峰值滤波器 (参数均衡)	在特定频率附近提升或衰减。用于房间模式校正或音色微调。	`gain` (增益), `freq` (频率), `q` (Q值) 或 `bandwidth` (带宽)
Notch	陷波滤波器	极窄的带阻滤波器。用于去除特定频率的干扰（如电源嗡嗡声）或强烈的共振。	`freq` (频率), `q` (Q值) 或 `bandwidth` (带宽)
GeneralNotch	通用陷波滤波器	允许分别设置零点和极点的陷波滤波器，用于高级校正。	`freq_z` (零点频率), `freq_p` (极点频率), `q_p` (极点Q值), `normalize_at_dc` (DC归一化)
Bandpass	带通滤波器	只允许特定频带通过。	`freq` (频率), `q` (Q值) 或 `bandwidth` (带宽)
Allpass	全通滤波器	只改变相位，不改变幅度。用于相位对齐或群延迟修正。	`freq` (频率), `q` (Q值) 或 `bandwidth` (带宽)
AllpassFO	一阶全通滤波器	一阶全通，提供 90 度相移。	`freq` (频率)
LinkwitzTransform	Linkwitz 变换	用于改变封闭式音箱的低频滚降特性，扩展低频响应。	`q_act` (实际Q值), `q_target` (目标Q值), `freq_act` (实际频率), `freq_target` (目标频率)
Free	自由定义的 Biquad 系数	直接输入系数，用于实现标准类型无法覆盖的特殊滤波器。	`a1`, `a2`, `b0`, `b1`, `b2`

2. BiquadCombo (组合双二阶滤波器)

由多个 Biquad 级联组成的复杂滤波器，主要用于分频和均衡。

子类型 (Subtype)	描述	用途/作用	参数
ButterworthLowpass	巴特沃斯低通	通带最平坦的低通滤波器。常用于分频网络。	`order` (阶数), `freq` (频率)
ButterworthHighpass	巴特沃斯高通	通带最平坦的高通滤波器。常用于分频网络。	`order` (阶数), `freq` (频率)
LinkwitzRileyLowpass	Linkwitz-Riley 低通	专为分频设计的低通滤波器，两路合成后幅频响应平坦。	`order` (阶数), `freq` (频率)
LinkwitzRileyHighpass	Linkwitz-Riley 高通	专为分频设计的高通滤波器，两路合成后幅频响应平坦。	`order` (阶数), `freq` (频率)
Tilt	倾斜滤波器	以中心频率为轴，提升一端同时衰减另一端。用于整体音色平衡调整（如“暖”或“亮”）。	`gain` (增益)
GraphicEqualizer	图形均衡器	提供多个固定频段的增益调整，直观地调节频响曲线。	`freq_min` (最小频率), `freq_max` (最大频率), `gains` (增益数组)

3. Conv (卷积)

用于 FIR (有限脉冲响应) 滤波器，通过卷积运算实现复杂的滤波特性。

子类型 (Subtype)	描述	用途/作用	参数
Raw	原始系数文件	加载原始二进制或文本格式的脉冲响应 (IR) 文件。用于房间校正 (DRC) 或扬声器校正。	`filename` (文件名), `format` (格式: TEXT/FLOAT32LE/FLOAT64LE), `skip_bytes_lines` (跳过字节/行), `read_bytes_lines` (读取字节/行)
Wav	WAV 文件	加载 WAV 格式的脉冲响应文件。	`filename` (文件名), `channel` (通道号)
Values	直接数值列表	直接在配置中输入 FIR 系数。适用于较短的滤波器。	`values` (系数数组)
Dummy	虚拟 (用于测试)	生成指定长度的零系数，仅用于测试性能或延迟。	`length` (长度)

4. Delay (延迟)

子类型 (Subtype)	用途/作用	参数
Default	对信号进行时间延迟。用于对齐不同扬声器单元或声道的时间差，确保声音同时到达听音位置。	`delay` (延迟量), `unit` (单位: ms/samples/mm/cm/m), `subsample` (是否启用子采样延迟)

5. Gain (增益)

子类型 (Subtype)	用途/作用	参数
Default	调整信号电平。用于平衡不同声道的音量、控制增益结构或反相信号。	`gain` (增益值), `scale` (标度: dB/linear), `inverted` (反相: true/false), `mute` (静音: true/false)

6. Volume (音量控制)

子类型 (Subtype)	用途/作用	参数
Default	带有平滑渐变功能的音量控制，通常作为系统的主音量调节。	`ramp_time` (渐变时间), `limit` (限制), `fader` (推子: Aux1/Aux2/Aux3/Aux4)

7. Loudness (响度控制)

子类型 (Subtype)	用途/作用	参数
Default	根据等响度曲线（Fletcher-Munson 曲线）动态调整高低频增益。使得在小音量下也能听到均衡的高低音。	`reference_level` (参考电平), `high_boost` (高频提升), `low_boost` (低频提升), `fader` (推子: Main/Aux…), `attenuate_mid` (衰减中频)

8. DiffEq (差分方程)

子类型 (Subtype)	用途/作用	参数
Default	通用 IIR 滤波器，直接通过差分方程系数定义。用于实现高级自定义滤波器。	`a` (反馈系数数组), `b` (前馈系数数组)

9. Dither (抖动)

用于位深转换时的抖动处理。

子类型 (Subtype)	描述	用途/作用	参数
None	无抖动	直接截断，可能产生量化失真。	`bits` (位深)
Flat	平坦抖动	加入白噪声抖动。最基本的抖动方式。	`bits` (位深), `amplitude` (幅度)
Highpass	高通抖动	能量集中在高频的抖动，人耳较难察觉。	`bits` (位深)
Fweighted…	F-加权抖动	根据人耳听觉特性加权的抖动。	`bits` (位深)
Gesemann…	Gesemann 噪声整形	心理声学优化的噪声整形算法。	`bits` (位深)
Lipshitz…	Lipshitz 噪声整形	另一种噪声整形算法。	`bits` (位深)
Shibata…	Shibata 噪声整形	另一种噪声整形算法。	`bits` (位深)

注：Dither 有多种针对不同采样率 (44.1, 48, 88.2, 96, 192 kHz) 的变体，用于在降低位深（如 32bit -> 16bit）时消除量化失真，保留微弱信号细节。

10. Limiter (限制器)

子类型 (Subtype)	用途/作用	参数
Default	防止信号幅度超过设定阈值。用于保护扬声器或防止数字削波。	`soft_clip` (软剪切: true/false), `clip_limit` (剪切限制)

11. 参数详解 (Parameter Details)

以下是上述滤波器中出现的常见参数的详细解释及其在滤波器中的作用：

基础参数

freq (频率): 滤波器的中心频率（对于 Peaking, Notch 等）或截止频率（对于 Lowpass, Highpass 等）。单位为赫兹 (Hz)。决定了滤波器在频谱上的作用位置。
gain (增益): 信号提升或衰减的量。单位通常为分贝 (dB)。正值表示音量增加，负值表示音量减少。
q (Q值 / 品质因数): 决定了滤波器影响频带的宽度或共振峰的尖锐程度。
在 Peaking/Notch 滤波器中：Q 值越高，影响的频带越窄，峰/谷越尖锐；Q 值越低，影响范围越宽平。
在 Lowpass/Highpass 滤波器中：Q 值决定了截止频率附近的“膝点”形状。Q=0.707 (Butterworth) 为最平坦；Q>0.707 会在截止频率前产生隆起；Q<0.5 则是过阻尼，过渡平缓。
slope (斜率): 滤波器在截止频率后的衰减速度。单位是 dB/oct (分贝/倍频程)。数值越大（如 24dB/oct 比 12dB/oct），对截止频率以外信号的衰减越快，分频越彻底。
bandwidth (带宽): 与 Q 值类似，用于定义滤波器影响的频率范围宽度，通常以倍频程 (octaves) 为单位。在某些滤波器中可替代 Q 值使用。
order (阶数): 滤波器的数学阶数，直接影响斜率。每增加 1 阶，斜率增加 6dB/oct。例如：2 阶 = 12dB/oct，4 阶 = 24dB/oct，8 阶 = 48dB/oct。

卷积与文件参数

filename (文件名): 脉冲响应 (IR) 文件的路径。CamillaDSP 会加载此文件进行卷积运算。
format (格式): IR 文件的数据存储格式。
TEXT: 纯文本格式，每行一个系数。
FLOAT32LE/FLOAT64LE: 32位或64位浮点数，小端序 (Little Endian)。
skip_bytes_lines: 读取文件时跳过的头部字节数（二进制格式）或行数（文本格式）。用于跳过文件头。
read_bytes_lines: 读取的字节数或行数。如果未指定，则读取到文件结束。
channel (通道): 当使用多通道 WAV 文件作为 IR 源时，指定使用其中的哪一个通道（从 0 开始计数）。

延迟与时间参数

delay (延迟量): 信号推迟的时间量。
unit (单位): 延迟量的单位。
ms: 毫秒。
samples: 采样点数。
mm/cm/m: 距离单位。系统会根据声速（约 343m/s）自动将其转换为时间延迟。
subsample (子采样): 布尔值 (true/false)。如果启用，延迟器会使用插值算法实现小于一个采样点的延迟精度，提供更精确的时间对齐。

音量与响度参数

ramp_time (渐变时间): 当音量设置改变时，从当前值过渡到新值所需的时间（毫秒）。用于实现平滑的淡入淡出，避免突变产生的爆音。
fader (推子): 指定该滤波器响应哪个控制信号。例如，可以将 Volume 滤波器绑定到 Aux1，这样改变 Aux1 的音量时，该滤波器会相应调整。
reference_level (参考电平): 响度控制的基准音量。当实际音量等于此电平时，响度补偿为 0（无效果）。当音量低于此电平时，系统会根据人耳听觉特性逐渐提升高频和低频。
high_boost / low_boost: 在最大衰减量（通常是 -20dB 或更低）时，高频和低频的最大提升量 (dB)。
attenuate_mid (衰减中频): 布尔值。
false: 传统的响度补偿，提升高低频。这可能会导致数字削波。
true: 保持高低频不变，通过衰减中频来实现相对的响度效果。这可以避免削波，但整体音量会变小。