Real-time safe EBU R128 loudness meter. More...

#include <LoudnessMeter.h>

Classes
struct	MeasurementInfo
	Window/gate coverage for a stopped or stream-owner measurement. Durations use the existing floor(sampleRate / 10) sample hop (minimum 1). The last partial hop contributes to neither windows nor histograms yet. Gate counts include complete windows surviving the absolute -70 LUFS gate, before each metric's relative gate. A zero count is not valid loudness. More...

Public Member Functions
MeasurementInfo	getMeasurementInfo () const noexcept
	Returns window coverage without modifying any state. Call from the stream owner, or after processing has stopped. Unlike the scalar GUI readouts, this reads the writer-owned hop counters. Bounded O(histogram bins) work and no allocation. Invalid measurements must also be rejected using isMeasurementValid().

void	prepare (double sampleRate, int numChannels=2) noexcept
	Prepares the meter and pre-calculates filter coefficients.

void	prepare (const AudioSpec &spec) noexcept
	Unified API preparation.

void	processBlock (AudioBufferView< const T > buffer) noexcept
	Processes a non-interleaved buffer view (read-only).

void	process (const T *data, int numSamples) noexcept
	Processes a mono block of samples.

void	process (const T left, const T right, int numSamples) noexcept
	Processes a stereo block of samples.

T	getMomentaryLUFS () const noexcept
	Reads the Momentary loudness (400 ms window).

T	getShortTermLUFS () const noexcept
	Reads the Short-term loudness (3 second window).

T	getIntegratedLUFS () const noexcept
	Computes the Integrated loudness using standard two-pass gating.

bool	isMeasurementValid () const noexcept
	Reports whether every measurement since reset was representable.

T	getTruePeakDb () const noexcept
	Returns the maximum true peak observed since the last reset.

void	finalizeTruePeak () noexcept
	Includes the final interpolation tail of a finite programme. Call after the last input block, from the stream owner; readers may remain concurrent. Repeated calls are idempotent. The Core detector evaluates zero extension on copied state: programme duration, loudness windows, integrated/LRA gates and live filter history are unchanged. No allocation. Do not call after each block of one continuous programme: the zero-ended prefix peak would then be retained in the maximum. reset() starts a new measurement as usual.

T	getLoudnessRange () const noexcept
	Computes the EBU R128 Loudness Range (EBU Tech 3342).

void	reset () noexcept
	Clears all measurements and resets filters.

Detailed Description

template<FloatType T>
class dspark::LoudnessMeter< T >

Real-time safe EBU R128 loudness meter.

Implements Momentary (400ms), Short-Term (3s), and Integrated (gated) measurements. Utilizes a constant-memory histogram for infinite integrated loudness tracking without memory allocation or O(N) CPU scaling, ensuring strict RT compliance.

Scalar readouts (getMomentaryLUFS, etc.) are lock-free and thread-safe for GUI threads while audio is processing. getMeasurementInfo() instead requires the stream owner or a stopped measurement.

Template Parameters

T	Sample type (float or double).

Definition at line 59 of file LoudnessMeter.h.

Member Function Documentation

◆ finalizeTruePeak()

template<FloatType T>

void dspark::LoudnessMeter< T >::finalizeTruePeak ( )

inlinenoexcept

Includes the final interpolation tail of a finite programme. Call after the last input block, from the stream owner; readers may remain concurrent. Repeated calls are idempotent. The Core detector evaluates zero extension on copied state: programme duration, loudness windows, integrated/LRA gates and live filter history are unchanged. No allocation. Do not call after each block of one continuous programme: the zero-ended prefix peak would then be retained in the maximum. reset() starts a new measurement as usual.

Definition at line 329 of file LoudnessMeter.h.

◆ getIntegratedLUFS()

template<FloatType T>

T dspark::LoudnessMeter< T >::getIntegratedLUFS ( ) const

inlinenoexcept

Computes the Integrated loudness using standard two-pass gating.

Note: O(bins) with a constant bin count (no per-block cost growth). Safe to call from any thread.

Returns: Loudness in LUFS (minimum -100.0).

Definition at line 251 of file LoudnessMeter.h.

◆ getLoudnessRange()

template<FloatType T>

T dspark::LoudnessMeter< T >::getLoudnessRange ( ) const

inlinenoexcept

Computes the EBU R128 Loudness Range (EBU Tech 3342).

Short-term (3 s) loudness sampled at 10 Hz (every 100 ms, as Tech 3342 V3 and later require), gated at -70 LUFS absolute and -20 LU relative; LRA is the spread between the 10th and 95th percentiles. O(bins) and real-time safe like the integrated gate.

Percentiles follow the Tech 3342 reference code: among the n gated short-term values sorted ascending, P is the value at 0-based rank round((n - 1) * P). Values are held at 0.1 LU resolution. The first short-term value exists after 3 s of input, so a programme shorter than that reads 0; a steady programme reads 0 at any length.

