CLI でアニメーション GIF プレビューを自動生成
動画ディレクトリ内の各ファイルから短い GIF を生成し、出力ディレクトリでも相対パスを維持します。以下の Bash スクリプトは、冒頭の 3 秒を 10 fps のプレビューにし、既存のファイルを保護します。変換が一つでも失敗すると、失敗ステータスを返します。別々のフォルダーにある同名の
demo.mp4 という二つの動画には、それぞれ個別のプレビューを生成します。
Linux ツールのセットアップ
Bash、GNU findutils と coreutils、および ffprobe を備えた FFmpeg を使用します。この例は、ハードリンクをサポートする大文字と小文字を区別するファイルシステム上の Linux を対象としています。ネイティブの macOS と PowerShell は、この手順でのテスト対象外です。通常の正方形ピクセルの SDR 動画を使用してください。HDR トーンマッピングとアナモフィック動画の補正には、別途フィルターの設定が必要です。
これらの例は、Ubuntu 24.04 上の FFmpeg 6.1.1 と Linux 上の FFmpeg n9.0.1 でテストしています。
Ubuntu または Debian では、次のコマンドでツールをインストールします。
sudo apt-get update && sudo apt-get install ffmpeg bash findutils coreutils
Ubuntu の FFmpeg パッケージには、メディアツールが含まれています。シェルで使用できるバージョンを確認します。
bash --version
ffmpeg -version
ffprobe -version
出力先で GIF が必要な場合の選択
GIF は、ドキュメント内でループする図や、画像は受け付けても動画を埋め込めないシステムに適しています。ただし、色数が限られており、音声もありません。元の MP4 よりも大幅に大きくなることがあるため、Web プレビューに使う前に実際のファイルを比較してください。出力先が動画に対応していれば、短い動画クリップのままにするほうが、小さいサイズで高い画質を得られる場合があります。Google の GIF と動画の比較で、サイズにどの程度の差が生じうるかを確認できます。
長さとサイズを制限したプレビューの作成
作業ディレクトリに input.mp4 という名前の動画を置き、次を実行します。
(
if [[ -e ./preview.gif || -L ./preview.gif ]]; then
printf 'Refusing existing output: ./preview.gif\n' >&2
exit 1
fi
ffmpeg -hide_banner -loglevel error -nostdin -n -xerror -abort_on empty_output \
-t 3 -i ./input.mp4 -map 0:v:0 \
-vf "fps=10,scale='min(320,iw)':-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" \
-t 3 -frames:v 30 -loop 0 -f gif ./preview.gif
)
最初の動画ストリームを選択し、小さい入力は拡大せずに幅を最大 320 ピクセルに制限して、無限ループする GIF を作成します。入力側の -t 3 は、フィルターに渡す区間を制限します。出力時間とフレーム数の上限により、プレビューは最大 3 秒、30 フレームになります。入力が短ければ、プレビューも短くなります。FFmpeg の入力と出力のオプション規則を参照してください。
分岐によって、拡大縮小後のフレームを palettegen と
paletteuse の両方に送ります。前者はクリップからパレットを生成し、後者はそれを適用します。動画全体のパレットを生成すると出力が遅れ、バッファリングも増えるため、入力の制限が重要です。使用できる色とディザリングの設定については、パレットフィルターのドキュメントを参照してください。
シェルでの確認では、preview.gif がすでに存在する場合は失敗として報告します。-n も、上書きしないよう FFmpeg に指示します。FFmpeg はバージョンによって上書きを拒否してもゼロを返す場合があるため、ここではそのステータスだけでは不十分です。-nostdin は対話的な入力を無効にします。ファイル作成後に変換が失敗すると、不完全な GIF が残ることがあります。以下のバッチスクリプトでは、まず一時ファイルに変換し、不完全な出力が公開されないようにします。
成功した結果は、次のコマンドで調べます。
ffprobe -v error -select_streams v:0 -count_frames \
-show_entries stream=width,height,nb_read_frames:format=duration,size \
-of json ./preview.gif
入力の長さが 3 秒以上なら、30 フレーム、長さ 3.000000 秒になるはずです。GIF も開いて確認してください。選ばれた冒頭シーンが有用かどうかは、メタデータでは判断できません。
ファイル名を維持したディレクトリのバッチ処理
このスクリプト全体を gif-previews.sh として保存してください。シンボリックリンクのエントリをたどらず、末尾が .mp4 の通常ファイルを、大文字と小文字を区別せず再帰的に処理します。相対ファイル名全体に
.gif を付加するため、videos/team/demo.mp4 は
gifs/team/demo.mp4.gif になります。拡張子を残すことで、対象のファイルシステム上では
demo.mp4 と demo.MP4 も区別できます。
#!/usr/bin/env bash
set -euo pipefail
if (( $# > 2 )); then
printf 'Usage: bash gif-previews.sh [video-directory] [output-directory]\n' >&2
exit 1
fi
VIDEO_DIR=${1:-./videos}
OUTPUT_DIR=${2:-./gifs}
command -v ffmpeg >/dev/null
# Resolve both directory arguments from the caller's working directory.
start_dir=$PWD
cd -P -- "$VIDEO_DIR"
VIDEO_DIR=$PWD
cd -P -- "$start_dir"
mkdir -p -- "$OUTPUT_DIR"
cd -P -- "$OUTPUT_DIR"
OUTPUT_DIR=$PWD
cd -P -- "$VIDEO_DIR"
work=$(mktemp -d -- "$OUTPUT_DIR/.gif-preview.XXXXXX")
trap 'rm -rf -- "$work"' EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
# Finish discovery first so a failed find cannot look like an empty successful batch.
find . -type f -iname '*.mp4' -print0 > "$work/files"
if [[ ! -s "$work/files" ]]; then
printf 'No MP4 files found.\n' >&2
exit 1
fi
generated=0
failed=0
while IFS= read -r -d '' video; do
output="$OUTPUT_DIR/${video#./}.gif"
if [[ -e "$output" || -L "$output" ]]; then
printf 'Refusing existing output: %q\n' "$output" >&2
failed=$((failed + 1))
continue
fi
if mkdir -p -- "${output%/*}" &&
ffmpeg -hide_banner -loglevel error -nostdin -y -xerror -abort_on empty_output \
-t 3 -i "$video" -map 0:v:0 \
-vf "fps=10,scale='min(320,iw)':-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" \
-t 3 -frames:v 30 -loop 0 -f gif "$work/preview.gif" &&
ln -T -- "$work/preview.gif" "$output"; then
printf 'Generated: %q\n' "$output"
generated=$((generated + 1))
else
printf 'Failed: %q\n' "$video" >&2
failed=$((failed + 1))
fi
# Unlink the temporary name before reuse: published files share its inode.
rm -f -- "$work/preview.gif"
done < "$work/files"
printf 'Generated: %d; failed: %d\n' "$generated" "$failed"
if (( failed > 0 )); then
exit 1
fi
videos フォルダーがあるディレクトリから実行します。
bash gif-previews.sh ./videos ./gifs
このスクリプトは、ファイル名に含まれる空白、改行、先頭のハイフン、文字としてのパーセント記号を維持します。ヌル文字区切りでファイルを検出するため、各ファイル名がそのまま保持されます。また、-nostdin により、FFmpeg がループの入力を読み取ることはありません。検出と変換はどちらも、物理パスに解決した同じ入力ディレクトリから実行します。ディレクトリ引数にシンボリックリンクと、それに続く .. が含まれる場合も同様です。
出力先がすでに存在する場合は失敗として扱い、通知せずにスキップしたり置き換えたりしません。変換時の -y は、専用の一時ファイルにのみ使用します。GNU の ln -T で完成した GIF を公開し、変換中に出現した出力先は置き換えません。ハードリンクを使えるよう、一時ディレクトリは出力先のファイルシステム上に作成します。管理下にあり、シンボリックリンクのサブディレクトリや入れ子のマウントがない出力ツリーを使用してください。
成功と失敗が混在するバッチでは、成功した GIF を保持し、ファイル単位の失敗後も処理を続行して、最後にステータス 1 で終了します。入力ディレクトリが空の場合もステータス 1 で終了します。同じ出力ツリーに対して再実行すると、既存のファイルを失敗として報告します。バッチ全体を再生成するには、新しい出力ディレクトリを選んでください。通常の失敗や割り込みでは一時ファイルを削除しますが、強制終了や電源喪失では、隠しディレクトリ .gif-preview.* が残ることがあります。
サイズと画質の配分調整
まずは 3 秒、320 ピクセル、10 fps の設定で、代表的なクリップを確認してください。寸法を小さくすると細部が失われ、フレームレートを下げると動きの滑らかさが減ります。色の調整よりも、クリップを短くするほうがサイズを削減できることがよくあります。フレームレートや長さを変更する場合は、両方の -t の値と
-frames:v の上限をまとめて更新してください。2 秒、8 fps なら上限を 16 にします。
既定の paletteuse ディザリングはグラデーションに有効ですが、目に見えるノイズが加わることがあります。ドキュメントに記載されている
dither=bayer 設定も、手元の映像で比較する価値があります。これらの設定は、細部、動き、色の正確さとサイズのトレードオフを調整するものです。どの設定も、GIF が動画コーデックより優れた結果になることを保証するものではありません。
バッチ失敗の診断
- 既存の出力: 新しい出力ディレクトリを選ぶか、再生成したいプレビューだけを意図的に削除してください。画質設定を変更しても、以前の結果は上書きされません。
- 無効な動画、または動画ストリームなし: 報告された元ファイルを
ffprobeで調べてください。破損したファイルを.mp4に改名しても修復されません。スクリプトが確認するのはプレビュー区間であり、動画全体の正常性ではありません。 - フレームなし、または不適切な冒頭シーン: 極端に短い入力や特殊な入力では、プレビューが生成されない場合があります。スクリプトは空の出力を失敗として扱います。冒頭が黒い場合は、別の区間を使う必要があります。
- ファイルシステムまたはメモリのエラー: 空き容量、出力先の権限、ハードリンクのサポートを確認してください。大きな入力では、区間の長さと寸法を小さくしてください。クリップを 3 秒に制限しても、デコーダーのメモリ使用量や実行時間に厳密な上限が設けられるわけではありません。
表示されたファイルパスを使って失敗を調べ、成功した GIF も確認してからメディアカタログに登録してください。
