soundmentations.RandomGainEnvelope¶

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

Bases: Gain

Apply a smoothly varying random gain envelope to audio samples.

This transform creates a smooth gain envelope by generating random gain values at control points and interpolating between them. This results in gradual gain changes over time, useful for creating natural volume variations.

Parameters:

min_gain (float) – Minimum gain in decibels for the envelope.
max_gain (float) – Maximum gain in decibels for the envelope.
n_control_points (int, optional) – Number of control points for the gain envelope, by default 10. More points create more detailed envelope variations.
clip (bool, optional) – Whether to clip the output to [-1, 1] range, by default True.
p (float, optional) – Probability of applying the random gain envelope transform, by default 1.0.

Examples

Apply a smooth random gain envelope:

>>> import numpy as np
>>> from soundmentations.transforms.amplitude import RandomGainEnvelope
>>>
>>> # Create audio samples (1 second at 8kHz)
>>> samples = np.random.randn(8000) * 0.1
>>>
>>> # Apply smooth gain envelope with 5 control points
>>> envelope_transform = RandomGainEnvelope(
...     min_gain=-12.0,
...     max_gain=6.0,
...     n_control_points=5
... )
>>> result = envelope_transform(samples)

Use in audio processing pipeline:

>>> import soundmentations as S
>>>
>>> # Create dynamic volume processing
>>> dynamic_pipeline = S.Compose([
...     S.RandomGainEnvelope(min_gain=-9.0, max_gain=3.0, n_control_points=8, p=0.7),
...     S.Gain(gain=6.0, p=0.5)  # Additional boost
... ])
>>>
>>> # Process audio with natural volume variations
>>> processed = dynamic_pipeline(samples, sample_rate=44100)

Different envelope scenarios:

>>> # Subtle volume variations for music
>>> subtle_envelope = RandomGainEnvelope(
...     min_gain=-3.0, max_gain=3.0, n_control_points=15
... )
>>>
>>> # Dramatic variations for sound effects
>>> dramatic_envelope = RandomGainEnvelope(
...     min_gain=-20.0, max_gain=10.0, n_control_points=5
... )
>>>
>>> # High-resolution envelope for detailed control
>>> detailed_envelope = RandomGainEnvelope(
...     min_gain=-6.0, max_gain=6.0, n_control_points=50
... )

Notes

The envelope is created by linearly interpolating between random gain values
More control points create more complex envelope shapes
The envelope affects the entire audio sample duration
Gain values are converted from dB to linear scale before application
The transform preserves audio sample length and format