- 文档
- 教程
- 游戏开发
【免费下载链接】godot-docs
Godot Engine official documentation
AudioEffectNotchFilter是 Godot 引擎音频系统中用于精确压制特定频率的陷波（Notch）滤波器。它作用于音频总线（Audio Bus），可将cutoff_hz处的频率大幅衰减，而让该频率之外的信号几乎原样通过，常用于给其他音效让出频段空间，或彻底消除 50/60 Hz 电源哼声、设备共振杂音等"令人讨厌的"特定频率。读完本文，你将掌握该效果的类继承关系、全部可调参数及取值范围、编辑器与运行时两种添加方式，以及它与带通/带阻滤波器的区别。
什么是 AudioEffectNotchFilter：陷波滤波器的核心语义
根据 class_audioeffectnotchfilter.rst 的定义，AudioEffectNotchFilter向音频总线添加一个陷波滤波器：
- 衰减目标：只衰减位于
cutoff_hz（截止频率）处的频段； - 通过策略：截止频率之外的所有频率原样通过，不受影响；
- 同类对比：它是 AudioEffectBandLimitFilter（带阻滤波器）更窄、更强的版本，同时也是 AudioEffectBandPassFilter（带通滤波器）的对立面。
官方教程对三者的关系有更直白的表述：带通滤波让截止点频率通过、衰减外部频率；带阻与陷波则恰好相反，衰减截止点频率、让外部频率通过，区别只在"带宽"与"强度"（见 audio_effects.rst 的
doc_band_pass_filter、doc_band_limit_filter、doc_notch_filter三节）。
典型应用场景
文档明确给出两个典型用途：
- 让出频段空间：在截止点频率处大幅衰减后，其他声音可以在该频段"腾出位置"，混音更干净；
- 彻底移除目标频率：由于陷波滤波器的衰减量极大，它甚至可以完全消除某一段不想要的特定频率——例如电源交流声、电机啸叫、某个共振峰等。
类继承链
Object < RefCounted < Resource < AudioEffect < AudioEffectFilter < AudioEffectNotchFilter- AudioEffect 是所有音频效果的资源基类；
- AudioEffectFilter 是滤波器基类，提供了
cutoff_hz、db、resonance等核心参数； AudioEffectNotchFilter是AudioEffectFilter的直接子类之一。从 class_audioeffectfilter.rst 的 "Inherited By" 列表可以看到，与它同级的还有带阻（BandLimit）、带通（BandPass）、低通（LowPass）、高通（HighPass）以及高/低架（Shelf）滤波器。
值得注意的是：AudioEffectNotchFilter自身没有声明任何额外属性或方法，它的全部可调参数都继承自AudioEffectFilter。这意味着"陷波"的核心行为完全由基类参数的组合方式决定。
核心参数详解（继承自 AudioEffectFilter）
所有参数均可通过属性或对应的set_*/get_*方法访问，具体签名见 class_audioeffectfilter.rst。
cutoff_hz —— 陷波中心频率
| 项目 | 内容 |
|---|---|
| 类型 | float |
| 默认值 | 2000.0 |
| 取值范围 | 1 ~ 20500Hz |
| 访问方法 | set_cutoff(value)/get_cutoff() |
这是陷波滤波器要衰减的中心频率。对陷波而言，"cutoff" 更像是"陷波点"：频率恰好落在此处的信号被最大程度衰减。取一个具体的例子，若你的录音混入了 50 Hz 电源哼声，可把cutoff_hz设为50.0。
db —— 衰减陡度（滤波器阶数）
| 项目 | 内容 |
|---|---|
| 类型 | AudioEffectFilter.FilterDB（枚举） |
| 默认值 | 0（FILTER_6DB） |
该参数决定截止曲线每个倍频程（octave）的 dB 衰减量，即滤波器的"阶数"。枚举定义如下：
| 常量 | 值 | 衰减量 |
|---|---|---|
FILTER_6DB | 0 | 每倍频程 6 dB |
FILTER_12DB | 1 | 每倍频程 12 dB |
FILTER_18DB | 2 | 每倍频程 18 dB |
FILTER_24DB | 3 | 每倍频程 24 dB |
文档对"倍频程"的说明：一个倍频程即
cutoff_hz上方的二倍频率，或下方的二分之一频率。阶数越高，衰减越陡峭、越激进——陷波效果越"窄而深"。
gain —— 受影响频段的增益
| 项目 | 内容 |
|---|---|
| 类型 | float |
| 默认值 | 1.0 |
| 取值范围 | 0 ~ 4 |
需要特别注意：文档明确指出，gain仅对低架（LowShelf）与高架（HighShelf）滤波器可用。对陷波滤波器来说，该参数不参与陷波行为的控制，了解其存在有助于避免混淆。
resonance —— 陷波带宽/锐度
| 项目 | 内容 |
|---|---|
| 类型 | float |
| 默认值 | 0.5 |
| 取值范围 | 0 ~ 1 |
resonance控制截止点频率处（或紧邻其旁）的增益表现，且因滤波器类型而异。对带通与陷波类滤波器，它的作用是：
在
cutoff_hz频率阈值处加宽或收窄滤波器。
也就是说，对于AudioEffectNotchFilter，resonance直接决定陷波"凹槽"的带宽——值越高，陷波越窄越尖锐；值越低，受影响的频带越宽、越柔和。
参数组合与陷波行为的关系
综合上述参数，一个陷波滤波器的实际效果由三者共同决定：
cutoff_hz决定"挖掉哪一段频率"（陷波位置）；db决定"挖得多深、多陡"（衰减强度）；resonance决定"挖的面有多宽"（带宽/锐度）。
例如，要彻底清除一段窄带噪声，可以组合使用较高的db（如FILTER_24DB）与较高的resonance，得到极窄极深的"针尖"式陷波；而若只想为其他乐器让出较宽的频段空间，则应降低db与resonance，让衰减平缓一些。
实战：如何把陷波滤波器加到音频总线上
方式一：编辑器（推荐，适合静态配置）
- 打开 Godot 编辑器底部面板的 Audio 面板（总线布局视图，详见 audio_buses.rst）；
- 在最左侧的Master总线或你新建的自定义总线上，点击Add Effect；
- 在效果列表中选择NotchFilter；
- 在 Inspector 中调整
Cutoff Hz（截止频率）、DB（衰减陡度）与Resonance（带宽/锐度）。
效果会按添加顺序依次应用到流经该总线的所有声音上。总线布局会自动保存到res://default_bus_layout.tres（见 audio_buses.rst 的 "Default bus layout" 一节）。
注意：在 Web 平台，若 AudioStreamPlayer 的播放模式为默认的Sample，总线效果不被支持，需切换为Stream模式（详见 audio_buses.rst 的 "Adding effects" 警告）。
方式二：运行时用代码动态添加
AudioEffect基类文档明确指出，运行时可以通过AudioServer的 API 操作任意总线上的效果（见 class_audioeffect.rst 与 class_audioserver.rst 的add_bus_effect、remove_bus_effect、get_bus_effect方法）。下面是一个完整的 GDScript 示例，向 Master 总线（索引 0）动态添加一个陷波滤波器并配置参数：
# 创建一个陷波滤波器资源 var notch := AudioEffectNotchFilter.new() # 设置陷波中心频率（Hz），例如清除 50 Hz 电源哼声 notch.set_cutoff(50.0) # 设置衰减陡度：每倍频程 24 dB，陷波更深更陡 notch.db = AudioEffectFilter.FILTER_24DB # 设置共振/带宽：较高的值让陷波更窄更尖锐 notch.resonance = 0.8 # 把效果添加到 Master 总线（bus_idx = 0），默认追加到效果链末尾 AudioServer.add_bus_effect(0, notch) # 之后还可以按需移除 # AudioServer.remove_bus_effect(0, effect_idx)AudioServer相关方法签名（摘自 class_audioserver.rst）：
add_bus_effect(bus_idx: int, effect: AudioEffect, at_position: int = -1)remove_bus_effect(bus_idx: int, effect_idx: int)get_bus_effect(bus_idx: int, effect_idx: int) -> AudioEffectget_bus_effect_count(bus_idx: int) -> int
at_position参数默认-1表示追加到效果链末尾；传入非负索引可把效果插入到指定位置，从而控制处理顺序。
底层机制：从 AudioEffect 到 AudioEffectInstance
了解一点底层原理有助于正确使用：AudioEffect基类通过虚方法_instantiate()为每个效果创建对应的 AudioEffectInstance（见 class_audioeffect.rst 的_instantiate说明）。真正负责对声音进行采样级处理的是这个 Instance，而资源本身（如AudioEffectNotchFilter）只负责保存参数配置。这正是"在编辑器里改参数、声音实时变化"的机制基础——Instance 会监听资源属性的变化并应用到音频处理链上。
与其他滤波器效果的选型对比
| 效果 | 行为 | 适用场景 |
|---|---|---|
| NotchFilter（陷波） | 衰减 cutoff 处频率，外部通过，窄而强 | 让出频段空间、彻底移除特定杂音 |
| BandLimitFilter（带阻） | 同上，但更宽更弱 | 温和地让出某频段空间 |
| BandPassFilter（带通） | 保留 cutoff 处频率，衰减外部 | 模拟电话/扩音器音色、哇音踏板 |
| LowPassFilter（低通） | 衰减高于 cutoff 的频率 | 模拟闷音、水下/隔墙/远处声音 |
| HighPassFilter（高通） | 衰减低于 cutoff 的频率 | 去掉低频，让声音"更薄" |
三者的官方定义分别位于 class_audioeffectnotchfilter.rst、class_audioeffectbandlimitfilter.rst、class_audioeffectbandpassfilter.rst，相互引用互为"更弱/更强版本"与"对立面"。教程 audio_effects.rst 也强调：先逐个试听每种效果，建立对它们听感差异的直觉，比死记参数更重要。
小结
AudioEffectNotchFilter是 Godot 混音工具箱里"外科手术式"的频率处理利器：用cutoff_hz锁定目标频率，用db控制衰减陡度，用resonance决定凹槽带宽，即可在不影响其他频段的前提下精确腾出空间或铲除杂音。它自身不引入新参数，全部能力来自AudioEffectFilter基类；无论走编辑器的 Audio 面板，还是运行时调用AudioServer.add_bus_effect()，都能快速部署。想深入了解其应用环境，可继续阅读 Audio buses（音频总线） 与 Audio effects（音频效果总览）。
- 文档
- 教程
- 游戏开发
【免费下载链接】godot-docs
Godot Engine official documentation
相关推荐
Radix Vue（reka-ui）Roving Focus 组件完全指南：实现 roving tabindex 焦点管理
Radix Vue（reka ui）Roving Focus 组件完全指南：实现 roving tabindex 焦点管理 导读 Roving Focus 是
文档教程游戏开发Godot 音频总线低频搁架滤波器（AudioEffectLowShelfFilter）完全指南：原理、参数与实战配置
Godot 音频总线低频搁架滤波器（AudioEffectLowShelfFilter）完全指南：原理、参数与实战配置 AudioEffectLowShelfF
文档教程游戏开发Godot 高通滤波器 AudioEffectHighPassFilter 实战指南：原理、参数与音频总线集成
Godot 高通滤波器 AudioEffectHighPassFilter 实战指南：原理、参数与音频总线集成 导读 AudioEffectHighPassFi
文档教程游戏开发
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
