Export SSIM Scores to a Log File Using FFmpeg

This guide explains how to calculate the Structural Similarity Index (SSIM) between a reference video and a modified video using FFmpeg, exporting both frame-level measurements and global average scores into a log file. By using FFmpeg's native ssim filter alongside standard command-line redirection, you can generate detailed visual quality metrics for automated testing and archival.

The Command

To run the SSIM comparison, write the per-frame scores to a dedicated text file, and capture the global average score, run the following command in your terminal:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "ssim=stats_file=ssim_frames.log" -f null - 2> ssim_global.log

If you want both the per-frame scores and the global output captured in a single command pipeline, you can redirect the process output while generating the frame log:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "ssim=stats_file=ssim_frames.log" -f null - 2>&1 | tee ssim_summary.log

Parameter Breakdown

  • -i distorted.mp4 -i reference.mp4: Specifies the two video files being compared. Ensure both inputs have identical resolutions and frame rates, or apply scaling filters before comparison.
  • -lavfi "ssim=stats_file=ssim_frames.log": Invokes the ssim filter. The stats_file parameter tells FFmpeg to write frame-by-frame SSIM scores directly to ssim_frames.log.
  • -f null -: Discards the decoded video output instead of re-encoding or saving it, ensuring the test runs as fast as possible without wasting disk space.
  • 2> ssim_global.log: Redirects the standard error (stderr) stream to a file. FFmpeg prints operational statistics and the final global SSIM score to stderr upon completion.

Reading the Frame-Level Log

Open ssim_frames.log in any text editor. Each line corresponds to an evaluated video frame and follows this format:

n:1 Y:0.982145 U:0.991204 V:0.990812 All:0.985432 (18.365412)
n:2 Y:0.978921 U:0.989943 V:0.988710 All:0.982109 (17.473521)
  • n: The frame index number (starting at 1).
  • Y, U, V: The SSIM score for the luma and chroma channels separately (ranging from -1.0 to 1.0, where 1.0 indicates an exact match).
  • All: The combined SSIM score across all channels for that specific frame.
  • (dB): The SSIM score expressed in decibels inside the parentheses.

Extracting the Global Score

FFmpeg outputs the final average score at the end of the process. In ssim_global.log (or your terminal output), locate the final Parsed_ssim_0 summary line:

[Parsed_ssim_0 @ 0x7f9a8b404d80] SSIM Y:0.974211 (15.885142) U:0.988412 (19.360124) V:0.987510 (19.034190) All:0.978912 (16.759410)

The value following All: represents the global SSIM score across the entire duration of the video.