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 抖色

# 使用較少變體快速比較
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets minimal

# 包含有損壓縮（需安裝 gifsicle）
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets lossy

# 注重高品質
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）

---

範例

# 轉換影片前 10 秒
uv run --python 3.12 .../video_to_gif.py demo.mp4 --end 10

# 提取特定片段
uv run --python 3.12 .../video_to_gif.py demo.mp4 --start 5 --end 15

# 自訂參數掃描
uv run --python 3.12 .../video_to_gif.py demo.mp4 --fps 12 15 --width 480 800 --colors 256

# 有損壓縮比較（需安裝 gifsicle）
uv run --python 3.12 .../video_to_gif.py demo.mp4 --lossy 0 30 60 100

---

如何選擇

執行後，開啟輸出目錄進行比較：

1. 從最小的檔案開始 — 檢查品質是否可接受
2. 檢查色帶現象 — 如果明顯，嘗試 256 色或 Bayer 抖色（quality 預設集）
3. 檢查流暢度 — 如果太卡，提高至 15 或 20 FPS
4. 檢查清晰度 — 如果文字難以辨識，提高寬度至 640 或 800px

大多數螢幕錄影的最佳平衡點通常在 640px、15fps、256 色。

---

重要注意事項

• 寬度大於來源影片解析度時會自動跳過。
• 腳本使用 FFmpeg 的兩次調色盤生成以獲得最佳 GIF 品質（遠優於單次處理）。
• 透過 gifsicle 的有損壓縮可在等級 30-60 時減少 30-70% 的檔案大小，且視覺影響極小。
• 對於非常長的片段，建議先用 --start/--end 裁切 — 超過 10 秒的 GIF 可能會非常大。