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/ 目录下生成 GIF，使用 full 预设（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 色。

---

重要说明

• 大于源视频分辨率的宽度会自动跳过。
• 脚本使用 FFmpeg 的两遍调色板生成，以获得最佳 GIF 画质（远优于单遍处理）。
• 使用 gifsicle 进行有损压缩，压缩级别为 30–60 时，在视觉影响极小的情况下可将文件大小减少 30–70%。
• 对于很长的视频片段，建议先使用 --start/--end 裁剪 — 超过 10 秒的 GIF 可能会非常大。