video-frames（视频帧）

Video-Frames Skill

Production-grade video frame extraction with comprehensive quality control, progress tracking, and safety limits.

When to Use

✅ USE this skill when:

• Extracting specific frames from videos at timestamps
• Creating thumbnail grids/contact sheets for video overview
• Generating animated GIFs from video segments
• Batch extracting frames at intervals (e.g., every N seconds)
• Creating video previews or storyboards
• Needing pixel-perfect frame access by index
• Extracting frames at specific quality levels

❌ DON'T use this skill when:

• Simple format conversion → Use ffmpeg-tools
• Video editing (effects) → Use video editor
• Real-time frame capture → Use streaming tools
• Video capture from camera → Use camsnap
• Image generation → Use image-gen

Prerequisites

# Install FFmpeg
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Ubuntu/Debian

# Optional: Install ImageMagick for better grid generation
brew install imagemagick   # macOS
sudo apt install imagemagick   # Ubuntu

# Verify installation
ffmpeg -version
ffprobe -version

Commands

1. Extract Single Frame

Extract a single frame at a specific time or by frame index.

# Extract frame at timestamp
{baseDir}/video-frames.js frame video.mp4 --time 30 --out frame.jpg
{baseDir}/video-frames.js frame video.mp4 --time 00:02:30 --out frame.jpg
{baseDir}/video-frames.js frame video.mp4 --time 150.5 --out frame.jpg

# Extract by frame index
{baseDir}/video-frames.js frame video.mp4 --index 0 --out first-frame.jpg
{baseDir}/video-frames.js frame video.mp4 --index 1000 --out frame-1000.jpg

# With quality settings
{baseDir}/video-frames.js frame video.mp4 --time 30 --format png --out high-quality.png
{baseDir}/video-frames.js frame video.mp4 --time 30 --quality 1 --out best-quality.jpg
{baseDir}/video-frames.js frame video.mp4 --time 30 --format jpg --quality 2

Time Formats:

Quality Settings (JPEG):

Supported Formats:

• jpg/jpeg - Web optimized, compression
• png - Lossless, transparency, best quality
• bmp - Uncompressed raw
• tiff - Professional formats
• webp - Next-gen web format

2. Extract Multiple Frames

Batch extract frames at regular intervals.

# Extract 1 frame per second
{baseDir}/video-frames.js frames video.mp4 --fps 1

# Extract specific segment
{baseDir}/video-frames.js frames video.mp4 --fps 1 --start 00:01:00 --duration 60
{baseDir}/video-frames.js frames video.mp4 --fps 5 --start 30 --duration 120

# Higher quality extraction
{baseDir}/video-frames.js frames video.mp4 --fps 1 --quality 1 --prefix keyframe

# Resize during extraction
{baseDir}/video-frames.js frames video.mp4 --fps 1 --width 1920 --quality 1

Frame Rate Options:

Output:

/tmp/frames_1234567890/
  ├── frame_00001.jpg
  ├── frame_00002.jpg
  ├── frame_00003.jpg
  └── ...

3. Generate Thumbnail Grid (Contact Sheet)

Create a grid of thumbnails for video overview.

# Basic grid
{baseDir}/video-frames.js grid video.mp4 --output grid.jpg

# Custom size and layout
{baseDir}/video-frames.js grid video.mp4 --count 16 --columns 4 --width 480 --out grid.jpg

# Compact preview
{baseDir}/video-frames.js grid video.mp4 --count 20 --columns 5 --width 320 --out overview.jpg

# High resolution grid
{baseDir}/video-frames.js grid video.mp4 --count 9 --columns 3 --width 640 --format png --out detailed.png

Grid Layout Examples:

Output Format:

+---+---+---+---+
| 1 | 2 | 3 | 4 |    <- 5 seconds into video
+---+---+---+---+
| 5 | 6 | 7 | 8 |    <- 25 seconds into video
+---+---+---+---+
| 9 |10 |11 |12 |    <- 45 seconds into video
+---+---+---+---+

4. Create Animated GIF

Extract video segment as animated GIF.

# Basic GIF (5 seconds from start)
{baseDir}/video-frames.js gif video.mp4 --output clip.gif

# Specific time and duration
{baseDir}/video-frames.js gif video.mp4 --start 00:01:30 --duration 5 --out highlight.gif
{baseDir}/video-frames.js gif video.mp4 --start 30 --duration 10 --out segment.gif

# Quality presets
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset fast --out quick.gif
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset quality --out smooth.gif
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset cinematic --out cinema.gif

# Custom parameters
{baseDir}/video-frames.js gif video.mp4 --start 30 --duration 5 --fps 30 --width 720 --out preview.gif

GIF Presets:

Max Duration: 300 frames (~10 seconds at 30fps)

5. Get Video Information

Display detailed video metadata.

{baseDir}/video-frames.js info video.mp4

Output:

{
  "stats": { "size": 1234567890, "mtime": "..." },
  "duration": 3665,
  "width": 1920,
  "height": 1080,
  "fps": 29.97,
  "totalFrames": 109785,
  "info": { ... }  // Full ffprobe output
}

Progress Tracking

Operations display real-time progress:

⏳ Extracting frames: 15/30 (50.0%) | Elapsed: 12.3s
⏳ Generating thumbnails: 8/12 (66.7%) | Elapsed: 5.2s

Safety Features

Limits

Video Validation

Before processing, the skill validates:

• File exists and is readable
• File size within limits
• Valid video format
• Duration within limits
• Contains video stream
• Not corrupted

Error Handling

Error Codes

Common Scenarios

Frame Index Out of Range:

{baseDir}/video-frames.js frame video.mp4 --index 999999
# ❌ ERROR: Frame index 999999 out of range (0-109784)

