Crate oximedia_metering

Expand description

Professional broadcast audio metering for OxiMedia.

This crate provides comprehensive, standards-compliant audio loudness measurement and metering for broadcast, streaming, and professional audio applications.

§Supported Standards

ITU-R BS.1770-4 - Algorithms to measure audio programme loudness and true-peak level
ITU-R BS.1771 - Requirements for loudness and true-peak indicating meters
EBU R128 - Loudness normalisation and permitted maximum level (European standard)
ATSC A/85 - Techniques for Establishing and Maintaining Audio Loudness (US standard)
Dolby Metadata - Dialogue Intelligence metadata generation (metadata only, respects IP)

§Features

§Loudness Measurement

Momentary Loudness - 400ms sliding window with 75% overlap
Short-term Loudness - 3-second sliding window with 75% overlap
Integrated Loudness - Gated program loudness (LKFS/LUFS)
Loudness Range (LRA) - Dynamic range measurement using percentile-based method

§True Peak Detection

4x Oversampling - Detects inter-sample peaks using sinc interpolation
Per-channel Tracking - Individual true peak levels for each channel
dBTP Conversion - True peak in dB relative to full scale

§Gating Algorithm

Absolute Gate - -70 LKFS threshold
Relative Gate - -10 LU below ungated loudness
Two-stage Process - ITU-R BS.1771 compliant gating

§Multi-channel Support

Supports up to 7.1.4 Dolby Atmos layouts with proper channel weighting:

Mono (1.0)
Stereo (2.0)
5.1 Surround
7.1 Surround
7.1.4 Dolby Atmos (bed channels)

§Compliance Checking

EBU R128 compliance (target: -23 LUFS ±1 LU, peak: -1 dBTP)
ATSC A/85 compliance (target: -24 LKFS ±2 dB, peak: -2 dBTP)
Streaming platform targets (Spotify, YouTube, Apple Music, etc.)

§Example Usage

§Basic Loudness Metering

use oximedia_metering::{LoudnessMeter, MeterConfig, Standard};

// Create meter for EBU R128
let config = MeterConfig::new(Standard::EbuR128, 48000.0, 2);
let mut meter = LoudnessMeter::new(config).expect("Failed to create meter");

// Process audio samples (interleaved f32)
meter.process_f32(audio_samples);

// Get loudness metrics
let metrics = meter.metrics();
println!("Integrated: {:.1} LUFS", metrics.integrated_lufs);
println!("LRA: {:.1} LU", metrics.loudness_range);
println!("True Peak: {:.1} dBTP", metrics.true_peak_dbtp);

// Check compliance
let compliance = meter.check_compliance();
if compliance.is_compliant() {
    println!("Audio is compliant with {}", compliance.standard_name());
}

// Generate detailed report
let report = meter.generate_report();
println!("{}", report);

§Peak Metering

use oximedia_metering::{PeakMeter, PeakMeterType};

// Create a VU meter for stereo audio
let mut vu_meter = PeakMeter::new(
    PeakMeterType::Vu,
    48000.0,
    2,
    2.0  // 2 second peak hold
).expect("Failed to create VU meter");

vu_meter.process_interleaved(audio_samples);

let peaks = vu_meter.peak_dbfs();
println!("L: {:.1} dBFS, R: {:.1} dBFS", peaks[0], peaks[1]);

// Create an RMS meter with 300ms integration
let mut rms_meter = PeakMeter::new(
    PeakMeterType::Rms(0.3),
    48000.0,
    2,
    0.0
).expect("Failed to create RMS meter");

§K-System Metering

use oximedia_metering::{KSystemMeter, KSystemType};

// Create K-14 meter (mastering standard)
let mut k_meter = KSystemMeter::new(
    KSystemType::K14,
    48000.0,
    2
).expect("Failed to create K-meter");

k_meter.process_interleaved(audio_samples);

// Get levels relative to K-14 reference
let rms_levels = k_meter.rms_relative_db();
println!("RMS relative to K-14: L={:.1} dB, R={:.1} dB",
         rms_levels[0], rms_levels[1]);

