How to Calculate SSIM with FFmpeg

This article explains how to use the FFmpeg ssim filter to measure the Structural Similarity Index (SSIM) between two videos. You will learn the basic command-line syntax for comparing a compressed video against its original source, how to export these metrics to a log file, and how to interpret the resulting SSIM scores to evaluate video quality.

The Basic SSIM Command

To calculate the SSIM, FFmpeg requires two inputs: the modified (compressed) video and the original (reference) video. The ssim filter compares the two video streams frame by frame.

Run the following command in your terminal:

ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]ssim" -f null -

Command breakdown: * -i distorted.mp4: The first input (index 0), which is typically the video you want to test. * -i reference.mp4: The second input (index 1), which is the high-quality original video. * -filter_complex "[0:v][1:v]ssim": Takes the video track of the first input [0:v] and the video track of the second input [1:v] and passes them to the ssim filter. * -f null -: Tells FFmpeg not to write an output video file, as we only need the text output in the console.

Saving SSIM Results to a Log File

If you want to analyze the SSIM score of every single frame, you can instruct the filter to write the results to a external log file using the stats_file option:

ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]ssim=stats_file=ssim_report.txt" -f null -

This command creates a file named ssim_report.txt in your current directory containing the frame number and the specific SSIM values for the Y, U, and V color channels.

Understanding the Output

Once the analysis is complete, FFmpeg will print a summary line in the terminal that looks similar to this:

[Parsed_ssim_0 @ 0x55bc8f12a300] SSIM Y:0.982341 U:0.991204 V:0.990451 All:0.984512 (18.100231)

Y, U, V: These represent the SSIM values for the Luminance (Y) and Chrominance (U/V) channels.
All: This is the global average SSIM score across all channels combined.
Scale: SSIM values range from 0 to 1. A score of 1.0 means the two videos are mathematically identical.
dB Value (in parentheses): The number in parentheses is the SSIM expressed on a logarithmic decibel scale (higher is better).

Crucial Requirement: Matching Dimensions and Frame Rates

The ssim filter compares videos pixel-by-pixel. Therefore, both input videos must have the exact same resolution and frame rate.

If your compressed video has a different resolution than the original, you must scale it first within the filtergraph. For example, to upscale a 1280x720 distorted video to match a 1920x1080 reference video:

ffmpeg -i distorted_720p.mp4 -i reference_1080p.mp4 -filter_complex "[0:v]scale=1920:1080[distorted_scaled];[distorted_scaled][1:v]ssim" -f null -