Timestamp Beyond Video:

{baseDir}/video-frames.js frame video.mp4 --time 10000
# ❌ ERROR: Timestamp 02:46:40 out of range (0-01:01:05)

Too Many Frames:

{baseDir}/video-frames.js frames video.mp4 --fps 100
# ❌ ERROR: Too many frames requested: 366500 (max: 1000)

Large GIF Request:

{baseDir}/video-frames.js gif video.mp4 --duration 60 --fps 60
# ❌ ERROR: GIF too long: 3600 frames (max: 300)

Technical Details

Frame Extraction Methods

1. Segment Seek (-ss before -i)

- Fast frame access - Use for --time option - Slight accuracy trade-off at start

1. Frame Selection (-vf select)

- Precise frame index extraction - Slower but frame-accurate - Use for --index option

1. Extract at Interval (fps filter)

- Efficient batch extraction - Frame-rate conversion - Use for batch operations

Quality Settings

JPEG Quality (CRF - Constant Rate Factor):

-q:v 1  -> 100% quality (best, largest)
-q:v 2  -> ~95% quality (default)
-q:v 5  -> ~85% quality (web)
-q:v 10 -> ~70% quality (low)
-q:v 31 -> ~10% quality (minimum)

PNG Output:

• Always lossless
• Larger file sizes
• Best for archival
• Transparent backgrounds supported

Scaling (Lanczos):

-vf scale=320:-2:flags=lanczos

• Lanczos resampling for best quality
• -2 ensures even dimensions (encoding requirement)
• Maintains aspect ratio

GIF Optimization

Palette Generation:

1. Parse video segment
2. Generate optimal 256-color palette
3. Apply palette to all frames
4. Dithering for smooth gradients

File Size Optimization:

• Fixed frame rate
• Limited color palette
• Resizing before encoding
• Optimized encoding settings

Examples

Video Storyboard Creation

#!/bin/bash
VIDEO="movie.mp4"
OUTDIR="storyboard"

mkdir -p $OUTDIR

# Create overview grid
echo "Creating overview grid..."
{baseDir}/video-frames.js grid "$VIDEO" --count 20 --columns 5 --width 480 --out "$OUTDIR/overview.jpg"

# Extract key frames every minute
echo "Extracting key frames..."
{baseDir}/video-frames.js frames "$VIDEO" --fps 0.0167 --prefix key --out "$OUTDIR/"

# Create chapter thumbnails
echo "Creating chapter thumbnails..."
for time in 0:00 10:00 20:00 30:00; do
  {baseDir}/video-frames.js frame "$VIDEO" --time $time --quality 1 --out "$OUTDIR/chapter_${time//:/}.png"
done

echo "Storyboard complete in $OUTDIR/"

Video Preview Gallery

#!/bin/bash
for video in *.mp4; do
  echo "Processing: $video"

  # Create 3x3 grid
  {baseDir}/video-frames.js grid "$video" --count 9 --columns 3 --width 640 --out "${video%.*}-grid.jpg"

  # Create 5-second preview GIF
  {baseDir}/video-frames.js gif "$video" --start 30 --duration 5 --preset balanced --out "${video%.*}-preview.gif"

done

Extract Frames Every N Seconds

# Extract frame at beginning of every minute
for i in {0..60}; do
  {baseDir}/video-frames.js frame video.mp4 --time $((i*60)) --out "frames/minute_${i}.jpg"
done

# Shell script for batch extraction
extract_frames() {
  local video="$1"
  local interval="${2:-10}"  # default 10 seconds
  local duration
  duration=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$video")

  for ((t=0; t<duration; t+=interval)); do
    {baseDir}/video-frames.js frame "$video" --time $t --out "frames/frame_${t}.jpg"
  done
}

High-Quality Thumbnail Generation

# Best quality single frame
{baseDir}/video-frames.js frame video.mp4 \
  --time 10 \
  --format png \
  --width 1920 \
  --out thumbnail.png

# Best quality grid
{baseDir}/video-frames.js grid video.mp4 \
  --count 9 \
  --columns 3 \
  --width 640 \
  --format png \
  --out grid.png

Performance Tips

1. Use JPEG for Speed

JPEG encoding is faster than PNG:

{baseDir}/video-frames.js frame video.mp4 --format jpg  # Faster
{baseDir}/video-frames.js frame video.mp4 --format png  # Better quality, slower

2. Lower Quality for Drafts

# Quick preview
{baseDir}/video-frames.js grid video.mp4 --count 9 --width 320  # Small, fast

# Final quality
{baseDir}/video-frames.js grid video.mp4 --count 16 --width 640  # Higher detail

3. Parallel Processing

# Process multiple videos in parallel
{baseDir}/video-frames.js grid video1.mp4 --out g1.jpg &
{baseDir}/video-frames.js grid video2.mp4 --out g2.jpg &
{baseDir}/video-frames.js grid video3.mp4 --out g3.jpg &
wait

4. Resize During Extraction

Better than extracting full size then scaling:

# Good
{baseDir}/video-frames.js frame video.mp4 --width 320 --out thumb.jpg

# Less efficient
{baseDir}/video-frames.js frame video.mp4 --out full.jpg
# Then resize externally

Notes

• Grid generation uses ImageMagick when available (better quality), FFmpeg tile filter otherwise
• Frame index 0 is always the first frame of the video
• Timestamps are rounded to nearest frame based on video FPS
• GIFs are optimized with 256-color palette for balance of quality and size
• PNG transparency is preserved (useful for overlays)
• All operations clean up temporary files automatically
• JSON output enables programmatic integration
• Grid thumbnails include timestamps at video intervals