Skill: Video to GIF

Convert a video file into multiple GIF variants with different parameters, so the user can visually compare and pick the best one.

Prerequisite: FFmpeg and uv must be installed. gifsicle is optional (enables lossy compression variants).

When to Use

The user wants to create a GIF from a video clip but isn't sure about the right parameters. GIF quality involves tradeoffs between:

• File size — smaller is better for sharing/embedding

• Color accuracy — fewer colors = smaller but may cause banding

• Smoothness — higher FPS = smoother but larger

• Resolution — wider = sharper detail but larger

Rather than guessing, this skill generates multiple variants and lets the user decide.

Default Workflow

When the user provides a video file:

uv run --python 3.12 /path/to/skills/video-to-gif/scripts/video_to_gif.py <input.mp4>

This generates GIFs in <input>_gifs/ directory with the full preset (18 variants):

• 3 FPS options: 10, 15, 20

• 3 widths: 480px, 640px, 800px

• 2 color counts: 128, 256

Output includes a sorted comparison table showing file size, FPS, width, and colors for each variant.

Presets

Preset

Variants

Best For

full

~18

General use — broad exploration of the parameter space

minimal

~4

Quick comparison — just a few key tradeoff points

lossy

~12

Smallest files — includes gifsicle lossy compression levels

quality

~12

Best visuals — higher res, includes bayer dithering

# Quick comparison with fewer variants

uv run --python 3.12 .../video_to_gif.py input.mp4 --presets minimal

# Include lossy compression (requires gifsicle)

uv run --python 3.12 .../video_to_gif.py input.mp4 --presets lossy

# Higher quality focus

uv run --python 3.12 .../video_to_gif.py input.mp4 --presets quality

Common Options

Flag

Default

Description

-o, --output-dir

<input>_gifs/

Output directory for all GIF variants

--start

none

Start time in seconds (trim source)

--end

none

End time in seconds (trim source)

--presets

full

Preset config: full, minimal, lossy, quality

--fps

preset

Override FPS values (e.g., --fps 10 15 20)

--width

preset

Override width values (e.g., --width 480 640)

--colors

preset

Override color counts (e.g., --colors 128 256)

--lossy

preset

Gifsicle lossy levels (e.g., --lossy 0 30 80)

Examples

# Convert first 10 seconds of a video

uv run --python 3.12 .../video_to_gif.py demo.mp4 --end 10

# Extract a specific segment

uv run --python 3.12 .../video_to_gif.py demo.mp4 --start 5 --end 15

# Custom parameter sweep

uv run --python 3.12 .../video_to_gif.py demo.mp4 --fps 12 15 --width 480 800 --colors 256

# Lossy compression comparison (needs gifsicle)

uv run --python 3.12 .../video_to_gif.py demo.mp4 --lossy 0 30 60 100

How to Choose

After running, open the output directory and compare:

• Start with the smallest files — check if quality is acceptable

• Look for color banding — if visible, try 256 colors or bayer dithering (quality preset)

• Check smoothness — if too choppy, go up to 15 or 20 FPS

• Check clarity — if text is unreadable, go up to 640 or 800px width

The sweet spot for most screen recordings is usually around 640px, 15fps, 256 colors.

Important Notes

• Widths larger than the source video resolution are automatically skipped.

• The script uses FFmpeg's two-pass palette generation for optimal GIF quality (much better than single-pass).

• Lossy compression via gifsicle can reduce file size by 30-70% with minimal visual impact at level 30-60.

• For very long clips, consider trimming with --start/--end first — GIFs over 10 seconds can get very large.