三脚なしの手持ち撮影や歩きながらの動画は、どうしても手ブレが乗ってしまいます。FFmpeg の vidstab は、まず映像を解析して揺れを検出し（vidstabdetect）、その結果をもとに揺れを打ち消す（vidstabtransform）2パス方式で安定化します。この記事ではパイプラインの流れ、smoothing や crop などの主要パラメータ、libvidstab の導入方法、限界と代替案までを解説します。
前提条件:
vidstabdetectおよびvidstabtransformフィルターは、FFmpegが--enable-libvidstab付きでビルドされている必要があります。Ubuntu / Debian のapt install ffmpegは条件を満たします（本サイトのCIで実測。詳細はインストール）。まずffmpeg -filters | grep vidstabで確認してください。
動画手ブレ補正の仕組み
FFmpegの動画手ブレ補正は外部ライブラリlibvidstabに依存し、2つのフィルターを使用します：
vidstabdetect— パス1: 動画のカメラ動きを分析し、モーションベクターファイル（デフォルト:transforms.trf）に書き出すvidstabtransform— パス2: モーションデータを読み込み、揺れを打ち消す変換（平行移動・回転）を適用する
2パス方式が必要な理由：フィルターが滑らかなカメラパスを計算するために、動き全体の軌跡を事前に把握する必要があるからです。
基本的な2パス手ブレ補正
注意: このセクションのFFmpegコマンドはすべて
--enable-libvidstabが必要です。以下のコマンドは Ubuntu 標準のapt install ffmpegビルドに対して本サイトのCIで毎回実行しており、参考掲載ではなく実行確認済みです。
パス1 — モーション検出：
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf vidstabdetect -f null /dev/nullカレントディレクトリにtransforms.trfが書き出されます。
パス2 — 手ブレ補正：
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf vidstabtransform output.mp4transforms.trfを読み込み、安定化された動画を生成します。
補正強度の調整
パス1：shakiness
shakinessパラメータ（1〜10、デフォルト: 5）は、検出器が動きを探す積極さを制御します。非常に揺れの大きい映像では値を上げます：
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabdetect=shakiness=8:accuracy=15" -f null /dev/null| パラメータ | 範囲 | デフォルト | 説明 |
|---|---|---|---|
shakiness |
1〜10 | 5 | 検出する動きの範囲 |
accuracy |
1〜15 | 15 | 検出精度（高いほど遅い） |
result |
パス | transforms.trf |
モーションファイルの出力先 |
パス2：smoothingとcrop
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabtransform=smoothing=30:crop=black" output.mp4| パラメータ | デフォルト | 説明 |
|---|---|---|
smoothing |
15 | 時間的平滑化半径（フレーム数）。高いほど滑らかだが黒枠が広くなる |
crop |
keep |
安定化の境界処理: keep（前フレームの情報で縁を埋める／既定）または black（黒で塗りつぶす） |
zoom |
0 | 追加ズーム率（%）。正で拡大、負で縮小 |
optzoom |
1 | 自動ズーム: 0=しない / 1=静的に最適化（既定） / 2=動的に最適化 |
interpol |
bilinear |
補間方法: no・linear・bilinear・bicubic |
cropの既定値はblackではなくkeepです。 省略すると黒枠ではなく、前フレームの映像で縁が埋められます（残像状に見えます）。黒枠にしたい場合は明示的にcrop=blackを指定してください。本記事のコマンドはすべて明示指定しています。ffmpeg -h filter=vidstabtransformで(default keep)と確認できます。
ズームで黒枠を隠す
手ブレ補正はカメラの動きを補償するためにフレームをシフトし、端に黒枠が現れます。zoomでスケールアップして黒枠を隠します：
# requires --enable-libvidstab
ffmpeg -i input.mp4 -vf "vidstabtransform=smoothing=20:zoom=5:crop=black" output.mp4zoom=5で出力を5%拡大し、黒枠を覆います。トレードオフとして画像領域がわずかに縮小します（クロップイン効果）。
カスタムパスを使った完全なパイプライン
スクリプトや複数ファイルを処理する場合、モーションファイルのパスを明示的に指定します：
# 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インストール
Ubuntu / Debian
標準リポジトリの ffmpeg パッケージで動きます。 PPAも自前ビルドも不要です。
sudo apt install ffmpegこれは推測ではなく実測です。本サイトのCI（GitHub Actions の Ubuntu ランナー）で apt-get install ffmpeg を実行すると、apt が libvidstab1.1 を依存として同時に導入します。そのログの該当行がこれです。
Unpacking libvidstab1.1:amd64 (1.1.0-2build1) ...そして入った FFmpeg 自身のビルド設定にも含まれています。ffmpeg -version の configuration: 行から連続する3項目を抜き出したものです。
--enable-libvidstab --enable-libvorbis --enable-libvpx自分の環境で同じ確認をするならこうです。
ffmpeg -version | grep -o -- "--enable-libvidstab"「Ubuntu の apt 版には libvidstab が入っていない」という説明を見かけますが、少なくとも 6.1.1-3ubuntu5 では誤りです。上で引用した --enable-libvidstab の行は Ubuntu 24.04 上の当サイト CI の実行ログそのままで、本記事のコマンドはそのビルドで再ビルドなしに全て通っています。最終的には ffmpeg -filters | grep vidstab で自分の環境を確認するのが確実です。
万一含まれていない古いビルドを使っている場合は、libvidstab-dev を入れた上で --enable-libvidstab を付けて自分でビルドするか、静的ビルド（BtbN/FFmpeg-Builds）を使ってください。sudo apt install libvidstab-dev だけでは解決しません — これはライブラリの開発用ヘッダを入れるだけで、ビルド済みのFFmpegバイナリには影響しないためです。
macOS（Homebrew）
brew install ffmpegHomebrewのFFmpegフォーミュラにはlibvidstabが含まれています。ffmpeg -filters | grep vidstabで確認してください。
Windows
gyan.dev/ffmpeg/buildsから“full”ビルドをダウンロードしてください — libvidstabが含まれています。
ビルドの確認方法
ffmpeg -filters 2>/dev/null | grep vidstab出力にvidstabdetectとvidstabtransformが表示されれば、手ブレ補正が使用可能です。
制限事項
- libvidstabは中程度の手ブレに最適です。 極端な手ブレ（走りながら撮影した映像など）では、見た目のゆがみや補正不足が生じることがあります。
- 2パスは必須です。 シングルパスの手ブレ補正はありません。
- ズームで画像領域が縮小します。 補正量が多いほど黒枠を隠すために必要なズームが大きくなり、フレームがクロップされます。
関連記事
テスト環境: この記事のコマンドは2つのビルドで実行して検証しています — ffmpeg 8.1（gyan.dev full / Windows）と、CI 上の ffmpeg 6.1.1-3ubuntu5（Ubuntu 標準パッケージ、--enable-libvidstab 付き）。
一次ソース: ffmpeg.org/ffmpeg-filters.html#vidstabdetect / ffmpeg.org/ffmpeg-filters.html#vidstabtransform / trac.ffmpeg.org/wiki/Stabilize_video
よくある質問
vidstabdetect と vidstabtransform は両方必要？
はい、2 段階処理です。1 段目（detect）で動画を解析してモーションデータ transforms.trf を生成。2 段目（transform）でそのデータを元に手ブレを補正。
スマホで撮った揺れた動画も補正できる？
できます。vidstabdetect=shakiness=8:accuracy=15 まで上げると激しいブレも拾えます。ただし揺れが極端だと縁の破綻が目立つので、vidstabtransform=zoom=5:crop=black のように数%ズームして縁を隠すのが定番です。crop は keep か black の2択で、ピクセル数は取りません（縁を数値で切り落としたい場合は別の crop フィルタを後段に繋ぎます）。
vidstab で出力すると映像が小さくなる
補正で画面端に発生する破綻を避けるため、optzoom=1（既定）が自動的にやや拡大しています。拡大を止めるには zoom=0 ではなく optzoom=0 を指定してください（zoom の既定値はもともと 0 なので、zoom=0 を書いても何も変わりません）。拡大を止めると縁の処理は crop の設定次第になります。
リアルタイムで安定化したい
vidstab は事前解析が必須なのでリアルタイムは不可。リアルタイム手ブレ補正には deshake フィルタを使う（精度は劣るが 1 パスで済む）。
安定化後の動画を更に補正したい
可能ですが多重補正は劣化を増やす。理想は元動画から 1 度だけ vidstab を適用すること。すでに補正済み動画にもう一度かけたい場合は、shakiness=2 accuracy=5 のように軽めに。