Compare Module

Compare module for mixref - A/B comparison tools.

class mixref.compare.BandComparison

Bases: object

Comparison of a single frequency band.

band_name

Name of frequency band (Sub, Low, Mid, High, Air)

Type:

str

track_energy

Track’s energy in this band (percentage)

Type:

float

reference_energy

Reference’s energy in this band (percentage)

Type:

float

difference

Difference in energy (positive = track has more energy)

Type:

float

is_significant

True if difference is > 3dB (noticeable)

Type:

bool

band_name: str

track_energy: float

reference_energy: float

difference: float

is_significant: bool

__init__(band_name, track_energy, reference_energy, difference, is_significant)

class mixref.compare.ComparisonResult

Bases: object

Complete A/B comparison result.

track_name

Name of analyzed track

Type:

str

reference_name

Name of reference track

Type:

str

loudness

Loudness comparison

Type:

mixref.compare.engine.LoudnessComparison

spectral

Spectral balance comparison

Type:

mixref.compare.engine.SpectralComparison

track_bpm

Track’s BPM (optional)

Type:

float | None

reference_bpm

Reference’s BPM (optional)

Type:

float | None

bpm_difference

Difference in BPM (optional)

Type:

float | None

track_key

Track’s musical key (optional)

Type:

str | None

reference_key

Reference’s musical key (optional)

Type:

str | None

track_name: str

reference_name: str

loudness: LoudnessComparison

spectral: SpectralComparison

track_bpm: float | None = None

reference_bpm: float | None = None

bpm_difference: float | None = None

track_key: str | None = None

reference_key: str | None = None

__init__(track_name, reference_name, loudness, spectral, track_bpm=None, reference_bpm=None, bpm_difference=None, track_key=None, reference_key=None)

class mixref.compare.LoudnessComparison

Bases: object

Comparison of loudness metrics between two tracks.

track_lufs

Track’s integrated LUFS

Type:

float

reference_lufs

Reference’s integrated LUFS

Type:

float

lufs_difference

Difference in LUFS (positive = track is louder)

Type:

float

track_peak

Track’s true peak in dBTP

Type:

float

reference_peak

Reference’s true peak in dBTP

Type:

float

peak_difference

Difference in true peak (positive = track has higher peak)

Type:

float

track_lra

Track’s loudness range in LU

Type:

float

reference_lra

Reference’s loudness range in LU

Type:

float

lra_difference

Difference in LRA (positive = track has wider dynamics)

Type:

float

track_lufs: float

reference_lufs: float

lufs_difference: float

track_peak: float

reference_peak: float

peak_difference: float

track_lra: float

reference_lra: float

lra_difference: float

__init__(track_lufs, reference_lufs, lufs_difference, track_peak, reference_peak, peak_difference, track_lra, reference_lra, lra_difference)

class mixref.compare.SpectralComparison

Bases: object

Comparison of spectral balance between two tracks.

bands

List of band comparisons (Sub, Low, Mid, High, Air)

Type:

list[mixref.compare.engine.BandComparison]

bands: list[BandComparison]

__init__(bands)

mixref.compare.compare_loudness(track_result, reference_result)

Compare loudness metrics between two tracks.

Parameters:

• track_result (LoudnessResult) – Loudness result for the track being analyzed

• reference_result (LoudnessResult) – Loudness result for the reference track

Returns:

LoudnessComparison with differences

Return type:

LoudnessComparison

Example

>>> from mixref.meters import calculate_lufs
>>> track_lufs = calculate_lufs(track_audio, 44100)
>>> ref_lufs = calculate_lufs(ref_audio, 44100)
>>> comparison = compare_loudness(track_lufs, ref_lufs)
>>> print(f"LUFS difference: {comparison.lufs_difference:+.1f} dB")
LUFS difference: -2.1 dB

mixref.compare.compare_spectral(track_result, reference_result, significance_threshold=3.0)

Compare spectral balance between two tracks.

Parameters:

• track_result (SpectralResult) – Spectral result for the track being analyzed

• reference_result (SpectralResult) – Spectral result for the reference track

• significance_threshold (float) – Minimum difference (in percentage points) to be considered significant. Default: 3.0 (roughly 3dB difference)

Returns:

SpectralComparison with band-by-band differences

Return type:

SpectralComparison

Example

>>> from mixref.detective import analyze_spectrum
>>> track_spec = analyze_spectrum(track_audio, 44100)
>>> ref_spec = analyze_spectrum(ref_audio, 44100)
>>> comparison = compare_spectral(track_spec, ref_spec)
>>> for band in comparison.bands:
...     if band.is_significant:
...         print(f"{band.band_name}: {band.difference:+.1f}%")
Sub: -3.2%
High: +4.1%

mixref.compare.compare_tracks(track_audio, reference_audio, sample_rate, track_name='Track', reference_name='Reference', include_bpm=False, include_key=False)

Compare two audio tracks comprehensively.

Analyzes both tracks and compares loudness, spectral balance, BPM, and key.

Parameters:

• track_audio (ndarray[Any, dtype[float32]]) – Audio data for track being analyzed. Shape: (samples,) for mono or (samples, channels) for stereo

• reference_audio (ndarray[Any, dtype[float32]]) – Audio data for reference track. Shape: (samples,) for mono or (samples, channels) for stereo

• sample_rate (int) – Sample rate in Hz (must be same for both tracks)

• track_name (str) – Human-readable name for the track (e.g., filename)

• reference_name (str) – Human-readable name for the reference

• include_bpm (bool) – If True, detect and compare BPM (slower)

• include_key (bool) – If True, detect and compare musical key (slower)

Returns:

ComparisonResult with all metrics

Raises:

ValueError – If audio arrays have incompatible shapes or invalid sample rate

Return type:

ComparisonResult

Example

>>> from mixref.audio import load_audio
>>> track, sr = load_audio("my_mix.wav")
>>> reference, _ = load_audio("pro_reference.wav", sample_rate=sr)
>>> result = compare_tracks(track, reference, sr, include_bpm=True)
>>> print(f"LUFS diff: {result.loudness.lufs_difference:+.1f} dB")
LUFS diff: -2.3 dB