Loudness Metering

Loudness metering using EBU R128 standard.

This module provides loudness measurement following the EBU R128 recommendation for broadcast and streaming audio. Uses pyloudnorm for accurate K-weighted integrated loudness (LUFS) measurement.

class mixref.meters.loudness.LoudnessResult[source]

Bases: NamedTuple

EBU R128 loudness measurement results.

integrated_lufs

Integrated loudness in LUFS (Loudness Units Full Scale)

Type:: float

true_peak_db

Maximum true peak level in dBTP (decibels True Peak)

Type:: float

loudness_range_lu

Loudness range (LRA) in LU, measures dynamic range

Type:: float

short_term_max_lufs

Maximum short-term loudness in LUFS

Type:: float

short_term_min_lufs

Minimum short-term loudness in LUFS

Type:: float

integrated_lufs: float: Alias for field number 0

true_peak_db: float: Alias for field number 1

loudness_range_lu: float: Alias for field number 2

short_term_max_lufs: float: Alias for field number 3

short_term_min_lufs: float: Alias for field number 4

static __new__(_cls, integrated_lufs, true_peak_db, loudness_range_lu, short_term_max_lufs, short_term_min_lufs)

Create new instance of LoudnessResult(integrated_lufs, true_peak_db, loudness_range_lu, short_term_max_lufs, short_term_min_lufs)

mixref.meters.loudness.calculate_lufs(audio, sample_rate)[source]

Calculate EBU R128 loudness metrics for audio.

Measures integrated loudness (LUFS), true peak (dBTP), and loudness range (LRA) according to EBU R128 / ITU-R BS.1770-4 standards.

Parameters:

audio (ndarray[Any, dtype[float32]]) – Audio data as float32 array. Shape: (samples,) for mono or (2, samples) for stereo
sample_rate (int) – Sample rate in Hz (e.g., 44100, 48000)

Returns:

LoudnessResult with integrated LUFS, true peak, LRA, and short-term ranges

Raises:

ValueError – If audio is not mono or stereo, or if sample rate is invalid

Return type:

LoudnessResult

Example

>>> from mixref.audio import load_audio
>>> audio, sr = load_audio("my_track.wav")
>>> result = calculate_lufs(audio, sr)
>>> print(f"Integrated: {result.integrated_lufs:.1f} LUFS")
Integrated: -8.2 LUFS
>>> print(f"True Peak: {result.true_peak_db:.1f} dBTP")
True Peak: -0.3 dBTP