Add documentation page for Aliasing

audiomentations/augmentations/aliasing.py

@@ -22,12 +22,15 @@ def __init__(
         self, min_sample_rate: int = 8000, max_sample_rate: int = 30000, p: float = 0.5
     ):
         """
-        :param min_sample_rate: The minimum sample rate used during an aliasing
-        :param max_sample_rate: The maximum sample rate used during an aliasing
+        :param min_sample_rate: Minimum target sample rate to downsample to
+        :param max_sample_rate: Maximum target sample rate to downsample to
         :param p: The probability of applying this transform
         """
         super().__init__(p)
 
+        if min_sample_rate < 2:
+            raise ValueError("min_sample_rate must be greater than or equal to 2")
+
         if min_sample_rate > max_sample_rate:
             raise ValueError("min_sample_rate must not be larger than max_sample_rate")
 

demo/generate_examples_for_doc.py

@@ -49,6 +49,7 @@
     Limiter,
     AddGaussianSNR,
     BitCrush,
+    Aliasing,
 )
 from audiomentations.core.audio_loading_utils import load_sound_file
 from audiomentations.core.utils import get_max_abs_amplitude
@@ -287,6 +288,29 @@ def generate_example(self):
         return sound, transformed_sound, sample_rate
 
 
+@register
+class AliasingExample(TransformUsageExample):
+    transform_class = Aliasing
+
+    def generate_example(self):
+        random.seed(42)
+        np.random.seed(42)
+        transform = Aliasing(
+            min_sample_rate=12000,
+            max_sample_rate=12000,
+            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 ApplyImpulseResponseExample(TransformUsageExample):
     transform_class = ApplyImpulseResponse

docs/waveform_transforms/aliasing.md

@@ -0,0 +1,48 @@
+# `Aliasing`
+
+_To be added in v0.35.0_
+
+Downsample the audio to a lower sample rate by linear interpolation, without low-pass
+filtering it first, resulting in aliasing artifacts. You get aliasing artifacts when
+there is high-frequency audio in the input audio that falls above the nyquist frequency
+of the chosen target sample rate. Audio with frequencies above the nyquist frequency
+cannot be reproduced accurately and get "reflected"/mirrored to other frequencies.
+
+After the downsampling, the signal gets upsampled to the original signal again, so the
+length of the output becomes the same as the length of the input.
+
+For more information, see
+
+* [Sample rate reduction :octicons-link-external-16:](https://en.wikipedia.org/wiki/Bitcrusher#Sample_rate_reduction){target=_blank} on Wikipedia
+* [Intro to downsampling :octicons-link-external-16:](http://gdsp.hf.ntnu.no/lessons/1/3/){target=_blank} by NTNU, Department of Music, Music Technology. Note: that article describes a slightly different downsampling technique, called sample-and-hold, while audiomentations implements linear interpolation. However, both methods lead to aliasing artifacts.
+
+## Input-output example
+
+Here we target a sample rate of 12000 Hz. Note the vertical mirroring in the spectrogram in the transformed sound.
+
+![Input-output waveforms and spectrograms](Aliasing.webp)
+
+| Input sound                                                                     | Transformed sound                                                                     |
+|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
+| <audio controls><source src="../Aliasing_input.flac" type="audio/flac"></audio> | <audio controls><source src="../Aliasing_transformed.flac" type="audio/flac"></audio> | 
+
+## Usage example
+
+```python
+from audiomentations import Aliasing
+
+transform = Aliasing(min_sample_rate=8000, max_sample_rate=30000, p=1.0)
+
+augmented_sound = transform(my_waveform_ndarray, sample_rate=44100)
+```
+
+# Aliasing API
+
+[`min_sample_rate`](#min_sample_rate){ #min_sample_rate }: `int` • unit: Hz • range: [2, ∞)
+:   :octicons-milestone-24: Minimum target sample rate to downsample to
+
+[`max_sample_rate`](#max_sample_rate){ #max_sample_rate }: `int` • unit: Hz • range: [2, ∞)
+:   :octicons-milestone-24: Maximum target sample rate to downsample to
+
+[`p`](#p){ #p }: `float` • range: [0.0, 1.0]
+:   :octicons-milestone-24: Default: `0.5`. The probability of applying this transform.

docs/waveform_transforms/resample.md

@@ -9,10 +9,10 @@ sampling rate and vice versa to do upsampling only.
 
 # Resample API
 
-[`min_sample_rate`](#min_sample_rate){ #min_sample_rate }: `int`
+[`min_sample_rate`](#min_sample_rate){ #min_sample_rate }: `int` • unit: Hz
 :   :octicons-milestone-24: Default: `8000`. Minimum sample rate
 
-[`max_sample_rate`](#max_sample_rate){ #max_sample_rate }: `int`
+[`max_sample_rate`](#max_sample_rate){ #max_sample_rate }: `int` • unit: Hz
 :   :octicons-milestone-24: Default: `44100`. Maximum sample rate
 
 [`p`](#p){ #p }: `float` • range: [0.0, 1.0]

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
       - AddShortNoises: waveform_transforms/add_short_noises.md
       - AdjustDuration: waveform_transforms/adjust_duration.md
       - AirAbsorption: waveform_transforms/air_absorption.md
+      - Aliasing: waveform_transforms/aliasing.md
       - ApplyImpulseResponse: waveform_transforms/apply_impulse_response.md
       - BitCrush: waveform_transforms/bit_crush.md
       - BandPassFilter: waveform_transforms/band_pass_filter.md

tests/test_aliasing.py

@@ -28,3 +28,8 @@ def test_multichannel(self):
         assert samples.shape == distorted_samples.shape
         assert not np.array_equal(samples, distorted_samples)
 
+    def test_param_range(self):
+        with pytest.raises(ValueError):
+            Aliasing(min_sample_rate=0, max_sample_rate=6000, p=1.0)
+        with pytest.raises(ValueError):
+            Aliasing(min_sample_rate=8000, max_sample_rate=6000, p=1.0)