video-to-gif

视频转 GIF 转换技能

此技能使用 FFmpeg 两遍调色板优化，将视频文件转换为经过优化的 GIF 动画。

概述

与单遍处理相比，两遍转换流程能生成质量更高的 GIF。第一遍会分析视频并创建经过优化的调色板。第二遍会应用该调色板，生成色彩还原度更高、文件更小的最终 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	每秒帧数
宽度	--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（环境变量）	-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	播放一次
N	播放 N 次

双遍与单遍

双遍（默认）

双遍转换会先根据源视频创建自定义调色板，再应用该调色板：

# 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

双遍转换能提供更准确的色彩，通常也会生成更小的文件。

单遍处理

单遍处理会跳过调色板生成，并使用 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+。脚本需要 libzimg 才能进行 HDR 色调映射。通过以下方式安装：

# 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）。如果转换过程中途失败，请手动删除此文件。