Video Frames Tool Free

SKILL.md

---
name: "video-frames-tool-free"
description: "轻量级视频帧提取工具，支持单帧抓取与时间点截图，适合个人创作者快速生成缩略图。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "视频帧提取-免费版"
  version: "1.0.0"
  summary: "轻量级视频帧提取工具，支持单帧抓取与时间点截图，适合个人创作者快速生成缩略图。"
  tags:
    - "Creative"
    - "视频处理"
    - "帧提取"
    - "免费版"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

# 视频帧提取工具 - 免费版

## 概述

视频帧提取免费版是一款面向个人创作者的轻量级视频抓帧工具。它依托 `ffmpeg` 命令行能力，让 AI Agent 通过自然语言指令即可从任意视频中提取关键帧，无需编写复杂脚本。

免费版聚焦核心抓帧场景：单帧抓取、首帧预览、基础缩略图生成。配置极简，开箱即用，适合以下用户：

- 短视频创作者快速获取封面
- 学习者整理视频笔记配图
- 内容运营人员生成预览图
- 测试人员快速验证视频内容

> 免费版限制：单次最多处理 1 个视频，最多生成 10 张缩略图。如需批量处理、区间提取、短视频剪辑等高级能力，请使用 PRO 版本。

## 核心能力

### 能力清单

| 能力 | 描述 | 免费版 |
|:-----|:-----|:-------|
| 单帧抓取 | 指定时间点提取一帧图像 | 支持 |
| 首帧抓取 | 快速获取视频第一帧 | 支持 |
| 缩略图生成 | 按间隔生成多张缩略图 | 支持（≤10 张） |
| 输出格式 | JPG / PNG 切换 | 支持 |
| 区间提取 | 提取视频片段为 GIF/MP4 | 不支持 |
| 批量处理 | 多视频并行处理 | 不支持 |
| 水印添加 | 自定义水印与位置 | 不支持 |
| 自定义分辨率 | 输出指定分辨率 | 不支持 |

**输入**: 用户提供能力清单所需的指令和必要参数。
**处理**: 按照skill规范执行能力清单操作,遵循单一意图原则。
**输出**: 返回能力清单的执行结果,包含操作状态和输出数据。

### 工作流程

```text
用户输入视频路径
      ↓
选择抓帧模式（首帧 / 时间点 / 缩略图）
      ↓
设置输出参数（格式、保存路径）
      ↓
调用 ffmpeg 执行抓帧
      ↓
返回结果路径供用户查看
```

**输入**: 用户提供工作流程所需的指令和必要参数。
**处理**: 按照skill规范执行工作流程操作,遵循单一意图原则。
**输出**: 返回工作流程的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 按照skill规范执行核心功能执行操作,遵循单一意图原则。
**输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：轻量级视频帧提取、支持单帧抓取与时、间点截图、适合个人创作者快、速生成缩略图、视频帧提取免费版、专注于为个人用户、提供简洁高效的视、频帧抓取能力、核心能力、单帧精准提取、指定时间点抓取、首帧快速抓取、一秒生成预览图、输出格式切换、基础缩略图批量生等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

### 核心功能执行
执行核心功能执行操作,使用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 按照skill规范执行核心功能执行操作,遵循单一意图原则。
**输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

## 使用场景

### 场景 1：短视频封面制作

小张是一名短视频博主，每次发视频都需要从成片中挑选一帧作为封面。

**操作步骤：**

1. 告诉 Agent：「帮我从 `/videos/vlog-01.mp4` 的第 8 秒抓一张封面图」
2. Agent 调用抓帧脚本，输出 `/tmp/cover-08s.jpg`
3. 用户确认效果后即可上传至平台

**示例命令：**

```bash
{baseDir}/scripts/frame.sh /videos/vlog-01.mp4 --time 00:00:08 --out /tmp/cover-08s.jpg
```

### 场景 2：视频内容快速预览

小李收到一段 30 分钟的会议录像，想快速了解大致内容。

**操作步骤：**

1. 告诉 Agent：「帮我给 `/videos/meeting.mp4` 生成 6 张缩略图」
2. Agent 按均匀间隔抓取 6 帧，保存至 `/tmp/thumbs/`
3. 用户浏览缩略图快速判断会议重点

**示例命令：**

```bash
# 免费版支持最多 10 张缩略图
{baseDir}/scripts/frame.sh /videos/meeting.mp4 --thumbs 6 --out /tmp/thumbs/
```

### 场景 3：学习笔记配图整理

小王在观看技术教程视频时，希望把关键操作步骤截图保存到笔记中。

**操作步骤：**

1. 告诉 Agent：「从教程视频的 2:15、5:30、8:45 三个时间点各抓一张 PNG」
2. Agent 依次执行三次单帧抓取
3. 用户将图片插入笔记文档

**示例命令：**

```bash
{baseDir}/scripts/frame.sh /videos/tutorial.mp4 --time 00:02:15 --out /tmp/step-1.png
{baseDir}/scripts/frame.sh /videos/tutorial.mp4 --time 00:05:30 --out /tmp/step-2.png
{baseDir}/scripts/frame.sh /videos/tutorial.mp4 --time 00:08:45 --out /tmp/step-3.png
```

## 不适用场景

以下场景视频帧提取-免费版不适合处理：

- 版权受保护的媒体内容处理
- 实时直播推流
- 专业影视后期

## 触发条件

需要视频处理、音频编辑、媒体转换、配音生成时使用。不适用于非本工具能力范围的需求。

## 快速开始

### 第一步：环境检查

确认本地已安装 `ffmpeg`：

```bash
ffmpeg -version
```

若未安装，请参考「依赖说明」章节完成安装。

