How to Analyze Camera Shake with FFmpeg vidstabdetect

This article explains how to use the vidstabdetect filter in FFmpeg to analyze camera shake in a video. You will learn the exact commands required to run the detection pass, understand what the configuration parameters do, and see how to generate the motion data file necessary for the stabilization process.

Understanding the Two-Step Stabilization Process

Stabilizing a video in FFmpeg using the vid.stab library is a two-step process:

  1. Analysis (vidstabdetect): FFmpeg analyzes the video frames to detect positional shifts, rotations, and camera shake, saving this tracking data to a file (usually named transforms.trf).
  2. Stabilization (vidstabtransform): FFmpeg reads the tracking data from the first step and applies a transform filter to create a stabilized output video.

Using vidstabdetect is the essential first step that performs the heavy computational work of motion analysis.

The Basic vidstabdetect Command

To analyze a video without wasting time rendering a dummy output video file, you can direct the output to a null muxer (-f null -). Run the following command in your terminal:

ffmpeg -i input.mp4 -vf vidstabdetect=result=transforms.trf -f null -

Command Breakdown:

  • -i input.mp4: Specifies your shaky source video.
  • -vf vidstabdetect: Activates the motion detection video filter.
  • result=transforms.trf: Tells FFmpeg to write the analyzed motion data to a file named transforms.trf.
  • -f null -: Runs the command and discards the video output, as we only need the generated .trf file from this step.

Fine-Tuning the Detection Parameters

You can customize vidstabdetect using several key-value parameters separated by colons. Here is an advanced configuration example:

ffmpeg -i input.mp4 -vf vidstabdetect=shakiness=5:accuracy=15:stepsize=6:result=transforms.trf -f null -

Parameter Explanations:

  • shakiness (1 to 10): Represents how shaky the original video is. A value of 1 means little to no shake, while 10 represents extreme, rapid camera movement. The default is 5.
  • accuracy (1 to 15): Determines the accuracy of the detection process. Higher numbers yield better results but require more processing time. The default is 15.
  • stepsize (1 to 32): Sets the step size of the search process in pixels. Smaller step sizes are more precise but slower. The default is 6.
  • show (0 or 1): If set to 1, FFmpeg will output a visual representation of the detected motion vectors overlaid on top of your video. This is useful for debugging.

Next Steps: Applying the Stabilization

Once the analysis is complete, you will find a new file named transforms.trf in your working directory. You can now use this file to stabilize your video using the vidstabtransform filter with the following command:

ffmpeg -i input.mp4 -vf vidstabtransform=input=transforms.trf:interpol=linear -c:v libx264 -crf 18 -c:a copy stabilized_output.mp4