pyloudnorm

0.2.0 · active · verified Thu Apr 09

pyloudnorm is an active Python library (version 0.2.0) that provides an implementation of the ITU-R BS.1770-4 loudness algorithm. It enables flexible and programmatic control over loudness measurement parameters, including integrated loudness (LUFS) and Loudness Range (LRA). The library is primarily feature-driven, with recent major updates introducing new capabilities and refining Python compatibility.

Warnings

breaking As of version 0.2.0, pyloudnorm officially requires Python 3.9 or newer. Earlier Python versions (3.7, 3.8) are no longer supported.
Fix: Upgrade your Python environment to 3.9 or a newer compatible version.
gotcha The `Meter` class must be initialized with the correct audio sample rate. Providing an incorrect sample rate will lead to inaccurate loudness measurements.
Fix: Ensure the `sample_rate` argument passed to `pyln.Meter()` precisely matches the sample rate of your audio data.
gotcha Measuring integrated loudness or loudness range with very short audio segments (e.g., less than 400ms, due to internal block processing) may yield undefined or incorrect results.
Fix: Provide audio data of sufficient length for meaningful measurements. For integrated loudness, generally at least 400ms is required for the gating algorithm to operate correctly.
gotcha Using very low sample rates (e.g., below 8000 Hz) can lead to numerical instability, overflow issues, or nonsensical loudness values, as the ITU-R BS.1770 algorithm is not intended for such rates. The library may produce very large positive numbers or -inf.
Fix: Process audio at standard or typical audio sample rates (e.g., 44.1 kHz, 48 kHz). If working with very low-frequency audio, consider resampling or understand that loudness measurements might not be perceptually valid.

Install

pip install pyloudnorm Install stable version

Imports

Meter

import pyloudnorm as pyln
meter = pyln.Meter(rate)

Commonly imported with the alias 'pyln'.

Quickstart

This quickstart demonstrates how to initialize a `pyloudnorm.Meter` and measure the integrated loudness (LUFS) and Loudness Range (LRA) of a dummy audio signal. It highlights the primary API calls for basic loudness analysis.

import numpy as np
import pyloudnorm as pyln

# Create dummy mono audio data (e.g., 2 seconds at 44.1 kHz)
sample_rate = 44100  # Hz
duration = 2.0      # seconds
channels = 1        # mono
data = np.random.uniform(-0.5, 0.5, int(sample_rate * duration))

# pyloudnorm expects a 2D array (samples, channels) if multi-channel,
# or 1D array for mono if you adjust it.
# For integrated_loudness, a 1D mono signal works directly.

# Create a BS.1770 meter
meter = pyln.Meter(sample_rate)

# Measure the integrated loudness
loudness = meter.integrated_loudness(data)

print(f"Integrated Loudness: {loudness:.2f} LUFS")

# Example for Loudness Range (LRA) - requires sufficient audio length
# (Often more than 2 seconds, but demonstrating usage)
lra = meter.loudness_range(data)
print(f"Loudness Range: {lra:.2f} LU")

view raw JSON →