soundmentations.PerSampleRandomGain¶

class soundmentations.PerSampleRandomGain(min_gain: float, max_gain: float, clip: bool = True, p: float = 1.0)[source]¶

Bases: Gain

Apply a different random gain to each audio sample in a batch.

This transform applies a unique random gain value, drawn from a uniform distribution between min_gain and max_gain, to each sample in the input batch. This is useful for batch processing where you want different gain variations for each audio sample in the batch, creating diverse augmentations.

Parameters:

min_gain (float) – Minimum gain in decibels for the random range.
max_gain (float) – Maximum gain in decibels for the random range.
clip (bool, optional) – Whether to clip the output to [-1, 1] range, by default True.
p (float, optional) – Probability of applying the per-sample random gain transform, by default 1.0.

Examples

Basic batch processing:

>>> import numpy as np
>>> from soundmentations.transforms.amplitude import PerSampleRandomGain
>>>
>>> # Create batch of audio samples (2 samples, each 1000 samples long)
>>> batch_samples = np.random.randn(2, 1000) * 0.1
>>>
>>> # Apply different random gain to each sample in batch
>>> per_sample_transform = PerSampleRandomGain(min_gain=-6.0, max_gain=6.0)
>>> result = per_sample_transform(batch_samples)
>>>
>>> # Each row now has a different gain applied
>>> print(f"Sample 1 max: {np.max(np.abs(result[0])):.3f}")
>>> print(f"Sample 2 max: {np.max(np.abs(result[1])):.3f}")

Machine learning data augmentation:

>>> # Training data preparation with varied gains
>>> ml_augment = PerSampleRandomGain(
...     min_gain=-12.0,
...     max_gain=12.0,
...     clip=True,
...     p=0.8
... )
>>>
>>> # Process batch for training
>>> training_batch = np.random.randn(32, 16000)  # 32 samples, 16k each
>>> augmented_batch = ml_augment(training_batch)

Different use cases:

>>> # Subtle variations for speech data
>>> speech_augment = PerSampleRandomGain(min_gain=-3.0, max_gain=3.0)
>>>
>>> # Dramatic variations for sound effects
>>> sfx_augment = PerSampleRandomGain(min_gain=-20.0, max_gain=10.0)
>>>
>>> # Conservative augmentation with low probability
>>> conservative_augment = PerSampleRandomGain(
...     min_gain=-1.5, max_gain=1.5, p=0.3
... )

Notes

Requires 2D input arrays where first dimension is batch size
Each sample in the batch gets an independent random gain
Useful for creating diverse training data in machine learning
The transform maintains the batch structure and sample lengths
Random gains are independently sampled for each batch item

Raises:: ValueError – If input is not a 2D array or if min_gain > max_gain