engine::LoudnessMeter Class Reference

A real-time-safe EBU R128 / ITU-R BS.1770-4 loudness meter. More...

#include <tracktion_LoudnessMeter.h>

Classes
struct	Readings
	A snapshot of the meter's current readings. More...

Public Member Functions
	LoudnessMeter ()=default
void	prepare (double sampleRate, int numChannels, int maxBlockSize)
	Allocates for the given format and resets the measurement.
void	process (choc::buffer::ChannelArrayView< const float > block) noexcept
	Processes a block of audio, updating the published readings.
void	process (const float *const *channels, int numChannels, int numSamples) noexcept
	Processes a block of audio from raw channel pointers.
void	flush () noexcept
	For offline use: finishes a partially-filled gating block if it's at least half full, so a file's tail contributes to the measurement.
void	requestReset () noexcept
	Asks for the integrated measurement, held maxima and peaks to be restarted.
Readings	getReadings () const noexcept
	Returns the current readings.

Static Public Attributes
static constexpr float	silenceFloorDb = -100.0f
	The value used for readings which haven't seen any audio yet.

Detailed Description

A real-time-safe EBU R128 / ITU-R BS.1770-4 loudness meter.

It measures momentary (400ms), short-term (3s) and gated integrated loudness, loudness range (EBU Tech 3342) and 4x-oversampled true peak and sample peak, and can be driven either from an audio callback or from an offline file pass.

Real-time contract:

• prepare() does all of the allocation and must not be called while processing.
• process() is allocation- and lock-free, and takes no locks internally.
• getReadings() may be called from any thread (typically a UI timer) while process() is running on the audio thread. It returns one internally consistent snapshot, via a seqlock: the write side stays wait-free, and the read side only retries if it collides with a publish.

Unlike a straight offline implementation, the integrated measurement doesn't keep the whole history of gating blocks: momentary powers are accumulated into a fixed 0.1 LU histogram (the libebur128 approach), so the memory is constant and the gated result is recomputed in constant time every 100ms. Only the two gate decisions are quantised, to at most the 0.1 LU bin width, which is far inside the EBU R128 tolerance. Loudness range works the same way, from a second histogram of short-term loudness.

Constructor & Destructor Documentation

LoudnessMeter()

engine::LoudnessMeter::LoudnessMeter ( )

default

Member Function Documentation

prepare()

void engine::LoudnessMeter::prepare	(	double	sampleRate,
		int	numChannels,
		int	maxBlockSize
	)

Allocates for the given format and resets the measurement.

Must be called before process(), and never whilst processing.

Parameters

maxBlockSize

the largest block process() will be given in one go internally - longer blocks are chunked, so this only needs to be a sensible working size

process() [1/2]

void engine::LoudnessMeter::process ( choc::buffer::ChannelArrayView< const float >  block )

noexcept

Processes a block of audio, updating the published readings.

Real-time safe: no allocation, no locks. The block can be any length - it's chunked internally to the prepared maximum block size. Channels beyond the number passed to prepare() are ignored.

process() [2/2]

void engine::LoudnessMeter::process ( const float *const *  channels, int  numChannels, int  numSamples  )

noexcept

Processes a block of audio from raw channel pointers.

See also

process (choc::buffer::ChannelArrayView<const float>)

flush()

void engine::LoudnessMeter::flush ( )

noexcept

For offline use: finishes a partially-filled gating block if it's at least half full, so a file's tail contributes to the measurement.

Call this after the last process() call, not during streaming.

requestReset()

void engine::LoudnessMeter::requestReset ( )

noexcept

Asks for the integrated measurement, held maxima and peaks to be restarted.

The request is picked up by the processing thread at the start of its next block, so this never blocks. The K-weighting filter state is deliberately left running, to avoid a reset causing a filter transient.

getReadings()

Readings engine::LoudnessMeter::getReadings ( ) const

noexcept

Returns the current readings.

Lock-free, callable from any thread.

Member Data Documentation

silenceFloorDb

constexpr float engine::LoudnessMeter::silenceFloorDb = -100.0f

staticconstexpr

The value used for readings which haven't seen any audio yet.

---

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

• tracktion_LoudnessMeter.h