Skip to content

gkraberger/vid.stab

BranchesTags
 
 

Repository files navigation

VidStab

Vidstab is a video stabilization library which can be plugged-in with Ffmpeg and Transcode.

Why is it needed

A video acquired using a hand-held camera or a camera mounted on a vehicle, typically suffers from undesirable shakes and jitters. Activities such as surfing, skiing, riding and walking while shooting videos are especially prone to erratic camera shakes. Vidstab targets these video contents to help create smoother and stable videos.

Some of the features include:

  • Fast detection of subsequent transformations e.g. translation and rotations up to a given extent.
  • Low pass filtered smoothing with adjustable horizon.
  • Detection algorithms:
  • Smart and fast multi measurement fields algorithm with contrast selection.
  • Brute force algorithm only for translations.
  • Clipping options: keep blank (black) or keep from previous frames.
  • Optional drawing of measurement fields and detected transformations for visual analysis.
  • Zooming possible to get rid of jiggling borders (automatic mode).
  • Resulting images are interpolated (different algorithms).
  • Sharpening of the stabilized movie to compensate for interpolation effects due to rotation/zooming (only with Transcode).
  • Single pass filter for streaming applications(only with Transcode).
  • Virtual-tripod-mode to get a tripod experience.

NOTE: This readme focuses mainly on using vidstab with Ffmpeg. See here for information regarding installation, usage and examples for using vidstab with Transcode. Or contact me at georg dot martius @ web dot de

System Requirements

  • A Linux-based system
  • ffmpeg source code
  • Cmake

Installation Instructions

For using vidstab library with ffmpeg, ffmpeg must to be configured using --enable-libvidstab option.

Default Build and Installation:

Installing vidstab library:
cd path/to/vid.stab/dir/
cmake .
make
sudo make install
Installing ffmpeg:
cd path/to/ffmpeg/dir/
./configure --enable-gpl --enable-libvidstab <other configure options>
make
sudo make install

Alternatively one can install vidstab into a custom directory this way:

Installing vidstab library:
cd path/to/vid.stab/dir/
cmake -DCMAKE_INSTALL_PREFIX:PATH=path/to/install_dir/
make
sudo make install
Installing ffmpeg:
cd path/to/ffmpeg/dir/
PKG_CONFIG_PATH="path/to/install_dir/lib/pkgconfig" \
./configure --enable-gpl --enable-libvidstab <other optionalconfigure options>
make
sudo make install

Before running ffmpeg for the first time, make sure to export LD_LIBRARY_PATH to point to vidstab library, e.g.,

export LD_LIBRARY_PATH=path/to/install_dir/lib:$LD_LIBRARY_PATH

Usage instructions

Currently with ffmpeg, vidstab library must run in two-pass mode. The first pass employs the vidstabdetect filter and the second pass uses the vidstabtransform filter.

Single pass filter with vidstab library is only available with Transcode. The deshake filter of ffmpeg can be used for a single-pass encoding, though using the vidstab two-pass filters will give superior results.

The vidstabdetect filter (in first pass) will generate a file with relative-translation and rotation-transform information about subsequent frames. This information will then be read by vidstabtransform filter (in second pass) to compensate for the jerky motions and produce a stable video output.

Make sure that you use unsharp filter provided by ffmpeg for best results (only in second pass).

See the list of ffmpeg filters to know more about vidstabdetect, vidstabtransform and all other filters available with ffmpeg.

Available options with vidstab filters:

First pass (vidstabdetect filter):
result
Set the path to the file used to write the transforms information. Default value is transforms.trf.
shakiness
Set the shakiness of input video or quickness of camera. It accepts an integer in the range 1-10, a value of 1 means little shakiness, a value of 10 means strong shakiness. Default value is 5.
accuracy
Set the accuracy of the detection process. It must be a value in the range 1-15. A value of 1 means low accuracy, a value of 15 means high accuracy. Default value is 15.
stepsize
Set stepsize of the search process. The region around minimum is scanned with 1 pixel resolution. Default value is 6.
mincontrast
Set minimum contrast. Any measurement field having contrast below this value is discarded. Must be a floating point value in the range 0-1. Default value is 0.3.
tripod
Set reference frame number for tripod mode. If enabled, the motion of the frames is compared to a reference frame in the filtered stream, identified by the specified number. The intention is to compensate all movements in a more-or-less static scene and keep the camera view absolutely still. If set to 0, it is disabled. The frames are counted starting from 1.
NOTE: If this mode is used in first pass then it should also be used in second pass.
show
Show fields and transforms in the resulting frames for visual analysis. It accepts an integer in the range 0-2. Default value is 0, which disables any visualization.
Examples: