Skip to main content

Checking Loudness Compliance

Use the audio layer to check if a file meets a loudness standard, such as EBU R 128 in Europe or ATSC A/85 in the US. For example, you can check a programme before playout, a file delivered by a partner, or a recording of a broadcast channel. For AC-3 and E-AC-3 audio, the toolkit also checks if the dialnorm value in the stream matches the measured loudness.

The measurement follows ITU-R BS.1770 and EBU R 128 (with EBU Tech 3341 and 3342). It gives the momentary, short-term and integrated loudness, the loudness range (LRA) and the true peak of every audio stream. It was checked against the EBU Tech 3341 and 3342 test signals. See Metrics for the details.

Note

While we have tested the loudness measurement against the EBU Tech 3341 and 3342 test signals, we cannot guarantee that it will give the same results as other loudness meters, and that the toolkit can be used for official compliance checks.

Checking a file​

The audio layer is on by default, so a normal analyze run already measures the loudness of every audio stream. If you only need the audio, use --layers audio. This is much faster, because the video is not decoded:

surfmeter-media analyze --layers audio -o results/programme programme.ts

By default, each audio stream is checked against two targets: ebu-r128 and atsc-a85. The result is in summary.json, under loudness of each input. This command shows the most important values of each stream, and the result of each target:

jq '.inputs[].loudness[] | {stream, codec, integrated, lra, true_peak, dialnorm,
dialnorm_difference, targets: [.targets[] | {name, deviation, ok}]}' \
results/programme/summary.json
{
"stream": 1,
"codec": "ac3",
"integrated": -23.994,
"lra": 0.0,
"true_peak": -23.999,
"dialnorm": -24,
"dialnorm_difference": 0.006,
"targets": [
{"name": "ebu_r128", "deviation": -1.0, "ok": false},
{"name": "atsc_a85", "deviation": 0.0, "ok": true}
]
}

This stream is at -24.0 LKFS, with a dialnorm of -24 dB. It meets ATSC A/85 (-24 LKFS ±2 dB). It does not meet EBU R 128, because it is 1.0 LU below -23 LUFS, and ebu-r128 allows only ±0.2 LU.

deviation is the integrated loudness minus the target level, in LU. A negative value means the stream is too quiet, a positive value means it is too loud. ok is true only when all checks of the target pass. To see which check failed, read loudness_ok, true_peak_ok and dialnorm_ok.

Choosing the targets​

Select the targets with --loudness-target. You can give the option several times. When you set it, it replaces the default targets:

# Only EBU R 128 with the tolerance for live programmes
surfmeter-media analyze --layers audio --loudness-target ebu-r128-live -o results channel1.ts

# EBU R 128 and a custom target for streaming: -16 LUFS, ±1 LU, true peak at most -1 dBTP
surfmeter-media analyze --layers audio \
--loudness-target ebu-r128 --loudness-target -16:1:-1 \
-o results episode.mp4

A custom target has the form LEVEL:TOLERANCE:MAX_TRUE_PEAK. Its name in the output is custom (and custom_2, custom_3 and so on if you give more than one). See Basic Usage for the list of presets.

Checking dialnorm​

AC-3 and E-AC-3 streams carry a dialnorm value (dialogue normalization, from -1 to -31 dB). The receiver uses it to set the playback level. ATSC A/85 requires dialnorm to match the loudness of the content. If it does not match, viewers hear a jump in volume when the programme changes.

The atsc-a85 target checks two things:

  • The integrated loudness is within -24 ±2 LKFS (loudness_ok).
  • The dialnorm matches the integrated loudness within ±2 dB (dialnorm_ok). dialnorm_difference gives the integrated loudness minus the dialnorm.

Both checks must pass for ok to be true. Here are two examples:

  • A stream at -24.0 LKFS with a dialnorm of -27 dB has a difference of +3.0 dB. dialnorm_ok is false, so the stream fails.
  • A stream at -27.0 LKFS with a dialnorm of -27 dB has a correct dialnorm (dialnorm_ok is true). It still fails, because the loudness is outside -24 ±2 LKFS (loudness_ok is false).

If your service uses a different dialnorm on purpose, read dialnorm_ok and dialnorm_difference instead of ok.

Here is a stream with a wrong dialnorm. The audio is at -20 LKFS, but the dialnorm says -27 dB:

jq -c '.inputs[].loudness[] | {integrated, dialnorm, dialnorm_difference,
a85: (.targets[] | select(.name == "atsc_a85") | {loudness_ok, dialnorm_ok, ok})}' \
results/channel1/summary.json
{"integrated":-19.994,"dialnorm":-27,"dialnorm_difference":7.006,"a85":{"loudness_ok":false,"dialnorm_ok":false,"ok":false}}

Dialnorm changes​

