audio-metrics

Audio Metrics Reference

Objective definitions of the audio metrics ffmpeg computes. Each entry states what the metric measures, how ffmpeg computes it, its units, scale, and source filter. Definitions only: no perceptual interpretation, no quality judgement, no threshold-to-meaning mapping.

Verified against FFmpeg filter docs (https://ffmpeg.org/ffmpeg-filters.html) and source on release/8.1 and master (libavfilter/af_aspectralstats.c, af_astats.c, af_loudnorm.c, doc/filters.texi). Where the fact-sheet flagged a derivation as medium-confidence, this skill marks it Confidence: medium.

aspectralstats - per-frame spectral statistics

Statistics run over the half-spectrum magnitude array magnitude[n] = hypotf(re, im) of length size = win_size/2; FFT output is pre-scaled by 1/win_size; scale = max_freq/size with max_freq = sample_rate/2. Metadata keys emit per channel as lavfi.aspectralstats.<N>.<key>.

Source notes:

• entropy: ffmpeg applies ln to raw magnitudes (not a normalised PMF) and divides by ln(size); the result is not a conventional normalised Shannon entropy and is not bounded to [0,1].
• slope/decrease: docs are terse; the exact normalisation (m = size*0.5, normalised index) is taken from source.
• Division-by-zero guards return 1.f (centroid, spread, skewness, kurtosis, entropy) or 0.f (flatness, crest, slope, decrease).

astats - time-domain level statistics

Samples are normalised to [-1, 1]; LINEAR_TO_DB(x) = 20*log10(x). Metadata key lavfi.astats.<N>.<Key>. The length option (default 0.05 s) sets the short window for Noise_floor, RMS_peak, and RMS_trough.

Source quirk (low impact): per-channel metadata Crest_factor numerator uses raw min/max while the console-log path uses normalised nmin/nmax; they agree for float/double formats. Both paths are peak/RMS linear ratios, never dB.

ebur128 - loudness

Logged values are labelled M, S, I, LRA, TPK/FTPK. Read-only metadata exports integrated, range, lra_low, lra_high, true_peak. Loudness uses K-weighting plus mean-square per ITU-R BS.1770; true peak uses libswresample oversampling.

Gating (BS.1770-2 onward, adopted by EBU R128 / Tech 3341): absolute gate -70 LUFS, then a relative gate -10 LU below the absolute-gated mean. (From the named standards, not the ffmpeg docs.)

loudnorm - EBU R128 normalisation (FFmpeg 8.1)

JSON stats print at filter teardown when print_format=json. Two measurement states: r128_in (raw input) and r128_out (post-processing output). Output is exactly these 10 keys; no gain/offset field exists in 8.1 (any blog or master claim of extra fields does not apply). 8.1 is byte-identical to master for options, struct, JSON, and decision regions.

loudnorm default targets and valid option ranges (AVOption table, 8.1; {default}, min, max):

• I / i: -24.0, range -70.0 .. -5.0 (integrated loudness target, LUFS)
• LRA / lra: 7.0, range 1.0 .. 50.0 (loudness range target, LU)
• TP / tp: -2.0, range -9.0 .. 0.0 (max true peak, dBTP)
• linear: 1 (bool, default on) - linear normalisation attempted only if all four measured_* values are supplied
• dual_mono: 0; print_format: none|json|summary

Method: K-weighted loudness per ITU-R BS.1770 / EBU R128 via the bundled ebur128. Dynamic mode (default unless linear preconditions are met) applies a per-frame Gaussian-smoothed gain envelope plus a true-peak limiter and forces the input to 192000 Hz internally. Linear mode applies a single static gain offset to all samples. normalization_type reports which ran. loudnorm's reported *_tp is sample-peak; the standalone ebur128 filter's True Peak is oversampled.

Disambiguations

• Spectral crest vs crest factor: aspectralstats.crest = max(magnitude)/mean(magnitude) over the frequency-domain magnitude spectrum (per-frame spectral peakiness). astats Crest factor = peak_sample/RMS in the time domain. Different domains; both are linear dimensionless ratios >= 1, never dB. Do not conflate.
• Kurtosis baseline: aspectralstats.kurtosis is Pearson kurtosis (4th-power moment / Sum mag * spread^4). No -3 and no -0 subtraction. It is not excess kurtosis.
• Flatness scale: a 0-1 linear ratio (geometric mean / arithmetic mean of magnitudes), not dB. 1.0 = flat spectrum, toward 0 = peaky.
• Entropy scale/basis: -Sum(mag*ln(mag+eps)) / ln(N), natural log, normalised by ln(N) with N = bins. Magnitudes are raw (not a PMF), so this is not a conventional 0-1 normalised entropy and is not bounded to [0,1].
• Flux normalisation: L2 norm between consecutive frames, per-frame, not normalised by bin count or energy. The first frame compares against a zeroed previous frame.
• True-peak provenance: ebur128 True Peak is oversampled (per BS.1770 Annex 2). loudnorm *_tp is sample peak (20*log10(sample_peak)), not oversampled.

Standards and platform targets

External reference targets, not interpretation. Each row marks whether it is a formal standard or a platform norm.

Provenance: formal standards are ITU-R BS.1770, EBU R128, and ATSC A/85 (A/85 is legally enforced in the US via the CALM Act for commercials). Platform norms are Spotify, Apple (Podcasts and Music), YouTube, and ACX. AES TD1004/TD1008 is an AES technical document/recommendation, not a formal standard.

Standards URLs:

• ITU-R BS.1770: https://www.itu.int/rec/R-REC-BS.1770/en
• EBU R128: https://tech.ebu.ch/publications/r128 (PDF: https://tech.ebu.ch/docs/r/r128.pdf)
• EBU Tech 3341: https://tech.ebu.ch/publications/tech3341
• EBU Tech 3342: https://tech.ebu.ch/publications/tech3342
• ATSC A/85: https://www.atsc.org/.../A85-2013.pdf
• AES TD1004: https://aes.org/.../AESTD1004_1_15_10.pdf
• Spotify: https://support.spotify.com/us/artists/article/loudness-normalization/
• Apple Podcasts: https://podcasters.apple.com/support/893-audio-requirements
• ACX: https://help.acx.com/s/article/what-are-the-acx-audio-submission-requirements

Producing the metrics

Canonical ffmpeg invocations. -f null - discards output and keeps the filter's printed stats.

# Per-frame spectral statistics (aspectralstats)
ffmpeg -i in.wav -af aspectralstats -f null -

# Time-domain level statistics (astats)
ffmpeg -i in.wav -af astats -f null -

# Loudness: integrated, LRA, true peak, momentary, short-term (ebur128)
ffmpeg -i in.wav -af ebur128 -f null -

# Loudness measurement as machine-readable JSON (loudnorm, measurement pass)
ffmpeg -i in.wav -af loudnorm=print_format=json -f null -

To collect per-frame aspectralstats or astats metadata for downstream parsing, route the metadata to a log with ametadata:

ffmpeg -i in.wav -af aspectralstats,ametadata=mode=print:file=spectral.log -f null -
ffmpeg -i in.wav -af astats=metadata=1,ametadata=mode=print:file=levels.log -f null -

Spectrogram image (showspectrumpic): renders the signal as a 2-D image. The x axis is time, the y axis is frequency, and magnitude is mapped to colour. scale selects the magnitude mapping (lin, log, sqrt, cbrt); fscale selects the frequency-axis mapping (lin or log).

ffmpeg -i in.wav -lavfi showspectrumpic=s=1280x480:scale=log:fscale=log spectrogram.png