How to Use vidstabdetect in FFmpeg for Camera Shake

This guide explains how to use the vidstabdetect filter in FFmpeg to analyze camera shake and generate motion stabilization data. Stabilizing video with FFmpeg is a two-pass process powered by the libvidstab library, where vidstabdetect performs the first pass by tracking feature points across frames and saving the motion vectors to a transforms file. Below, you will find the necessary prerequisites, the core command syntax, explanations of key parameters, and instructions for generating an accurate analysis file.

Prerequisites

To use vidstabdetect, your FFmpeg build must be compiled with the libvidstab library enabled. You can verify this by running ffmpeg -filters in your terminal and checking if vidstabdetect and vidstabtransform appear in the output list. If they are missing, you will need to install an FFmpeg build configured with --enable-libvidstab.

The Basic Detection Command

The vidstabdetect filter evaluates video frames to detect motion paths and exports this data to a text file (typically named transforms.trf). Because this pass only generates metadata and does not render a final video, you can discard the video output using the null muxer to maximize processing speed.

Run the following command in your terminal:

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

Key Parameters for vidstabdetect

You can fine-tune the analysis by appending options to the filter, separated by colons:

  • result: Specifies the path and filename where the motion vectors will be stored. The default value is transforms.trf.
  • shakiness: Sets how shaky the original video is on a scale from 1 (very little shake) to 10 (extremely shaky). The default is 5. Higher values cause the filter to search for larger shifts between frames.
  • accuracy: Defines the precision of the motion search on a scale from 1 (lowest/fastest) to 15 (highest/slowest). The default is 15. A setting of 9 to 15 is recommended for high-quality tracking.
  • stepsize: Controls the distance (in pixels) between analyzed points on the grid. A smaller step size checks more points, yielding higher tracking accuracy at the cost of speed. Common values range from 16 to 64, with 32 being the default.
  • mincontrast: A floating-point value between 0.0 and 1.0 that defines the minimum contrast required for a point to be tracked. The default is 0.25. If your video has low lighting or flat colors, reducing this value can help the filter find more tracking points.
  • show: When set to 1 or 2, draws the tracked feature points and camera transformations directly onto the frames, which is useful for debugging. The default is 0 (disabled).

Using the Output File

Once the analysis command completes, FFmpeg will have written the motion vector data into the specified transforms.trf file. You can then run the second pass using the vidstabtransform filter, which reads this .trf file to crop, shift, and smooth the frames, producing the final stabilized video:

ffmpeg -i input.mp4 -vf vidstabtransform=input="transforms.trf":smoothing=10 output_stabilized.mp4