How to Use FFmpeg vidstabtransform to Stabilize Video

This guide provides a straightforward tutorial on stabilizing shaky footage using the vidstabtransform filter in FFmpeg. You will learn the required two-pass workflow—first generating camera motion vectors with vidstabdetect and then transforming the frames with vidstabtransform—along with optimal command examples and key settings to fine-tune your results.

The Two-Step Stabilization Process

Video stabilization with the vid.stab library in FFmpeg cannot be done in a single isolated step because the software must first analyze the entire video to map camera movement before applying corrections.

Analysis Pass (vidstabdetect): Scans the input video, calculates camera shake, and writes translation and rotation data to a file (typically named transforms.trf).
Transformation Pass (vidstabtransform): Reads the generated .trf file, applies corrective transformations to counteract the motion, and outputs the stabilized video.

Step 1: Generate the Motion Analysis File

Before running vidstabtransform, run the vidstabdetect filter to create the transform file.

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

shakiness=8: Sets how shaky the original video is on a scale from 1 (mild) to 10 (extreme).
accuracy=15: Determines the precision of the analysis (1 to 15, where 15 is highest precision).
stepsize=6: The step size of the search grid. Lower values are slower but more accurate.
result="transforms.trf": The path where the motion vector data will be saved.
-f null -: Discards the visual output to speed up the analysis phase.

Step 2: Apply the Stabilization with `vidstabtransform`

Once transforms.trf is generated, run the second pass using the vidstabtransform filter to produce the final, stabilized video.

ffmpeg -i input.mp4 -vf vidstabtransform=input="transforms.trf":smoothing=30:zoom=5:optzoom=1 -c:a copy output.mp4

input="transforms.trf": Specifies the motion data file created in Step 1.
smoothing=30: Number of frames used for smoothing camera movement. Higher values result in smoother, slower camera panning; lower values preserve quick, deliberate pans.
optzoom=1: Automatically determines the optimal zoom level to hide the black borders caused by shifting frames.
zoom=5: Adds an additional percentage of digital zoom (0 to 5%) to crop out residual border artifacts.
-c:a copy: Copies the audio stream without re-encoding to preserve quality and save processing time.

Advanced Settings for `vidstabtransform`

You can customize the filter further depending on your footage requirements:

Tripod Mode (tripod=1): Simulates a stationary camera mounted on a tripod. Useful for shots where the camera was intended to be completely still.
```
vidstabtransform=input="transforms.trf":tripod=1
```
Interpolation (interpol=bicubic): Sets the image interpolation method used during pixel shifting. Options include no (nearest neighbor), linear, bicubic (default), or bilinear.
Border Handling (crop=black vs crop=keep): Determines how edges are handled if zoom does not cover empty areas. Setting crop=black fills edges with black borders, while crop=keep stretches or retains pixel edges.

Full Combined Script

To execute both passes consecutively in a single command chain:

ffmpeg -i input.mp4 -vf vidstabdetect=shakiness=7:result="transforms.trf" -f null - && \
ffmpeg -i input.mp4 -vf vidstabtransform=input="transforms.trf":smoothing=25:optzoom=1 -c:v libx264 -crf 18 -c:a copy output_stabilized.mp4 && \
rm transforms.trf

This sequence generates the motion data, applies the vidstabtransform filter using visually lossless H.264 encoding (-crf 18), and cleans up the temporary .trf file upon completion.