Returns: Loudness range in LU (0 if not enough material yet).

Definition at line 360 of file LoudnessMeter.h.

◆ getMeasurementInfo()

template<FloatType T>

MeasurementInfo dspark::LoudnessMeter< T >::getMeasurementInfo ( ) const

inlinenoexcept

Returns window coverage without modifying any state. Call from the stream owner, or after processing has stopped. Unlike the scalar GUI readouts, this reads the writer-owned hop counters. Bounded O(histogram bins) work and no allocation. Invalid measurements must also be rejected using isMeasurementValid().

Definition at line 83 of file LoudnessMeter.h.

◆ getMomentaryLUFS()

template<FloatType T>

T dspark::LoudnessMeter< T >::getMomentaryLUFS ( ) const

inlinenoexcept

Reads the Momentary loudness (400 ms window).

Returns: Loudness in LUFS (minimum -100.0).

Definition at line 231 of file LoudnessMeter.h.

◆ getShortTermLUFS()

template<FloatType T>

T dspark::LoudnessMeter< T >::getShortTermLUFS ( ) const

inlinenoexcept

Reads the Short-term loudness (3 second window).

Returns: Loudness in LUFS (minimum -100.0).

Definition at line 240 of file LoudnessMeter.h.

◆ getTruePeakDb()

template<FloatType T>

T dspark::LoudnessMeter< T >::getTruePeakDb ( ) const

inlinenoexcept

Returns the maximum true peak observed since the last reset.

Returns: True peak in dBTP (ITU-R BS.1770-4, 4x oversampled estimate).

Definition at line 315 of file LoudnessMeter.h.

◆ isMeasurementValid()

template<FloatType T>

bool dspark::LoudnessMeter< T >::isMeasurementValid ( ) const

inlinenoexcept

Reports whether every measurement since reset was representable.

False means a filter/accumulator became non-finite, a block had to be discarded, or a histogram could not represent another value exactly. The streaming meter continues recovering where possible, but an offline caller can use this diagnostic to distinguish recovery from silence. reset() starts a new diagnostic transaction.

Definition at line 306 of file LoudnessMeter.h.

◆ prepare() [1/2]

template<FloatType T>

void dspark::LoudnessMeter< T >::prepare ( const AudioSpec & spec )

inlinenoexcept

Unified API preparation.

Definition at line 127 of file LoudnessMeter.h.

◆ prepare() [2/2]

template<FloatType T>

void dspark::LoudnessMeter< T >::prepare	(	double	sampleRate,
		int	numChannels = `2`
	)

inlinenoexcept

Prepares the meter and pre-calculates filter coefficients.

A non-finite or non-positive sample rate is ignored (conservative no-op keeping the previous state).

Parameters

sampleRate	Sample rate in Hz (must be > 0 and finite).
numChannels	Accepted for API symmetry; the channel layout is taken from each processed buffer (up to 2 channels are measured).

Definition at line 109 of file LoudnessMeter.h.

◆ process() [1/2]

template<FloatType T>

void dspark::LoudnessMeter< T >::process	(	const T *	data,
		int	numSamples
	)

inlinenoexcept

Processes a mono block of samples.

Parameters

data	Pointer to mono audio data.
numSamples	Number of samples to process.

Definition at line 155 of file LoudnessMeter.h.

◆ process() [2/2]

template<FloatType T>

void dspark::LoudnessMeter< T >::process	(	const T *	left,
		const T *	right,
		int	numSamples
	)

inlinenoexcept

Processes a stereo block of samples.

Parameters

left	Pointer to left channel data.
right	Pointer to right channel data.
numSamples	Number of samples per channel.

Definition at line 192 of file LoudnessMeter.h.

◆ processBlock()

template<FloatType T>

void dspark::LoudnessMeter< T >::processBlock ( AudioBufferView< const T > buffer )

inlinenoexcept

Processes a non-interleaved buffer view (read-only).

The first two channels are measured; additional channels are ignored (multichannel spatial weighting is not implemented).

Parameters

buffer AudioBufferView to analyze.

Definition at line 140 of file LoudnessMeter.h.

◆ reset()

template<FloatType T>

void dspark::LoudnessMeter< T >::reset ( )

inlinenoexcept

Clears all measurements and resets filters.

Call from the stream owner or a setup thread, not concurrently with the process calls: the accumulators and filter states are plain writer-owned members.

Definition at line 423 of file LoudnessMeter.h.

The documentation for this class was generated from the following file:

LoudnessMeter.h

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ finalizeTruePeak()

◆ getIntegratedLUFS()

◆ getLoudnessRange()

◆ getMeasurementInfo()

◆ getMomentaryLUFS()

◆ getShortTermLUFS()

◆ getTruePeakDb()

◆ isMeasurementValid()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ process() [1/2]

◆ process() [2/2]

◆ processBlock()

◆ reset()