What You Will Learn

  • What the vidstabdetect and vidstabtransform filters do
  • The two-pass stabilization pipeline
  • Key parameters: shakiness, smoothing, crop (border handling), zoom and optzoom
  • How to install libvidstab so FFmpeg can use these filters
  • Limitations and when to consider other approaches

Target OS: Linux / macOS / Windows

Prerequisite: The vidstabdetect and vidstabtransform filters require FFmpeg to be built with --enable-libvidstab. Ubuntu / Debian’s apt install ffmpeg qualifies — measured on this site’s CI, see Installation. Check yours first with ffmpeg -filters | grep vidstab.

How Video Stabilization Works

FFmpeg’s video stabilization relies on the external libvidstab library and uses two filters:

  1. vidstabdetect — Pass 1: Analyzes the video for camera motion and writes a motion vectors file (default: transforms.trf).
  2. vidstabtransform — Pass 2: Reads the motion data and applies compensating transforms (translation, rotation) to smooth out shakes.

The two-pass approach is necessary because the filter needs to “see” the entire motion trajectory before it can compute a smooth camera path.

Basic Two-Pass Stabilization

Note: Every command in this section needs --enable-libvidstab. All of them are executed against Ubuntu’s stock apt install ffmpeg build on this site’s CI, so they are verified rather than merely illustrative.

Pass 1 — Motion detection:

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf vidstabdetect -f null /dev/null

This writes transforms.trf to the current directory.

Pass 2 — Stabilization:

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf vidstabtransform output.mp4

This reads transforms.trf and produces a stabilized video.

Tuning Stabilization Strength

Pass 1: shakiness

The shakiness parameter (1–10, default: 5) controls how aggressively the detector looks for motion. Increase it for very shaky footage:

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabdetect=shakiness=8:accuracy=15" -f null /dev/null
Parameter Range Default Description
shakiness 1–10 5 Motion range to detect
accuracy 1–15 15 Detection accuracy (higher = slower)
result path transforms.trf Output motion file

Pass 2: smoothing and crop

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabtransform=smoothing=30:crop=black" output.mp4
Parameter Default Description
smoothing 15 Temporal smoothing radius (frames). Higher = smoother but more black borders
crop keep Border handling: keep (fill the edge from the previous frame — the default) or black (fill with black)
zoom 0 Additional zoom percentage; positive zooms in, negative zooms out
optzoom 1 Automatic zoom: 0 = none, 1 = optimal static zoom (default), 2 = optimal dynamic zoom
interpol bilinear Interpolation method: no, linear, bilinear, bicubic

crop defaults to keep, not black. Omit it and the borders are filled from the previous frame (which looks like smearing), not painted black. Pass crop=black explicitly if you want black borders — every command in this article does. Confirm with ffmpeg -h filter=vidstabtransform, which prints (default keep).

Hiding Black Borders with Zoom

Stabilization shifts frames to compensate for camera movement, revealing black borders at the edges. Use zoom to scale up and hide them:

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabtransform=smoothing=20:zoom=5:crop=black" output.mp4

zoom=5 scales the output up by 5%, covering the black borders. The trade-off is a slight reduction in image area (crop-in effect).

Complete Pipeline with Custom Paths

For scripts or when processing multiple files, specify the motion file path explicitly:

# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabdetect=result=/tmp/transforms.trf" -f null /dev/null
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabtransform=input=/tmp/transforms.trf:smoothing=20" output.mp4

Installation

Ubuntu / Debian

The stock repository package works. No PPA and no custom build needed.

sudo apt install ffmpeg

That is measured, not assumed. Running apt-get install ffmpeg on this site’s CI (a GitHub Actions Ubuntu runner) makes apt pull in libvidstab1.1 as a dependency. Here is that line from the log:

Unpacking libvidstab1.1:amd64 (1.1.0-2build1) ...

And the FFmpeg binary’s own build configuration lists it — three consecutive entries lifted from the configuration: line of ffmpeg -version:

--enable-libvidstab --enable-libvorbis --enable-libvpx

To run the same check yourself:

ffmpeg -version | grep -o -- "--enable-libvidstab"

You will find claims that Ubuntu’s apt build omits libvidstab. For 6.1.1-3ubuntu5 at least, that is wrong — the --enable-libvidstab line quoted above is from our own CI log on Ubuntu 24.04, where every command in this article ran without a rebuild. Either way, ffmpeg -filters | grep vidstab settles it for your own environment.

If you are on an older build that genuinely lacks it, install libvidstab-dev and rebuild FFmpeg with --enable-libvidstab, or grab a static BtbN/FFmpeg-Builds release. Installing libvidstab-dev alone will not help — it only adds the library’s development headers and does not touch an already-compiled FFmpeg binary.

macOS (Homebrew)

brew install ffmpeg

Homebrew’s FFmpeg formula includes libvidstab. Verify with ffmpeg -filters | grep vidstab.

Windows

Download a build from gyan.dev/ffmpeg/builds — the “full” build includes libvidstab.

Verifying Your Build

ffmpeg -filters 2>/dev/null | grep vidstab

If the output includes vidstabdetect and vidstabtransform, your FFmpeg build supports stabilization.

Limitations

  • libvidstab works best with moderate shake. Extreme camera shake (run-and-gun footage) may produce visible warping or insufficient correction.
  • Two-pass is mandatory. There is no single-pass stabilization.
  • Zoom reduces image area. The more stabilization needed, the more zoom required to hide borders, which crops into the frame.

Primary sources: ffmpeg.org/ffmpeg-filters.html#vidstabdetect / ffmpeg.org/ffmpeg-filters.html#vidstabtransform / trac.ffmpeg.org/wiki/Stabilize_video