### 第二步：抓取首帧

最简单的用法 - 抓取视频第一帧：

```bash
{baseDir}/scripts/frame.sh /path/to/video.mp4 --out /tmp/first-frame.jpg
```

### 第三步：指定时间点抓取

抓取第 10 秒的画面：

```bash
{baseDir}/scripts/frame.sh /path/to/video.mp4 --time 00:00:10 --out /tmp/frame-10s.jpg
```

### 第四步：生成缩略图

为长视频生成预览缩略图：

```bash
{baseDir}/scripts/frame.sh /path/to/video.mp4 --thumbs 8 --out /tmp/thumbs/
```

**结果处理**: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。


## 示例

### 基础配置

```yaml
# 免费版默认配置
video_frames_free:
  max_thumbnails: 10          # 最大缩略图数量
  default_format: jpg         # 默认输出格式
  default_quality: 2           # JPEG 质量（2=最佳）
  supported_inputs:
    - mp4
    - mov
    - avi
    - mkv
    - webm
  supported_outputs:
    - jpg
    - png
```

### 输出格式对比

| 格式 | 适用场景 | 文件大小 | 画质 |
|:-----|:---------|:---------|:-----|
| JPG | 快速分享、网络传输 | 较小 | 有损 |
| PNG | UI 截图、需要透明度 | 较大 | 无损 |

## 最佳实践

### 1. 选择合适的时间点

- 使用 `--time` 参数精准定位关键画面
- 时间格式为 `HH:MM:SS`（如 `00:01:30` 表示 1 分 30 秒）
- 推荐先抓取多张缩略图预览，再选择最佳时间点

### 2. 根据用途选择格式

```bash
# 网络分享用 JPG（体积小）
{baseDir}/scripts/frame.sh video.mp4 --time 00:00:05 --out /tmp/share.jpg

# UI 设计稿用 PNG（无损画质）
{baseDir}/scripts/frame.sh video.mp4 --time 00:00:05 --out /tmp/ui-frame.png
```

### 3. 缩略图数量建议

| 视频时长 | 建议缩略图数 |
|:---------|:------------|
| < 1 分钟 | 3-4 张 |
| 1-5 分钟 | 4-6 张 |
| 5-30 分钟 | 6-8 张 |
| > 30 分钟 | 8-10 张 |

### 4. 输出目录管理

建议为不同项目创建独立目录：

```bash
mkdir -p /tmp/frames/project-a
mkdir -p /tmp/frames/project-b
```

## 常见问题

### Q1：提示 ffmpeg 未找到怎么办？

**A：** 请先安装 ffmpeg：

- **Windows**：`winget install ffmpeg` 或下载官方压缩包
- **macOS**：`brew install ffmpeg`
- **Linux（Ubuntu/Debian）**：`sudo apt install ffmpeg`

### Q2：抓取的画面是黑屏？

**A：** 可能原因：

1. 视频开头是黑屏过渡，建议改用 `--time 00:00:03` 或更晚时间点
2. 视频编码特殊，尝试加上 `-vsync vfr` 参数
3. 视频损坏，请先用 `ffmpeg -i video.mp4` 检查完整性

### Q3：免费版最多能生成多少张缩略图？

**A：** 免费版单次最多 10 张。如需更多，可分多次执行，或升级至 PRO 版本（支持 100+ 张批量生成）。

### Q4：支持哪些视频格式？

**A：** 免费版支持所有 ffmpeg 可解码的格式，包括 mp4、mov、avi、mkv、webm、flv 等主流格式。

### Q5：能否从网络 URL 直接抓帧？

**A：** 免费版仅支持本地视频文件。请先下载视频到本地后再执行抓帧。PRO 版本支持直接输入 URL。

### Q6：缩略图清晰度不够？

**A：** 默认输出为原始分辨率。如需调整，可手动修改 ffmpeg 参数（PRO 版本内置分辨率调整功能）：

```bash
ffmpeg -ss 00:00:10 -i video.mp4 -vf scale=1280:-1 -frames:v 1 output.jpg
```

## 依赖说明

### 运行环境

- **Agent 平台**：支持 SKILL.md 规范的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
- **Python**：3.8+（部分脚本依赖）
- **Shell**：Bash 或兼容 Shell（Windows 用户建议使用 Git Bash）

### 依赖详情

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| ffmpeg | 命令行工具 | 必需 | 系统包管理器安装 |
| LLM API | API | 必需 | 由 Agent 内置 LLM 提供 |
| Python 3 | 运行时 | 可选 | python.org 官网下载 |

#### ffmpeg 安装命令

```bash
# Windows (PowerShell)
winget install Gyan.FFmpeg

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt update && sudo apt install ffmpeg

# CentOS / RHEL
sudo yum install epel-release && sudo yum install ffmpeg
```

### API Key 配置

- 本 Skill 纯本地运行，**无需任何 API Key**
- 所有视频处理均在本地完成，不上传至云端
- 如需配合云存储使用，请参考相关云服务文档

### 可用性分类

- **分类**：MD+EXEC（Markdown 指令 + 命令行执行）
- **说明**：通过自然语言指令驱动 Agent 调用 `ffmpeg` 完成视频帧提取
- **离线可用**：是（完全本地运行，无需网络）
- **隐私等级**：高（视频数据不离开本地）

## 版本说明

- **当前版本**：1.0.0
- **版本类型**：FREE（免费版）
- **升级路径**：如需批量处理、区间剪辑、自定义分辨率、水印添加等高级能力，请使用 `video-frames-tool-pro`

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 已知限制

- 需LLM支持,无LLM环境不可用
- 复杂业务场景建议结合人工经验判断
- 执行效率受模型能力与网络环境影响