Class LoudnessAnalyzer

Namespace

PluginUI.Dsp

Assembly

PluginUI.dll

Loudness measurement according to ITU-R BS.1770-4 / EBU R128: momentary (400 ms), short-term (3 s) and integrated (gated) loudness in LUFS, loudness range (LRA, EBU Tech 3342) and sample peak. Feeds LoudnessMeter.

public sealed class LoudnessAnalyzer

Inheritance

object

LoudnessAnalyzer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Processor (audio thread):
readonly LoudnessAnalyzer _loudness = new();
protected override void OnActivate(bool active) { if (active) _loudness.Configure(ProcessSetupData.SampleRate, 2); }
protected override void ProcessMain(in AudioProcessData data)
{
    ... // after processing:
    _loudness.Process(outLeft, outRight);
}

// Editor (UI thread): new LoudnessMeter { Analyzer = processorLoudness }

Remarks

Threading. Call Process(ReadOnlySpan<float>, ReadOnlySpan<float>) on the audio thread (no allocation, no lock, wait-free); read the results from any thread. Configure(double, int, ReadOnlySpan<double>) and Reset() must not run concurrently with Process(ReadOnlySpan<float>, ReadOnlySpan<float>) (call them from OnActivate / SetupProcessing or while processing is stopped).

Algorithm. Each channel goes through the K-weighting filter (high-shelf pre-filter + RLB high-pass, coefficients computed for the actual sample rate), mean squares are accumulated in 100 ms sub-blocks, and the momentary / short-term values are sliding sums of 4 / 30 sub-blocks. Integrated loudness and LRA use histograms with 0.1 LU resolution (absolute gate −70 LUFS, relative gates −10 LU and −20 LU), so memory is constant whatever the duration. Channel weights: 1.0 for front channels (pass 1.41 for surround channels with Configure(double, int, ReadOnlySpan<double>)).

Reference values: a 997 Hz sine at −23 dBFS on both channels of a stereo signal reads −23.0 LUFS.

Constructors

LoudnessAnalyzer()

Creates an analyzer for stereo at 48 kHz (call Configure(double, int, ReadOnlySpan<double>) with the real settings).

public LoudnessAnalyzer()

Properties

ChannelCount

Number of channels.

public int ChannelCount { get; }

Property Value

int

IntegratedLufs

Integrated (program) loudness in LUFS since the last Reset(), with the absolute (−70 LUFS) and relative (−10 LU) gates of BS.1770-4; −∞ while no block passes the gates. Computed on demand (O(1000)).

public double IntegratedLufs { get; }

Property Value

double

LoudnessRange

Loudness range (LRA) in LU (EBU Tech 3342): spread between the 10th and 95th percentiles of the short-term loudness, after absolute (−70 LUFS) and relative (−20 LU) gating; 0 while too little signal was measured.

public double LoudnessRange { get; }

Property Value

double

MomentaryLufs

Momentary loudness (400 ms window) in LUFS; −∞ before 400 ms of signal or during digital silence.

public double MomentaryLufs { get; }

Property Value

double

SamplePeak

Largest absolute sample value since the last Reset() (linear, 1.0 = 0 dBFS).

public float SamplePeak { get; }

Property Value

float

SampleRate

Sample rate in Hz.

public double SampleRate { get; }

Property Value

double

ShortTermLufs

Short-term loudness (3 s window) in LUFS; −∞ before 3 s of signal.

public double ShortTermLufs { get; }

Property Value

double

Methods

Configure(double, int, ReadOnlySpan<double>)

Prepares the filters for a sample rate and a channel layout, and resets all measurements.

public void Configure(double sampleRate, int channelCount, ReadOnlySpan<double> channelWeights = default)

Parameters

sampleRate double

Sample rate in Hz (8 kHz to 384 kHz).

channelCount int

Number of channels (1 to 8).

channelWeights ReadOnlySpan<double>

Weight of each channel (BS.1770: 1.0 for L, R, C; 1.41 for Ls, Rs; 0 to ignore LFE), or null for 1.0.

Exceptions

ArgumentOutOfRangeException

sampleRate or channelCount is out of range.

KWeighting(double)

K-weighting coefficients (BS.1770 pre-filter and RLB high-pass) for any sample rate, from the analog prototypes through the bilinear transform; at 48 kHz they match the coefficients tabulated in BS.1770.

public static (double[] PreB, double[] PreA, double[] RlbB, double[] RlbA) KWeighting(double sampleRate)

Parameters

sampleRate double

Sample rate in Hz.

Returns

(double[] PreB, double[] PreA, double[] RlbB, double[] RlbA)

Numerator and denominator (a0 = 1) of both sections.

Process(ReadOnlySpan<float>)

Audio thread: analyzes a mono block (or the first channel of the configuration).

public void Process(ReadOnlySpan<float> mono)

Parameters

mono ReadOnlySpan<float>

Samples.

Process(ReadOnlySpan<float>, ReadOnlySpan<float>)

Audio thread: analyzes a stereo block (or the first two channels).

public void Process(ReadOnlySpan<float> left, ReadOnlySpan<float> right)

Parameters

left ReadOnlySpan<float>

Left channel samples.

right ReadOnlySpan<float>

Right channel samples (same length as left).

Exceptions

ArgumentException

The spans have different lengths.

RequestReset()

Thread-safe reset request (e.g. from a "reset" button of the UI): the measurements are cleared by the audio thread at the beginning of the next Process(ReadOnlySpan<float>, ReadOnlySpan<float>) call.

public void RequestReset()

Reset()

Clears all measurements (integrated loudness, LRA, peak) and the filter states.

public void Reset()