if k_meter.is_overload() {
    println!("Warning: Headroom exceeded!");
}

§Phase Analysis

use oximedia_metering::{PhaseCorrelationMeter, StereoWidthAnalyzer};

// Create phase correlation meter
let mut phase_meter = PhaseCorrelationMeter::new(48000.0, 0.4)
    .expect("Failed to create phase meter");

phase_meter.process_interleaved(audio_samples);

let correlation = phase_meter.correlation();
println!("Phase correlation: {:.2}", correlation);

if phase_meter.has_phase_issues() {
    println!("Warning: Phase cancellation detected!");
}

// Stereo width analysis
let mut width_analyzer = StereoWidthAnalyzer::new(48000.0)
    .expect("Failed to create width analyzer");

width_analyzer.process_interleaved(audio_samples);
println!("Stereo width: {:.0}%", width_analyzer.width_percentage());

§Spectrum Analysis

use oximedia_metering::{SpectrumAnalyzer, WindowFunction, WeightingCurve};

// Create FFT-based spectrum analyzer
let mut spectrum = SpectrumAnalyzer::new(
    48000.0,
    2048,
    WindowFunction::Hann,
    WeightingCurve::A,
    1.0  // 1 second peak hold
).expect("Failed to create spectrum analyzer");

spectrum.process(audio_samples);

let spectrum_db = spectrum.spectrum_db();
for (i, &magnitude) in spectrum_db.iter().take(10).enumerate() {
    let freq = spectrum.bin_frequency(i);
    println!("{:.0} Hz: {:.1} dB", freq, magnitude);
}

§Video Metering

use oximedia_metering::{LuminanceMeter, GamutMeter, ColorGamut, QualityAnalyzer, Frame2D};

// Luminance metering for HDR content
let mut lum_meter = LuminanceMeter::new(1920, 1080, 1000.0, 256)
    .expect("Failed to create luminance meter");

lum_meter.process(&luminance_frame)?;

println!("Peak: {:.1} nits", lum_meter.peak_nits());
println!("Average: {:.1} nits", lum_meter.average_nits());
println!("Dynamic range: {:.1} stops", lum_meter.dynamic_range_stops());

if lum_meter.is_hdr10() {
    println!("HDR10 content detected");
}

// Color gamut analysis
let mut gamut_meter = GamutMeter::new(1920, 1080, ColorGamut::Rec2020)
    .expect("Failed to create gamut meter");

gamut_meter.process(&r_channel, &g_channel, &b_channel)?;

println!("Rec.2020 coverage: {:.1}%", gamut_meter.gamut_coverage_percentage());
println!("Max saturation: {:.2}", gamut_meter.max_saturation());

// Video quality metrics (PSNR, SSIM)
let quality = QualityAnalyzer::new(1920, 1080, 1.0)
    .expect("Failed to create quality analyzer");

let metrics = quality.analyze(&reference_frame, &distorted_frame)?;

println!("PSNR: {:.2} dB", metrics.psnr);
println!("SSIM: {:.4}", metrics.ssim);
println!("Quality: {}", metrics.rating());

§Meter Rendering

use oximedia_metering::{BarMeterConfig, BarMeterData, ColorGradient, Orientation};

// Configure a vertical bar meter
let config = BarMeterConfig {
    orientation: Orientation::Vertical,
    width: 30,
    height: 200,
    min_value: -60.0,
    max_value: 0.0,
    gradient: ColorGradient::traffic_light(),
    show_peak_hold: true,
    show_scale: true,
    ..Default::default()
};

// Create meter data from dBFS values
let meter_data = BarMeterData::from_dbfs(
    -12.0,  // Current level
    -6.0,   // Peak hold
    -60.0,  // Min range
    0.0     // Max range
);

if meter_data.is_clipping {
    println!("Clipping detected!");
}

// Get color for current level
let color = config.gradient.color_at(meter_data.level);
println!("Meter color: RGB({}, {}, {})", color.r, color.g, color.b);

§Technical Implementation

§K-weighting Filter

The K-weighting filter chain implements ITU-R BS.1770-4 specification:

