Adds a cap on the maximum gain for added noise

[Arne Nix (ArneNx)]

Summary

• Add set_audio_mix_max_gain_db() / get_audio_mix_max_gain_db() API (+ env var
  LHOTSE_AUDIO_MIX_MAX_GAIN_DB) to cap the amplitude gain applied during SNR-based
  audio mixing in AudioMixer
• Prevents near-silent noise clips from being amplified by orders of magnitude, which
  produces high-amplitude artifacts that corrupt training data

Motivation

When using CutSet.mix() for noise augmentation (e.g. with MUSAN), the gain applied to
the noise signal is computed as:

gain = sqrt(target_energy / noise_energy)

If a noise clip — or a random offset into one (random_mix_offset=True) — has
near-zero energy, the gain approaches infinity. For example, with
noise_energy ≈ 1e-12, the gain can reach ~1e6, turning a near-silent clip into a
high-amplitude artifact that completely drowns out the speech signal. The mixed audio is
then paired with the original transcript during ASR training, teaching the model to
hallucinate text from noise.

NeMo's native NoisePerturbation has an explicit max_gain_db cap (default 300 dB) for
this reason, but Lhotse's AudioMixer had none.

API

Follows the same pattern as set_audio_duration_mismatch_tolerance():

from lhotse import set_audio_mix_max_gain_db

# Cap noise amplification at 40 dB (amplitude factor of 100x)
set_audio_mix_max_gain_db(40.0)

# Or via environment variable:
# LHOTSE_AUDIO_MIX_MAX_GAIN_DB=40.0
The default is None (no cap), preserving full backward compatibility.

[Copilot]

Pull request overview

Adds an opt-in global cap (including env var support) for maximum gain during SNR-based audio mixing to prevent extreme amplification of near-silent noise segments that can corrupt training data.

Changes:

• Introduces get_audio_mix_max_gain_db() / set_audio_mix_max_gain_db() with LHOTSE_AUDIO_MIX_MAX_GAIN_DB support.
• Applies the configured max-gain cap inside AudioMixer by clamping the computed SNR gain.
• Exposes the new API from lhotse.audio and the package root.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
lhotse/audio/utils.py	Adds global getter/setter and env var lookup for max mix gain (dB).
lhotse/audio/mixer.py	Converts max gain dB to linear factor and clamps computed mixing gain.
lhotse/audio/init.py	Re-exports the new getter/setter from the audio package.
lhotse/init.py	Re-exports the new getter/setter from the top-level package.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.