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 | Description | Example |
|---|---|---|
| output_path | Directory to save extracted frames | Default: ./tmp/frames |
| frame_rate | Frames per second to extract | 0.25 (1 frame every 4 seconds) |
| scale | Short side resize target in pixels (optional) | 640 (short side → 640px) |
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:
| Flag | Purpose |
|---|---|
-hide_banner |
Suppress build info |
-loglevel error |
Quiet mode, show only errors |
-thread_queue_size 512 |
Increase thread queue for large files |
-vf "fps={rate}" |
Set frame extraction rate |
-fps_mode vfr |
Variable frame rate (skip duplicates) |
-q:v 2 |
JPEG quality (1-31, lower = better) |
-atomic_writing 1 |
Atomic file write (prevent corruption) |
%06d.jpg |
Sequential naming: 000001.jpg, 000002.jpg... |
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
- Download from: https://www.gyan.dev/ffmpeg/builds/
- Extract to a permanent location (e.g.,
C:\tools\ffmpeg) - Add to PATH:
setx PATH "$PATH;C:\tools\ffmpeg\bin - 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
| Error | Solution |
|---|---|
ffmpeg: command not found |
Install FFmpeg first |
No such file or directory |
Check video_path is correct |
Permission denied |
Check write permissions for output_path |
Output directory not empty |
Clear or use different output path |
Notes
- FFmpeg is much faster than OpenCV for frame extraction (10-100x)
- The scale filter uses
-2instead of-1to ensure dimensions are divisible by 2 (better codec compatibility) -fps_mode vfr(variable frame rate) skips duplicate frames when seeking- Use
-q:v 2for high quality JPEG (range 1-31, default 31)