Feature Request: Support for Target Level Normalization

[LarocheC]

Feature Description

I propose the addition of an target level normalization augmentation to the torch-audiomentations library. This feature would analyze an audio signal's average power and adjust its gain to normalize the signal to a target RMS level.

Current Limitations

While the library currently supports peak normalization and gain adjustments, these methods do not directly allow setting a specific RMS across audio signals. Gain adjustments without explicit RMS targeting can result in inaccurate loudness levels especially those with large dynamic ranges.

Potential Implementation

An RMS normalization feature would provide a more accurate way to achieve a set level across different audio signals. Considering the function already available in the library. It would be similar to the gain augmentation. The actual gain would be a function of the signal current level and of the target RMS value.

Considerations for Preventing Clipping

When setting high levels, clipping can occur if the signal's peak amplitude exceeds the system's maximum representable limit, leading to distortion. To prevent this issue, we could take into consideration the crest factor for different types of signals.

I believe this would enhance the library's utility for audio processing and production tasks. Thank you for considering this proposal. I look forward to discussing it further and am open to contributing to its implementation.

[iver56]

Thanks for the feature request

[Shohail-Ismail]

Hi, I’d love to take this on!

I’m currently working on a student research project involving spectral analysis and normalisation, so this would tie in nicely. I had a few quick questions before I start:

• Should target_level be in dBFS or linear RMS?
• Is per-channel RMS normalisation peferred (for multi-channel audio) or should it operate on a single combined signal?

Happy to draft an implementation plan once I get a sense of direction for the issue. Thanks!

[iver56]

• I would prefer dBFS
• I would prefer the combined signal (e.g. gain both channels in a stereo track by the same amount)

[Shohail-Ismail]

Thanks! I made an draft implementation plan for the transform, please let me know if I’ve missed anything or if you’d like any naming tweaks:

Class signature

class RMSNormalisation(BaseWaveformTransform):
    Adjusts gain so that the signal’s overall RMS matches `target_level_dbfs`

    args:
        target_level_dbfs (float): Desired RMS level in dBFS (with 0 dBFS = full scale)
        eps (float, optional): Small constant to avoid divide by 0. Default: 1e-9

---

Core algorithm (apply)

1) Compute combined‐signal RMS:

rms = x.pow(2).mean(dim = (-1, -2),keepdim = True).sqrt()

2) Compute gain = db_to_amplitude(target) ÷ (rms + eps)

3) Cap gain so peak(x) * gain <= 1.0 to prevent clipping

4) Return x * gain

---

Edge cases

If silence (rms ~ 0) then output stays 0. If multi-channel then same scalar gain for all channels.

---

Tests

• Sine wave: adjust from -20 to -10 dB, check RMS within +-0.5 dB

• Silence: output 0, check no NaNs

• Stereo: both channels gain equally

---

Happy to adjust anything before implementation!

[iver56]

LGTM, but I would personally not include this step:

3. Cap gain so peak(x) * gain <= 1.0 to prevent clipping

Reasoning: If each transform would be responsible for avoiding clipping, we would maintain a lot of extra code and have more code to execute. It's better to have a single step at the end of the data augmentation signal chain that prevents values outside the [-1, 1] range, if you ask me. Also, float32 doesn't have inherent clipping issues, so it's acceptable to have extreme values within the signal chain, as long as it's dealt with before it gets passed to something that needs the values to be within [-1, 1]

[Shohail-Ismail]

Thanks for the clarification! I’ll remove the clipping logic and have the transform only:

1. Compute combined‐signal RMS
2. Compute gain = db_to_amplitude(target) / (rms + eps)
3. Return x * gain

As everything else is GTG, I’ll start coding on that basis now.