GIF Creation

Create high-quality, optimized GIFs from videos or image sequences using FFmpeg’s 2-pass palette generation technique.

Quick Start

Create a GIF from video:

cd ~/.claude/scripts/media-tools
bun run gif video.mp4 --Width 480 --FPS 15

Intelligent Behavior

Automatically detects source type and uses appropriate method:

CLI Options

Features

2-Pass Processing:

• Pass 1: Generate optimized color palette
• Pass 2: Create GIF using palette
• Result: Better quality and smaller file size

Optimization Presets:

Loop Options:

• infinite – Loop forever (default, best for web)
• once – Play once and stop
• custom – Specify loop count

Usage Examples

Video to GIF – basic

bun run gif video.mp4

Default settings: 480px width, 15 FPS, full duration, infinite loop, balanced optimization.

Video to GIF – first 5 seconds

bun run gif video.mp4 --Duration 5

Video to GIF – custom clip

bun run gif video.mp4 --Start custom --Duration custom --Width 640

Prompts for timing:

Enter start time (HH:MM:SS or seconds): 00:00:30
Enter duration (seconds or HH:MM:SS): 10

Video to GIF – small file size

bun run gif video.mp4 --Width 320 --FPS 12 --Optimize size

Video to GIF – high quality

bun run gif video.mp4 --Width 800 --FPS 24 --Optimize quality

Image sequence to GIF

bun run gif ./frames/ --FPS 24 --Width 640

Image sequence – specific pattern

bun run gif "frame_*.png" --FPS 15 --Loop once

Size Estimation

Approximate file sizes for different settings:

Factors affecting size:

• Width: Larger = bigger files
• FPS: More frames = bigger files
• Duration: Longer = bigger files
• Content: Complex scenes with motion = bigger files
• Optimize: quality > balanced > size

Processing Preview

Before creating GIF, shows preview and confirmation:

Creating GIF from: video.mp4

Source:
- Duration: 0:15
- Resolution: 1920x1080
- FPS: 30

Output settings:
- Width: 480px (auto height: 270px)
- FPS: 15 (half source FPS)
- Duration: 5 seconds (from 0:03)
- Loop: infinite
- Optimize: balanced

Estimated size: ~3-5 MB
Processing time: ~10-15 seconds

Proceed? [Yes/No]

2-Pass Processing

From Video

Pass 1 – Generate palette:

ffmpeg -ss 00:00:03 -t 5 -i video.mp4 \
  -vf "fps=15,scale=480:-1:flags=lanczos,palettegen=stats_mode=diff" \
  -y /tmp/palette.png

Pass 2 – Create GIF:

ffmpeg -ss 00:00:03 -t 5 -i video.mp4 -i /tmp/palette.png \
  -lavfi "fps=15,scale=480:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5" \
  -loop 0 \
  output.gif

From Image Sequence

With FFmpeg:

ffmpeg -framerate 15 -pattern_type glob -i "frames/*.png" \
  -vf "scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  -loop 0 \
  output.gif

With ImageMagick (alternative):

magick -delay 6 frames/*.png \
  -resize 480x \
  -layers optimize \
  output.gif

Note: Delay calculation: 100 / FPS (e.g., 15 FPS = 6.67ms ≈ 6)

Additional Optimization

For even smaller files, use gifsicle (optional):

gifsicle -O3 --lossy=80 output.gif -o output_optimized.gif

Lossy compression levels:

• --lossy=30 – Minimal quality loss
• --lossy=80 – Good balance
• --lossy=200 – Maximum compression

Processing Results

✓ GIF created successfully

Output: video.gif
- Size: 4.2 MB
- Dimensions: 480 x 270
- Frames: 75 (5s @ 15fps)
- Duration: 5 seconds
- Loop: infinite

Performance:
- Pass 1 (palette): 2.1s
- Pass 2 (encoding): 8.4s
- Total time: 10.5s

Tip: Use --Optimize size for smaller files or --Width 320 to reduce size further

Best Practices

1. Reduce file size:

   • Lower FPS (12-15 works well for most content)
   • Smaller width (480px or less)
   • Use “size” optimization preset
   • Trim to shortest necessary duration

2. Better quality:

   • Higher FPS (24-30 for smooth motion)
   • Larger width (640-800px)
   • Use “quality” optimization preset

3. Smooth motion:

   • Use 24+ FPS for fast action
   • Use 12-15 FPS for simple content or talking heads

4. Social media:

   • Most platforms compress GIFs automatically
   • Upload slightly higher quality than needed
   • Test file size limits (Twitter: 5MB, Discord: 8MB)

5. Performance:

   • Shorter clips process faster
   • Lower resolution = faster encoding
   • 2-pass method is slower but produces better results

Platform Limits

Requirements

• FFmpeg – Required for video processing
• ImageMagick 7+ – Optional for image sequences
• gifsicle – Optional for additional optimization

Install all:

brew install ffmpeg imagemagick gifsicle

Verify FFmpeg:

ffmpeg -version | head -n 1

Related Files

• Command: plugins/media-tools/commands/gif.md
• Video Processing: plugins/media-tools/skills/video-processing/
• Media Processor: plugins/media-tools/skills/media-processor/