Stage 1: High-pass filter at 78.5 Hz (head diffraction modeling)
Stage 2: High-shelf filter for revised low-frequency B-weighting (RLB)

Both filters are implemented as second-order IIR biquad filters with precise coefficients calculated for the given sample rate.

§Block Processing

Audio is processed in overlapping blocks:

Block size: 100ms (400ms blocks for momentary, 3000ms for short-term)
Overlap: 75% (blocks advance by 25% of their duration)
Gating: Applied on 400ms blocks with absolute (-70 LKFS) and relative (-10 LU) gates

§True Peak Detection

Uses 4x oversampling with windowed sinc interpolation:

Lanczos-windowed sinc function (a=3)
Linear-phase FIR resampling
Per-sample peak tracking

§Performance

Real-time capable: Processes audio faster than real-time on modern CPUs
Memory efficient: Circular buffers for sliding windows
Zero-copy where possible: Processes interleaved or planar audio in-place when possible

§Standards References

ITU-R BS.1770-4 (10/2015): “Algorithms to measure audio programme loudness and true-peak audio level”
ITU-R BS.1771 (2006): “Requirements for loudness and true-peak indicating meters”
EBU R 128 (2020): “Loudness normalisation and permitted maximum level of audio signals”
ATSC A/85:2013: “Techniques for Establishing and Maintaining Audio Loudness for Digital Television”

Re-exports§

pub use correlation as correlation_meter;
pub use dynamics as dynamic_range_meter;
pub use peak as peak_meter;
pub use phase as phase_analysis;
pub use truepeak as true_peak;
pub use atsc::AtscA85Compliance;
pub use atsc::AtscA85Meter;
pub use ballistics::BallisticProcessor;
pub use ballistics::BallisticType;
pub use ballistics::MultiChannelBallistics;
pub use correlation::CorrelationMeter;
pub use correlation::FrequencyBand;
pub use correlation::Goniometer as CorrelationGoniometer;
pub use correlation::GoniometerPoint as CorrelationGoniometerPoint;
pub use correlation::MultibandMeter;
pub use correlation::PhaseRelationship;
pub use dynamics::DynamicRangeMeter;
pub use dynamics::PlrMeter;
pub use ebu::EbuR128Compliance;
pub use ebu::EbuR128Meter;
pub use filters::KWeightFilter;
pub use filters::KWeightFilterBank;
pub use gating::GatingProcessor;
pub use gating::GatingResult;
pub use lkfs::LkfsCalculator;
pub use lkfs::LufsValue;
pub use peak::dbfs_to_linear;
pub use peak::linear_to_dbfs;
pub use peak::KSystemMeter;
pub use peak::KSystemType;
pub use peak::PeakMeter;
pub use peak::PeakMeterType;
pub use phase::Goniometer;
pub use phase::GoniometerPoint;
pub use phase::PhaseCorrelationMeter;
pub use phase::StereoWidthAnalyzer;
pub use range::LoudnessRange;
pub use range::LraCalculator;
pub use render::colors;
pub use render::generate_db_scale;
pub use render::BarMeterConfig;
pub use render::BarMeterData;
pub use render::CircularMeterConfig;
pub use render::Color;
pub use render::ColorGradient;
pub use render::Orientation;
pub use render::ScaleMark;
pub use render::ScaleType;
pub use report::ComplianceReport;
pub use report::LoudnessReport;
pub use report::MeteringReport;
pub use spectrum::CachedSpectrumAnalyzer;
pub use spectrum::OctaveBand;
pub use spectrum::OctaveBandAnalyzer;
pub use spectrum::SpectrumAnalyzer;
pub use spectrum::WeightingCurve;
pub use spectrum::WindowFunction;
pub use truepeak::TruePeak;
pub use truepeak::TruePeakDetector;
pub use video_color::ColorGamut;
pub use video_color::ColorTemperatureMeter;
pub use video_color::GamutMeter;
pub use video_color::HsvColor;
pub use video_color::RgbColor;
pub use video_color::SaturationMeter;
pub use video_luminance::BlackWhiteLevelMeter;
pub use video_luminance::LuminanceMeter;
pub use video_quality::BlockinessDetector;
pub use video_quality::Frame2D;
pub use video_quality::PsnrCalculator;
pub use video_quality::QualityAnalyzer;
pub use video_quality::QualityMetrics;
pub use video_quality::SsimCalculator;

