Video-Frames Skill 是一个生产级的视频抽帧工具，围绕质量控制、进度跟踪与安全限制设计，可完成单帧提取、批量抽帧、缩略图网格和 GIF 生成等任务。
用途与适用场景 适用于以下情况：在指定时间戳提取视频帧；按帧索引获取精确帧；为视频概览创建缩略图网格或 contact sheet；从视频片段生成动图 GIF；按间隔批量抽帧（如每 N 秒一帧）；制作视频预览或故事板；按指定质量级别抽帧。不适用场景包括：简单格式转换（建议使用 ffmpeg-tools）、视频编辑加特效（建议使用视频编辑器）、实时帧捕获（建议使用流媒体工具）、摄像头视频采集（建议使用 camsnap）、图像生成（建议使用 image-gen）。
前置依赖 需安装 FFmpeg：macOS 使用 brew install ffmpeg，Ubuntu/Debian 使用 sudo apt install ffmpeg。可选安装 ImageMagick 以获得更好的网格生成效果：macOS 使用 brew install imagemagick，Ubuntu 使用 sudo apt install imagemagick。可通过 ffmpeg -version 与 ffprobe -version 验证安装。
主要命令
- 单帧提取（frame）：支持 --time 按时间戳提取，时间格式支持秒、MM:SS、HH:MM:SS 与小数秒；也支持 --index 按帧索引提取（索引 0 为第一帧）。可用 --format 指定输出格式（jpg/jpeg、png、bmp、tiff、webp），用 --quality 设置 JPEG 质量（1 最佳，2-3 高，5 中等，10+ 低）。
- 批量抽帧（frames）：用 --fps 设置每秒抽帧数（1、5、0.1、0.5 等），可用 --start 与 --duration 限定片段，--quality 控制质量，--prefix 设置文件名前缀，--width 在抽帧时缩放。输出到类似 /tmp/frames_1234567890/ 的目录，文件名为 frame_00001.jpg 等。
- 缩略图网格（grid）：用 --count 设置缩略图数量、--columns 设置列数、--width 设置宽度、--format 设置格式、--out 指定输出文件。示例布局包括 4 张（2x2）、9 张（3x3）、12 张（4x3）、16 张（4x4）、20 张（5x4）。
- GIF 生成（gif）：用 --start 与 --duration 指定片段，--preset 选择 fast、balanced、quality 或 cinematic 预设，也可用 --fps 与 --width 自定义。GIF 预设分别对应不同帧率、宽度、颜色数与体积：fast 为 15fps、480px、128 色；balanced 为 20fps、640px、256 色；quality 为 24fps、720px、512 色；cinematic 为 30fps、1080px、1024 色。GIF 最长 300 帧（30fps 下约 10 秒）。
- 视频信息（info）：输出视频大小、时长、宽高、帧率、总帧数等元数据，并包含完整 ffprobe 输出。
进度与安全限制 操作会显示实时进度，例如“Extracting frames: 15/30 (50.0%) | Elapsed: 12.3s”。安全限制包括：最大视频大小 50 GB、最大时长 4 小时、批量抽帧最多 1,000 帧、网格最多 60 张缩略图、GIF 最多 300 帧、默认超时 30 分钟。处理前会校验文件存在且可读、大小在限内、格式有效、时长在限内、包含视频流且未损坏。
错误处理 提供错误码：0 SUCCESS、1 INVALID_INPUT、2 FILE_NOT_FOUND、3 INVALID_FORMAT、4 INVALID_TIME_RANGE、5 FFMPEG_ERROR、6 OUT_OF_MEMORY、7 TIMEOUT、8 INTERRUPTED、9 PERMISSION_DENIED、10 VALIDATION_FAILED、99 UNKNOWN。常见情况包括帧索引超出范围、时间戳超出视频长度、请求帧数过多、GIF 过长等，均会报错。
技术细节与性能建议 抽帧方法包括：Segment Seek（-ss 在 -i 之前，用于 --time，速度快但起点精度略有取舍）、帧选择（-vf select，用于 --index，较慢但帧精确）、间隔抽取（fps 滤镜，用于批量）。JPEG 质量基于 CRF：-q:v 1 约 100%，-q:v 2 约 95%（默认），-q:v 5 约 85%，-q:v 10 约 70%，-q:v 31 约 10%。PNG 为无损、体积更大、支持透明背景。缩放使用 Lanczos 重采样，-2 保证偶数尺寸并维持宽高比。GIF 通过生成 256 色调色板、固定帧率、限制调色板、编码前缩放来优化体积。性能建议包括：JPEG 编码比 PNG 更快；草稿可用更低质量；可并行处理多个视频；抽帧时直接缩放比先抽原图再缩放更高效。
其他说明 网格生成在 ImageMagick 可用时优先使用它（质量更好），否则使用 FFmpeg tile 滤镜。帧索引 0 始终为视频第一帧。时间戳会根据视频帧率四舍五入到最近帧。PNG 透明度会被保留。所有操作自动清理临时文件，JSON 输出便于程序化集成。网格缩略图会包含对应视频时间点的间隔时间戳。