video-to-gif

動画から GIF への変換スキル

このスキルでは、FFmpeg の 2 パスパレット最適化を使用して、動画ファイルを最適化された GIF アニメーションに変換します。

概要

2 パス変換プロセスでは、1 パス方式よりも高品質な GIF を生成できます。1 パス目では動画を解析し、最適化されたカラーパレットを作成します。2 パス目ではそのパレットを適用し、色の再現性を高め、ファイルサイズを小さくした最終的な GIF を生成します。

応答形式

変換が成功したら、応答に GIF へのファイルリンクを絶対ファイルパスで記載してください。

/absolute/path/to/filename.gif

これにより、ユーザーはファイルを開いて確認できます。

前提条件

FFmpeg が必要です。システムの PATH から利用できる必要があります。

macOS

brew install ffmpeg

Linux（Debian/Ubuntu）

sudo apt update && sudo apt install ffmpeg

Windows

Chocolatey を使用する場合：

choco install ffmpeg

winget を使用する場合：

winget install FFmpeg.FFmpeg

インストールを確認します：

ffmpeg -version

クイックスタート

デフォルト設定（10 FPS、幅 1280px、sierra2_4a ディザリング）で動画を変換します：

scripts/convert.sh input.mp4

scripts/convert.ps1 -InputPath input.mp4

デフォルトでは、出力は input.gif に保存されます。

ファイル検索の動作

フルパスを指定せずにファイル名を指定すると、スクリプトは次の順序で検索します：

1. 現在の作業ディレクトリ
2. ワークスペースのルート（プロジェクト内の場合）
3. ~/Movies/（macOS）または ~/Videos/（Linux）
4. ~/Downloads/
5. ~/Desktop/

これにより、フルパスを指定せずに convert.sh demo.mov のような自然なコマンドを使用できます。

HDR の処理

スクリプトは ffprobe を使用して、BT.2020 の色原色または SMPTE 2084 の伝達特性を確認し、HDR 動画コンテンツを自動的に検出します。HDR が検出されると、適切な色を保った SDR 対応の GIF 出力を生成できるよう、トーンマッピングが自動的に適用されます。

トーンマッピングアルゴリズムを選択するには、--tonemap を使用します：

アルゴリズム	特徴
hable	フィルム調のカーブで、ハイライトの減衰が良好（デフォルト）
reinhard	より多くの色の彩度を保持
mobius	reinhard に似ており、ハイライトをより良好に処理
bt2390	ITU 標準で、より控えめ

パラメーターリファレンス

パラメーター	フラグ（bash）	フラグ（PowerShell）	デフォルト	説明
入力ファイル	--input	-InputPath	（必須）	ソース動画ファイルのパス
出力ファイル	--output	-OutputPath	input.gif	出力先GIFファイルのパス
フレームレート	--fps	-Fps	10	1秒あたりのフレーム数
幅	--width	-Width	1280	出力幅（ピクセル単位）
ディザリング	--dither	-Dither	sierra2_4a	ディザリングアルゴリズム
トーンマッピング	--tonemap	-Tonemap	hable	HDRトーンマッピングアルゴリズム
パレットをスキップ	--skip-palette	-SkipPalette	false	シングルパスモードを使用
開始時間	--start	-Start	0	開始時間（秒）
長さ	--duration	-Duration	（動画全体）	変換する長さ（秒）
ループ回数	--loop	-Loop	0	GIFのループ回数（0 = 無限）
タイムアウト	VIDEO_TO_GIF_TIMEOUT（env）	-TimeoutSeconds	600	各ffprobe/ffmpegの実行に許可される秒数

出力パスは入力パスと異なる必要があります。どちらのスクリプトも、出力先が入力ファイルと同じ場所に解決される場合は実行を拒否します。これには.gif入力ファイルに対するデフォルトの出力先も含まれるため、その場合は明示的に出力パスを指定してください。異なる出力パスに既存のファイルがある場合は上書きされます。

各ffprobeおよびffmpegの実行は、タイムアウトを超えると停止します。HDRの検出に失敗するかタイムアウトした場合、入力はSDRとして扱われ、変換が続行されます。

フレームレート（FPS）

FPSはアニメーションの滑らかさとファイルサイズを制御します。値を小さくするとファイルサイズは減りますが、動きがぎこちなくなります。

FPS	用途
5	シンプルなアニメーション、アイコン
10	一般的な用途（デフォルト）
15	滑らかな動き、UIデモ
24	動画に近い品質

幅

幅は出力の水平方向の解像度をピクセル単位で設定します。縦の長さはアスペクト比を維持するよう比例して調整されます。

幅	用途
320	サムネイル、プレビュー
640	ドキュメント
800	プレゼンテーション
1280	高精細（デフォルト）

ディザリングアルゴリズム

ディザリングは、256色のGIFパレットで元の色をどのように近似するかを決定します。

アルゴリズム	品質	速度	最適な用途
sierra2_4a	高	中	一般的な用途（デフォルト）
floyd_steinberg	高	遅い	写真コンテンツ
bayer	中	速い	単色のグラフィック
none	低	最速	スタイライズ／ポスタライズ調

時間範囲の選択

--startと--durationを使うと、動画の特定の部分を変換できます。

# Start at 5 seconds, convert 10 seconds
scripts/convert.sh --input video.mp4 --start 5 --duration 10

ループ制御

--loopを使うと、GIFの繰り返し動作を制御できます。

値	動作
0	無限にループ
1	1回再生
N	N回再生

2パスとシングルパスの比較

