distortion-residual

A differentiable Distortion Residual Level (DRL) metric for PyTorch.

DRL measures the nonlinear distortion introduced by audio processors (limiters, compressors, saturators, etc.) using the nulling method:

1. Level-match the reference to the processed signal via least-squares projection, cancelling any linear gain difference.
2. Subtract the matched reference from the processed signal to isolate the distortion residual.
3. Measure the power ratio of the residual to the signal:

$$ \text{DRL} = 10 \log_{10} \frac{\lVert d \rVert^2}{\lVert \hat{g},x \rVert^2}, \qquad \hat{g} = \frac{\langle x, y \rangle}{\langle x, x \rangle}, \qquad d = y - \hat{g},x $$

Every operation is differentiable, so DRL can be used directly as a loss function for gradient-based optimisation of audio processing parameters.

Installation

pip install distortion-residual

Or from source:

git clone https://github.com/agrathwohl/distortion-residual.git
cd distortion-residual
pip install -e .

Optional: audio file I/O

pip install "distortion-residual[audio]"

Quick start

import torch
from distortion_residual import DRL

drl = DRL(sample_rate=44100)

reference = torch.randn(44100)              # 1 s of audio
processed = torch.clamp(reference, -0.5, 0.5)  # hard-clip at -6 dBFS

result = drl(reference, processed)
print(result["total_drl_db"])    # e.g. tensor(-18.42)
print(result["total_drl_percent"])  # e.g. tensor(12.0)

As a loss function

gain = torch.tensor(1.0, requires_grad=True)
processed = torch.tanh(reference * gain)

result = drl(reference, processed)
loss = result["total_drl_db"]
loss.backward()
print(gain.grad)  # gradient flows through

Band-wise analysis

By default, DRL is decomposed into three frequency bands (20-200 Hz, 200-2000 Hz, 2000-20000 Hz). You can customise or disable this:

# Custom bands
drl = DRL(sample_rate=44100, frequency_bands=[(100, 1000), (1000, 10000)])

# Broadband only (faster, no FIR filtering)
drl = DRL(sample_rate=44100, frequency_bands=None)

Output dictionary

DRL.forward() returns a dict with:

How it works

The level-matching step (g_hat = <x,y>/<x,x>) projects out any linear gain component, so DRL is invariant to makeup gain. Only the nonlinear distortion component remains in the residual.

This makes DRL ideal for optimising dynamics processors: the loss function measures what the processor does to the waveform shape, not how loud it makes the output.

Gradient properties

• Through the residual: linear subtraction, gradients pass directly.
• Through level matching: quotient rule on the inner-product ratio.
• Through band filters: FIR convolution is a linear operation.

All paths are fully differentiable. No straight-through estimators or surrogate gradients required.

Development

git clone https://github.com/agrathwohl/distortion-residual.git
cd distortion-residual
uv sync --extra dev
uv run pytest

License

MIT