How to Use FFmpeg ebur128 for Loudness Telemetry

This article provides a practical guide on how to use the ebur128 filter in FFmpeg to analyze audio loudness and output telemetry data. You will learn the basic commands for scanning audio files, how to interpret the console output metrics (such as momentary, short-term, and integrated loudness), and how to generate real-time visual telemetry graphs.

The Basic Loudness Analysis Command

To analyze the loudness of an audio or video file without rendering a new media file, use the ebur128 audio filter and direct the output to the null muxer (-f null). This tells FFmpeg to process the file and print the telemetry results to the console.

Run the following command in your terminal:

ffmpeg -i input.mp4 -af ebur128=peak=true -f null -

Parameter Breakdown:

• -i input.mp4: Specifies your input source file.
• -af ebur128=peak=true: Applies the EBU R128 audio filter. Setting peak=true includes True Peak (TP) measurements in the analysis, which is critical for checking if your audio clipping thresholds are exceeded.
• -f null -: Decodes the audio and runs the analysis without writing an output media file, ensuring the process runs as fast as possible.

Understanding the Console Telemetry Output

While the command runs, FFmpeg outputs real-time telemetry frames in the console. At the very end of the process, it prints a summary of the entire file.

Real-Time Frame Telemetry

During playback or processing, you will see repeating blocks of telemetry data that look like this:

t: 2.40003    M: -21.2 S: -20.5     I: -18.2 LRA:   3.2

• t: The current timestamp in seconds.
• M (Momentary): Loudness over a 400ms window. This shows immediate volume spikes.
• S (Short-term): Loudness over a 3-second window. This is useful for monitoring ongoing phrases or sound effects.
• I (Integrated): The cumulative loudness from the start of the file to the current timestamp.
• LRA (Loudness Range): The statistical distribution of loudness, measuring the dynamic range of the audio.

Final Summary Telemetry

Once the analysis completes, FFmpeg outputs the final statistics for the entire asset:

Summary:

  Integrated loudness:
    I:         -23.0 LUFS
    Threshold: -33.0 LUFS

  Loudness range:
    LRA:         5.4 LU
    Threshold: -43.0 LUFS
    LRA low:   -26.1 LUFS
    LRA high:  -20.7 LUFS

  True peak:
    Peak:       -1.2 dBTP

• Integrated Loudness (I): The overall target loudness of your file. For broadcast standards like EBU R128, the target is usually -23.0 LUFS (or -24.0 LUFS for ATSC A/85).
• Loudness Range (LRA): Measured in Loudness Units (LU), this represents the dynamic range.
• True Peak (Peak): Measured in Decibels True Peak (dBTP). This value should ideally stay below -1.0 dBTP to prevent distortion during digital-to-analog conversion.

Generating Visual Loudness Telemetry

The ebur128 filter can also generate a real-time visual graph of the loudness telemetry. Because this outputs both audio and video, you must use filter_complex to route the streams.

To render a video file showing the loudness graph alongside the original audio, use this command:

ffmpeg -i input.mp4 -filter_complex "[0:a]ebur128=video=1:meter=18[outy][outa]" -map "[outy]" -map "[outa]" -c:v libx264 -c:a aac output.mp4

Parameter Breakdown:

• video=1: Enables the video output component of the ebur128 filter.
• meter=18: Sets the scale of the visualization meter (typically 9 or 18 LU).
• [outy][outa]: Separates the generated video graph (outy) and the original audio stream (outa).
• -map "[outy]" -map "[outa]": Maps these processed streams to the final output file (output.mp4).

Saving Telemetry Logs to a File

If you need to store the text-based telemetry data for automated analysis or compliance logging, redirect the standard error output (stderr) of FFmpeg to a text file:

ffmpeg -i input.mp4 -af ebur128=peak=true -f null - 2> loudness_log.txt

This creates loudness_log.txt in your current directory, containing the complete, frame-by-frame loudness telemetry log for future parsing.