video-to-gif

スキル：動画から GIF へ

動画ファイルを異なるパラメーターで複数の GIF 形式に変換し、見た目を比較して最適なものを選べるようにします。

前提条件：FFmpeg と uv がインストールされている必要があります。gifsicle は任意です（非可逆圧縮のバリエーションを利用できます）。

---

使用する場面

動画クリップから GIF を作成したいものの、適切なパラメーターがわからない場合に使います。GIF の品質には次のようなトレードオフがあります。

• ファイルサイズ — 共有や埋め込みには小さいほど適しています
• 色の正確さ — 色数を減らすとファイルサイズは小さくなりますが、バンディングが発生することがあります
• 滑らかさ — FPS を上げると滑らかになりますが、ファイルサイズは大きくなります
• 解像度 — 幅を広くすると細部が鮮明になりますが、ファイルサイズは大きくなります

推測で決めるのではなく、このスキルで複数のバリエーションを生成し、ユーザーが選べるようにします。

---

デフォルトのワークフロー

ユーザーから動画ファイルが提供された場合：

uv run --python 3.12 /path/to/skills/video-to-gif/scripts/video_to_gif.py <input.mp4>

<input>_gifs/ ディレクトリに、full プリセットの GIF（18 種類）を生成します。

• 3 種類の FPS：10、15、20
• 3 種類の幅：480px、640px、800px
• 2 種類の色数：128、256

出力には、各バリエーションのファイルサイズ、FPS、幅、色数を示す、並べ替え済みの比較表が含まれます。

---

プリセット

プリセット	バリエーション	最適な用途
full	約18種類	一般的な用途 — パラメーターの範囲を幅広く比較できます
minimal	約4種類	手早い比較 — 主要なトレードオフのポイントだけを確認できます
lossy	約12種類	ファイルサイズを最小限に — gifsicle の非可逆圧縮レベルを含みます
quality	約12種類	見た目を重視 — 高解像度で、Bayer ディザリングを含みます

# Quick comparison with fewer variants
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets minimal

# Include lossy compression (requires gifsicle)
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets lossy

# Higher quality focus
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets quality

---

よく使うオプション

フラグ	デフォルト	説明
-o、--output-dir	<input>_gifs/	すべての GIF バリエーションの出力先ディレクトリ
--start	なし	開始時間（秒）（入力動画をトリミング）
--end	なし	終了時間（秒）（入力動画をトリミング）
--presets	full	プリセット設定：full、minimal、lossy、quality
--fps	プリセット	FPS の値を上書きします（例：--fps 10 15 20）
--width	プリセット	幅の値を上書きします（例：--width 480 640）
--colors	プリセット	色数を上書きします（例：--colors 128 256）
--lossy	プリセット	gifsicle の非可逆圧縮レベル（例：--lossy 0 30 80）

---

例

# Convert first 10 seconds of a video
uv run --python 3.12 .../video_to_gif.py demo.mp4 --end 10

# Extract a specific segment
uv run --python 3.12 .../video_to_gif.py demo.mp4 --start 5 --end 15

# Custom parameter sweep
uv run --python 3.12 .../video_to_gif.py demo.mp4 --fps 12 15 --width 480 800 --colors 256

# Lossy compression comparison (needs gifsicle)
uv run --python 3.12 .../video_to_gif.py demo.mp4 --lossy 0 30 60 100

---

選び方

実行後、出力ディレクトリを開いて比較します。

1. まずはファイルサイズが最小のものを確認します — 品質に問題がないか確認してください
2. 色のバンディングを確認します — 目立つ場合は、256 色または Bayer ディザリング（quality プリセット）を試してください
3. 滑らかさを確認します — カクつきすぎる場合は、FPS を 15 または 20 に上げてください
4. 鮮明さを確認します — テキストが読みにくい場合は、幅を 640 または 800px に上げてください

ほとんどの画面録画では、640px、15fps、256 色あたりが最適なバランスです。

---

重要な注意事項

• 元の動画の解像度より幅が大きい設定は、自動的にスキップされます。
• このスクリプトでは、GIF の品質を最適化するために FFmpeg の 2 パスパレット生成を使用します（1 パス方式よりも大幅に優れています）。
• gifsicle による非可逆圧縮では、レベル 30～60 で見た目への影響を最小限に抑えながら、ファイルサイズを 30～70% 削減できます。
• 非常に長いクリップの場合は、まず --start／--end でトリミングすることを検討してください。10 秒を超える GIF は非常に大きくなることがあります。