When the dialnorm changes in the stream, the toolkit writes an audio_metadata record and a dialnorm_change event at the time of the change. The summary gives the dialnorm that was used for the longest time (dialnorm), the lowest and highest values (dialnorm_min, dialnorm_max) and the number of changes (dialnorm_changes). To list the changes:

jq -c 'select(.type == "audio_event" and .kind == "dialnorm_change") | {stream, start, message}' \
results/channel1/records.ndjson
{"stream":1,"start":11.496,"message":"dialnorm changes from -27 dB to -24 dB"}

The integrated loudness covers the whole stream. If the dialnorm changes between programmes, check each programme on its own: cut the file into programmes, or use --duration to measure only the start.

You can also see the dialnorm without a full analysis. probe shows the dialnorm, bitstream mode and channel mode of the first frame of each AC-3 and E-AC-3 stream, and writes them as an audio_metadata record:

surfmeter-media probe channel1.ts | jq -c 'select(.type == "audio_metadata")'
{"schema_version":"0.1.9","type":"audio_metadata","input":"0","stream":1,"program":1,"pid":257,"pts":1.474667,"codec":"ac3","dialnorm":-31,"bsid":8,"bsmod":0,"acmod":7,"lfe":true,"sample_rate":48000,"bitrate":448000,"frame_size":1792,"channel_layout":"5.1(side)"}

Finding problems in time​

Besides the totals, the toolkit reports audio events:

  • silence: a channel stays below -60 dBFS for 2 seconds or longer
  • clipping: 3 or more samples in a row at full scale
  • true_peak_over: the true peak is above the maximum of a target
  • dialnorm_change: the dialnorm changes

summary.json counts the events of each kind under events. To list them with their times:

jq -c 'select(.type == "audio_event") | {stream, kind, start, end, channel, message}' \
results/channel1/records.ndjson

To see the loudness over time, open the results in the terminal view. It shows the loudness as a track on the timeline, the events as markers, and an audio panel with meters and the result of each target. See Reviewing Saved Results.

surfmeter-media view results/channel1/records.ndjson

Files with several audio streams​

By default, all audio streams are measured. A transport stream may have, for example, a stereo stream and a 5.1 stream, or streams in several languages. To measure only some of them, give their stream indexes as probe shows them:

surfmeter-media analyze --layers audio --audio-streams 1,3 -o results channel1.ts

Each stream gets its own records and its own loudness_summary. The stream field tells you which stream a record belongs to, and language gives the language, if the file has one.

Audio-only files​

The toolkit also measures files without video, for example WAV files, raw .ac3 and .eac3 files, and MP4 or Matroska files with only audio. For these files, only the audio layer runs:

surfmeter-media analyze -o results/mix final-mix.wav

Checking many files in a script​

loudness_summary.csv has one row per stream and one column per target field, for example targets.ebu_r128.ok or targets.atsc_a85.dialnorm_ok. This makes it easy to check a batch of files in a spreadsheet:

surfmeter-media analyze --layers audio -o results/batch --format ndjson,json,csv recordings/*.ts

In a script, you can fail when a stream does not meet a target. This example stops with an error if any stream fails EBU R 128:

surfmeter-media analyze -q --layers audio --loudness-target ebu-r128 -o "$out" "$file"

status=$(jq -r '.run_info.status' "$out/summary.json")
if [ "$status" != "completed" ]; then
echo "Audio analysis did not complete: $status" >&2
exit 2
fi

streams=$(jq '[.inputs[].loudness[]?] | length' "$out/summary.json")
if [ "$streams" -eq 0 ]; then
echo "No audio streams were measured" >&2
exit 2
fi

failed=$(jq '[.inputs[].loudness[]? | select(any(.targets[]; .ok == false))] | length' \
"$out/summary.json")
if [ "$failed" -gt 0 ]; then
echo "Loudness check failed for $failed stream(s)" >&2
exit 1
fi

See Automating Quality Checks for more about scripts and CI jobs.

Limits​

  • The audio is measured as it is decoded: without dynamic range control (as A/85 requires), without downmix and without resampling. The LFE channel does not count towards the loudness, as in BS.1770.
  • A mono stream counts once, as BS.1770 says. Played on two loudspeakers, it sounds 3 dB louder.
  • For E-AC-3 streams with several programs (independent substreams), only program 0 is measured. The toolkit shows a warning.
  • Lost or damaged audio packets count as silence, and the toolkit shows a warning with the number of decoding errors. Damaged MPEG audio can decode to loud noise, which makes the measured loudness too high. The warning tells you when this can happen.
  • The targets are checked on the integrated loudness of the whole stream. There is no event yet for parts of the stream that are too loud or too quiet.
  • The short-term loudness limit of EBU R 128 s1 for short content, such as adverts, is not checked.
  • The audio layer needs a tool bundle of a release that includes it. With an older bundle, the toolkit turns off the layer and shows one warning.