Meters Module

Loudness and metering utilities.

This module provides loudness measurement following EBU R128 standards for broadcast and streaming audio, plus platform and genre-specific targets.

mixref.meters.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
class mixref.meters.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)

class mixref.meters.Platform[source]

Bases: str, Enum

Streaming and playback platforms with standard loudness targets.

SPOTIFY = 'spotify'
YOUTUBE = 'youtube'
APPLE_MUSIC = 'apple_music'
TIDAL = 'tidal'
SOUNDCLOUD = 'soundcloud'
CLUB = 'club'
BROADCAST = 'broadcast'
__new__(value)
class mixref.meters.Genre[source]

Bases: str, Enum

Electronic music genres with specific mastering practices.

DNB = 'dnb'
TECHNO = 'techno'
HOUSE = 'house'
DUBSTEP = 'dubstep'
TRANCE = 'trance'
__new__(value)
class mixref.meters.LoudnessTarget[source]

Bases: NamedTuple

Loudness target specification.

name

Human-readable name (e.g., “Spotify”, “DnB Club Master”)

Type:

str

target_lufs

Target integrated loudness in LUFS

Type:

float

min_lufs

Minimum acceptable LUFS (None = no minimum)

Type:

float | None

max_lufs

Maximum acceptable LUFS (None = no maximum)

Type:

float | None

max_true_peak_db

Maximum true peak in dBTP (typically -1.0)

Type:

float

description

Description of the target use case

Type:

str

name: str

Alias for field number 0

target_lufs: float

Alias for field number 1

min_lufs: float | None

Alias for field number 2

max_lufs: float | None

Alias for field number 3

max_true_peak_db: float

Alias for field number 4

description: str

Alias for field number 5

static __new__(_cls, name, target_lufs, min_lufs, max_lufs, max_true_peak_db, description)

Create new instance of LoudnessTarget(name, target_lufs, min_lufs, max_lufs, max_true_peak_db, description)

mixref.meters.get_target(platform=None, genre=None)[source]

Get loudness target for a platform or genre.

Parameters:

  • platform (Platform | None) – Target platform (Spotify, YouTube, Club, etc.)

  • genre (Genre | None) – Music genre (DnB, Techno, House, etc.)

Returns:

LoudnessTarget with target LUFS, ranges, and description

Raises:

ValueError – If neither platform nor genre specified, or both specified

Return type:

LoudnessTarget

Example

>>> target = get_target(platform=Platform.SPOTIFY)
>>> print(f"Target: {target.target_lufs} LUFS")
Target: -14.0 LUFS

>>> target = get_target(genre=Genre.DNB)
>>> print(f"DnB target: {target.target_lufs} LUFS")
DnB target: -8.0 LUFS
mixref.meters.compare_to_target(measured_lufs, target)[source]

Compare measured loudness against target.

Parameters:

  • measured_lufs (float) – Measured integrated LUFS

  • target (LoudnessTarget) – Target loudness specification

Returns:

  • is_acceptable: True if within acceptable range

  • difference_db: Difference from target (+ve = too loud, -ve = too quiet)

  • message: Human-readable feedback

Return type:

Tuple of (is_acceptable, difference_db, message)

Example

>>> from mixref.meters import calculate_lufs
>>> result = calculate_lufs(audio, 44100)
>>> target = get_target(platform=Platform.SPOTIFY)
>>> ok, diff, msg = compare_to_target(result.integrated_lufs, target)
>>> print(msg)
2.3 dB above Spotify target (-14.0 LUFS). Will be turned down.

Submodules