2パス（デフォルト）

2パス変換では、ソース動画からカスタムパレットを作成してから適用します。

# Pass 1: Generate palette
ffmpeg -i input.mp4 \
  -vf "fps=10,scale=1280:-1:flags=lanczos,palettegen=stats_mode=diff" \
  -y /tmp/palette.png

# Pass 2: Create GIF
ffmpeg -i input.mp4 -i /tmp/palette.png \
  -filter_complex "fps=10,scale=1280:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=sierra2_4a:diff_mode=rectangle" \
  -loop 0 -y output.gif

2パス変換では色の再現性が向上し、通常はファイルサイズも小さくなります。

シングルパス

シングルパスではパレット生成を省略し、FFmpeg のデフォルトの 256 色パレットを使用します。

ffmpeg -i input.mp4 \
  -vf "fps=10,scale=1280:-1:flags=lanczos" \
  -loop 0 -y output.gif

シングルパスは処理が速くなりますが、出力品質が低下し、色の縞模様が発生する可能性があります。

--skip-palette（bash）または -SkipPalette（PowerShell）を使うと、シングルパスで処理できます。

スクリプトリファレンス

convert.sh（Bash）

# Basic usage
scripts/convert.sh video.mp4

# Custom output path
scripts/convert.sh --input video.mp4 --output demo.gif

# Adjust quality parameters
scripts/convert.sh --input video.mp4 --fps 15 --width 640 --dither floyd_steinberg

# HDR video with custom tonemapping
scripts/convert.sh --input hdr-video.mov --tonemap reinhard

# Extract a 10-second clip starting at 5 seconds
scripts/convert.sh --input video.mp4 --start 5 --duration 10

# Create a GIF that plays only once
scripts/convert.sh --input video.mp4 --loop 1

# Fast single-pass mode
scripts/convert.sh --input video.mp4 --skip-palette

convert.ps1（PowerShell）

# Basic usage
scripts/convert.ps1 -InputPath video.mp4

# Custom output path
scripts/convert.ps1 -InputPath video.mp4 -OutputPath demo.gif

# Adjust quality parameters
scripts/convert.ps1 -InputPath video.mp4 -Fps 15 -Width 640 -Dither floyd_steinberg

# HDR video with custom tonemapping
scripts/convert.ps1 -InputPath hdr-video.mov -Tonemap reinhard

# Extract a 10-second clip starting at 5 seconds
scripts/convert.ps1 -InputPath video.mp4 -Start 5 -Duration 10

# Create a GIF that plays only once
scripts/convert.ps1 -InputPath video.mp4 -Loop 1

# Fast single-pass mode
scripts/convert.ps1 -InputPath video.mp4 -SkipPalette

使用例

HDR 動画の変換

HDR コンテンツは自動的に検出されます。特別なフラグは必要ありません。

scripts/convert.sh hdr-footage.mov

スクリプトはデフォルトで hable トーンマッピングを適用します。別のアルゴリズムを試すには、--tonemap を使用します。

# Use reinhard for more saturated colors
scripts/convert.sh --input hdr-footage.mov --tonemap reinhard

時間範囲の抽出

長い動画から特定の区間を抽出します。

# Convert seconds 30-45 of a screencast
scripts/convert.sh --input screencast.mp4 --start 30 --duration 15 --fps 15

ドキュメント用サムネイル

ドキュメント用のコンパクトなサムネイルを作成します。

scripts/convert.sh --input demo.mp4 --width 320 --fps 8

トラブルシューティング

FFmpeg が見つからない

FFmpeg が PATH に含まれていることを確認します。

which ffmpeg  # macOS/Linux
where.exe ffmpeg  # Windows

FFmpeg がインストールされているのに見つからない場合は、そのディレクトリを PATH 環境変数に追加してください。

ファイルが見つからない

指定したパスにファイルが存在することを確認します。ファイル名のみを指定した場合、スクリプトはまずワークスペースを検索し、次に一般的なディレクトリ（~/Movies/、~/Downloads/、~/Desktop/）を検索します。ファイルが別の場所にある場合は、絶対パスを使用してください。

出力ファイルが大きすぎる

次の設定を調整してファイルサイズを小さくします。

• FPS を下げる（8 または 5 を試してください）
• 幅を小さくする（640 または 320 を試してください）
• 処理を速くするには bayer ディザリングを使用する
• 動画の一部だけを変換するには --duration を使用する

色が薄く見える

写真コンテンツには floyd_steinberg ディザリングに切り替えてください。意図的にスタイライズした見た目にする場合を除き、none ディザリングは避けてください。

HDR コンテンツが正しく表示されない

zscale フィルターをサポートする FFmpeg 4.0 以降がインストールされていることを確認してください。このスクリプトでは HDR トーンマッピングに libzimg が必要です。次の方法でインストールします。

# macOS
brew install zimg
brew reinstall ffmpeg

# Ubuntu
sudo apt install libzimg-dev

色味がまだ適切でない場合は、--tonemap で別のトーンマッピングアルゴリズムを試してください。reinhard アルゴリズムは彩度をより多く保ち、bt2390 はより控えめな結果を出します。

フィルターエラーで変換に失敗する

FFmpeg 4.0 以降がインストールされていることを確認してください。palettegen フィルターと paletteuse フィルターには、このバージョンが必要です。

ffmpeg -version

一時パレットファイルが残る

スクリプトは /tmp/palette.png（Windows では $env:TEMP\palette.png）を自動的に削除します。処理の途中で変換に失敗した場合は、このファイルを手動で削除してください。