Modules§

atsc: ATSC A/85 loudness standard for digital television.
ballistics: Meter ballistics for realistic meter behavior.
bs2132: ITU-R BS.2132 loudness measurement for short-form content (<30 s).
bs2051_weights: ITU-R BS.2051 channel weights for immersive audio layouts.
clip_counter: Audio clip/overload event counting and tracking.
correlation: Stereo correlation and phase analysis for audio metering.
crest_factor: Crest factor meter for broadcast audio analysis.
dr_meter: Dynamic range metering: peak, RMS, crest factor, and DR scoring.
dynamics: Dynamic range measurement.
ebu: EBU R128 loudness normalization standard.
ebu_r128_impl: Comprehensive EBU R128 / ITU-R BS.1770-4 loudness metering implementation.
filters: K-weighting filters for ITU-R BS.1770-4 loudness measurement.
gating: Gating algorithm for integrated loudness measurement.
k_weight_simd: SIMD-accelerated K-weighting filter for ITU-R BS.1770-4 loudness.
k_weighted: K-weighted loudness level calculation for broadcast metering.
k_weighting: K-weighting filter implementation for ITU-R BS.1770-4 loudness measurement.
leq: Leq (Equivalent Continuous Sound Level) meter.
lkfs: LKFS/LUFS loudness calculation.
loudness_gate: Loudness gating for integrated loudness measurement (ITU-R BS.1770-4).
loudness_history: Loudness history tracking and trend analysis.
loudness_trend: Loudness trending over time windows.
m_s_meter: Mid/Side (M/S) metering for stereo audio.
meter_bridge: Meter bridge aggregation for broadcast metering.
meter_type_config: Meter type enumeration and per-type configuration sets.
ms_ssim: Multi-Scale SSIM (MS-SSIM) video quality metric.
noise_floor: Noise floor detection and measurement for audio signals.
octave_bands: Multi-band octave spectrum analysis.
peak: Peak and level meters.
phase: Phase and stereo analysis meters.
phase_scope: Phase/goniometer scope: Lissajous display data, phase angle, and correlation coefficient.
ppm: PPM (Peak Programme Meter) implementation.
range: Loudness Range (LRA) calculation.
render: Meter rendering and visualization.
report: Comprehensive metering reports and compliance documentation.
rms_envelope: RMS envelope follower with configurable time constants.
silence_detect: Silence detection and dead-air monitoring for broadcast audio.
spectral_balance: Spectral balance metering: frequency band energy, tilt measurement, warmth/brightness.
spectral_energy: Spectral energy balance metering: frequency-band energy analysis and deviation measurement against a target balance curve.
spectrum: Spectrum analyzers and frequency analysis.
spectrum_bands: Spectrum analyzer metering with octave and 1/3-octave band analysis.
stereo_balance: Stereo balance and panning analysis for audio metering.
temporal_noise: Temporal noise measurement for video frames.
true_peak_meter: True peak metering with 4x oversampling via cubic interpolation.
truepeak: True peak detection using 4x oversampling.
video_color: Video color metering.
video_luminance: Video luminance metering.
video_quality: Video quality metrics.
vmaf_estimate: VMAF score estimator — pure Rust feature extraction.
vmaf_features: VMAF-inspired feature extractor (pure signal analysis, no ML).
vu_meter: VU meter with analogue-style ballistics.

Structs§

ComplianceResult: Compliance result.
LoudnessMeter: Main loudness meter.
LoudnessMetrics: Loudness measurement metrics.
MeterConfig: Meter configuration.

Enums§

ChannelLayout: Channel configuration for multi-channel audio.
MeteringError: Metering error types.
Standard: Broadcast loudness standard.

Type Aliases§

MeteringResult: Metering result type.