Video Stabilization — vidstabdetect and vidstabtransform

What You Will Learn

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

Tested version: FFmpeg 6.1 (ubuntu-latest / CI-validated)
Target OS: Linux / macOS / Windows

Prerequisite: The vidstabdetect and vidstabtransform filters require FFmpeg to be compiled with --enable-libvidstab. The standard Ubuntu 24.04 package (apt install ffmpeg) does not include libvidstab. See the Installation section below for how to get a build that includes it.

How Video Stabilization Works

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

vidstabdetect — Pass 1: Analyzes the video for camera motion and writes a motion vectors file (default: transforms.trf).
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: All FFmpeg commands in this section require --enable-libvidstab. They are shown for reference — run them on a system where libvidstab is available.

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`	`black`	Fill stabilized borders: `black` (black fill) or `keep` (retain original edge)
`zoom`	0	Additional zoom percentage to hide border artifacts
`interpol`	`bilinear`	Interpolation method: `no`, `linear`, `bilinear`, `bicubic`

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 ffmpeg package in Ubuntu 24.04 repositories does not include libvidstab. Options:

Install from a PPA that includes non-free/external libraries:
```
sudo add-apt-repository ppa:savoury1/ffmpeg4
sudo apt update
sudo apt install ffmpeg
```
Then verify: ffmpeg -filters | grep vidstab
Build FFmpeg from source with --enable-libvidstab (requires libvidstab-dev):
```
sudo apt install libvidstab-dev
```
Then configure FFmpeg with --enable-libvidstab and compile.

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.

Tested with: ffmpeg 6.1.1 / Ubuntu 24.04 (GitHub Actions runner — libvidstab not available in default package)
Primary sources: ffmpeg.org/ffmpeg-filters.html#vidstabdetect / ffmpeg.org/ffmpeg-filters.html#vidstabtransform / trac.ffmpeg.org/wiki/Stabilize_video