Improve BandStopFilter docs

demo/generate_examples_for_doc.py

@@ -332,6 +332,31 @@ def generate_example(self):
         return sound, transformed_sound, sample_rate
 
 
+@register
+class BandStopFilterExample(TransformUsageExample):
+    transform_class = BandStopFilter
+
+    def generate_example(self):
+        random.seed(42)
+        np.random.seed(42)
+        transform = BandStopFilter(
+            min_center_freq=2500.0,
+            max_center_freq=2500.0,
+            min_bandwidth_fraction=0.8,
+            max_bandwidth_fraction=0.8,
+            p=1.0,
+        )
+
+        sound, sample_rate = load_sound_file(
+            os.path.join(DEMO_DIR, "p286_011.wav"), sample_rate=None
+        )
+        sound = sound[..., int(0.5 * sample_rate) : int(2.9 * sample_rate)]
+
+        transformed_sound = transform(sound, sample_rate)
+
+        return sound, transformed_sound, sample_rate
+
+
 @register
 class LimiterExample(TransformUsageExample):
     transform_class = Limiter

docs/waveform_transforms/band_stop_filter.md

@@ -3,11 +3,29 @@
 _Added in v0.21.0_
 
 Apply band-stop filtering to the input audio. Also known as notch filter or
-band reject filter. It relates to the frequency mask idea in the SpecAugment paper.
-Center frequency gets picked in mel space, so it is
-more aligned with human hearing, which is not linear. Filter steepness
-(6/12/18... dB / octave) is parametrized. Can also be set for zero-phase filtering
-(will result in a 6 dB drop at cutoffs).
+band reject filter. It relates to the frequency mask idea in the [SpecAugment paper :octicons-link-external-16:](https://arxiv.org/abs/1904.08779).
+Center frequency gets picked in mel space, so it is somewhat aligned with human hearing,
+which is not linear. Filter steepness (6/12/18... dB / octave) is parametrized. Can also
+be set for zero-phase filtering (will result in a 6 dB drop at cutoffs).
+
+Applying band-stop filtering as data augmentation during model training can aid in
+preventing overfitting to specific frequency relationships, helping to make the model
+robust to diverse audio environments and scenarios, where frequency losses can occur.
+
+## Input-output example
+
+Here we input a speech recording and apply `BandStopFilter` with a center
+frequency of 2500 Hz and a bandwidth fraction of 0.8, which means that the bandwidth in
+this example is 2000 Hz, so the low frequency cutoff is 1500 Hz and the high frequency
+cutoff is 3500 Hz. One can see in the spectrogram of the transformed sound that the band
+stop filter has attenuated this frequency range. If you listen to the audio example, you
+can hear that the timbre is different in the transformed sound than in the original.
+
+![Input-output waveforms and spectrograms](BandStopFilter.webp)
+
+| Input sound                                                                           | Transformed sound                                                                           |
+|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| <audio controls><source src="../BandStopFilter_input.flac" type="audio/flac"></audio> | <audio controls><source src="../BandStopFilter_transformed.flac" type="audio/flac"></audio> | 
 
 # BandStopFilter API