How to Calculate Video SSIM Using FFmpeg

The Structural Similarity Index Measure (SSIM) is a widely used metric for quantifying the visual quality degradation between an original reference video and a compressed or processed version. FFmpeg includes a built-in ssim filter that compares two input video streams frame-by-frame and calculates quality scores for individual color components as well as an overall average. This guide demonstrates how to run basic SSIM comparisons, save the output metrics to a file, and normalize mismatched video streams for accurate measurement.

Prerequisites

To calculate SSIM accurately, both videos must share the same resolution and frame rate. The calculation requires two inputs: the distorted (compressed) video and the original reference video.

Basic SSIM Calculation

Run the following command in your terminal to calculate the overall SSIM score between two matched videos:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "ssim" -f null -

In this command:

  • -i distorted.mp4 specifies the first input (stream [0:v]).
  • -i reference.mp4 specifies the second input (stream [1:v]).
  • -lavfi "ssim" invokes the libavfilter SSIM filter to compare the two streams.
  • -f null - discards the video output, as only the calculated metrics in the console are needed.

Once processing finishes, FFmpeg displays a summary line similar to:

SSIM Y:0.965412 U:0.982145 V:0.981054 All:0.971201 (15.405912)
  • Y, U, V: The average SSIM score for the luminance (Y) and chrominance (U, V) channels.
  • All: The combined weighted SSIM score across all channels. Values range from 0 to 1, where 1 indicates identical visual quality.
  • The number in parentheses represents the score converted to decibels (dB).

Saving SSIM Stats to a Log File

To analyze frame-by-frame metrics or plot graphs over time, save the output to a text log using the stats_file parameter:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "ssim=stats_file=ssim_report.log" -f null -

The generated ssim_report.log records each frame number alongside its individual Y, U, V, and overall SSIM scores.

Handling Different Resolutions

If the compressed video was downscaled during encoding, it must be scaled back to the reference resolution before comparison:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "[0:v][1:v]scale2ref[dist][ref];[dist][ref]ssim" -f null -

Here, the scale2ref filter scales the first input ([0:v]) to match the dimensions of the reference input ([1:v]) before passing both streams directly into the ssim filter.