video-frame-extractor（视频帧提取器）

Video Frame Extractor

Overview

This skill guides LLM agents to extract frames from video files using FFmpeg. It provides complete workflow for frame extraction including environment setup, parameter configuration, and command execution.

Primary method: FFmpeg (fast and reliable) Fallback method: OpenCV (if FFmpeg unavailable)

Workflow

Step 1: Verify FFmpeg Installation

Before extracting frames, check if FFmpeg is installed:

ffmpeg -version

If FFmpeg is not installed, see FFmpeg Installation section below.

Step 2: Determine Extraction Parameters

Before extracting frames, the LLM MUST confirm these parameters with the user:

Parameter Calculation Guide:

• To extract 1 frame every X seconds: frame_rate = 1/X
• Example: 1 frame every 4 seconds → frame_rate = 0.25
• Example: 1 frame every 10 seconds → frame_rate = 0.1
• Example: 1 frame per second → frame_rate = 1

Step 3: Execute FFmpeg Command

Generate and execute the FFmpeg command:

Basic Command (no resize):

ffmpeg -hide_banner -loglevel error -i "{video_path}" -vf "fps={frame_rate}" -fps_mode vfr -q:v 2 -f image2 "{output_path}/%06d.jpg"

With Short Side Resize (recommended for analysis):

ffmpeg -hide_banner -loglevel error -thread_queue_size 512 -i "{video_path}" -vf "fps={frame_rate},scale='if(gt(iw,ih),-2,{scale}):if(gt(iw,ih),{scale},-2)':flags=lanczos" -fps_mode vfr -q:v 2 -f image2 -atomic_writing 1 "{output_path}/%06d.jpg"

Parameter Breakdown:

Step 4: Verify Output

After extraction, verify the output:

• Count frames: ls {output_path}/*.jpg | wc -l
• Check frame sizes: ls -lh {output_path}/*.jpg | head -5

FFmpeg Installation

Windows

Option 1: winget (Recommended)

winget install ffmpeg

Option 2: Chocolatey

choco install ffmpeg

Option 3: Manual Download

1. Download from: https://www.gyan.dev/ffmpeg/builds/
2. Extract to a permanent location (e.g., C:\ ools\ffmpeg)
3. Add to PATH: setx PATH "$PATH;C:\ ools\ffmpeg\bin
4. Restart terminal

Verify Installation:

ffmpeg -version

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Verify Installation:

ffmpeg -version

Linux (CentOS/RHEL/Fedora)

sudo dnf install ffmpeg

macOS

brew install ffmpeg

Common Use Cases

Extract 1 frame every 4 seconds, resize to 640px

frame_rate = 0.25
scale = 640

Extract 1 frame every 10 seconds, original size

frame_rate = 0.1
scale = 0 (no resize)

Extract 1 frame per second for a 10-minute video (600 frames)

frame_rate = 1
video_duration = 600 seconds
expected_frames = 600

Output Directory Structure

Frames are saved with sequential naming:

output_path/
├── 000001.jpg
├── 000002.jpg
├── 000003.jpg
└── ...

The sequential naming (%06d) ensures frames are in temporal order regardless of original frame numbers.

Error Handling

Notes

• FFmpeg is much faster than OpenCV for frame extraction (10-100x)
• The scale filter uses -2 instead of -1 to ensure dimensions are divisible by 2 (better codec compatibility)
• -fps_mode vfr (variable frame rate) skips duplicate frames when seeking
• Use -q:v 2 for high quality JPEG (range 1-31, default 31)