Video-to-GIF Conversion Skill

This skill converts video files to optimized GIF animations using FFmpeg two-pass palette optimization.

Overview

The two-pass conversion process generates superior quality GIFs compared to single-pass approaches. Pass one analyzes the video and creates an optimized color palette. Pass two applies that palette to produce the final GIF with better color fidelity and smaller file sizes.

Response Format

After successful conversion, include a file link to the GIF in the response with the absolute file path:

/absolute/path/to/filename.gif

This allows the user to open the file and review it.

Prerequisites

FFmpeg is required and must be available in your system PATH.

macOS

brew install ffmpeg

Linux (Debian/Ubuntu)

sudo apt update && sudo apt install ffmpeg

Windows

Using Chocolatey:

choco install ffmpeg

Using winget:

winget install FFmpeg.FFmpeg

Verify installation:

ffmpeg -version

Quick Start

Convert a video using default settings (10 FPS, 1280px width, sierra2_4a dithering):

scripts/convert.sh input.mp4

scripts/convert.ps1 -InputPath input.mp4

Output saves to

input.gif

File Search Behavior

When a filename is provided without a full path, the script searches in this order:

1. Current working directory
2. Workspace root (if inside a project)

3. ~/Movies/

   (macOS) or

   ~/Videos/

   (Linux)

4. ~/Downloads/

5. ~/Desktop/

This allows natural commands like

convert.sh demo.mov

HDR Handling

The script automatically detects HDR video content via ffprobe by checking for BT.2020 color primaries or SMPTE 2084 transfer characteristics. When HDR is detected, tonemapping is applied automatically to produce SDR-compatible GIF output with proper color preservation.

Use

--tonemap

Parameters Reference

--input

-InputPath

--output

-OutputPath

input.gif

--fps

-Fps

--width

-Width

--dither

-Dither

--tonemap

-Tonemap

--skip-palette

-SkipPalette

--start

-Start

--duration

-Duration

--loop

-Loop

Frame Rate (FPS)

FPS controls animation smoothness and file size. Lower values reduce file size but create choppier motion.

Width

Width sets the output horizontal resolution in pixels. Height scales proportionally to maintain aspect ratio.

Dithering Algorithms

Dithering determines how the 256-color GIF palette approximates the original colors.

Time Range Selection

Use

--start

--duration

# Start at 5 seconds, convert 10 seconds
scripts/convert.sh --input video.mp4 --start 5 --duration 10

Loop Control

Use

--loop

Two-Pass vs Single-Pass

Two-Pass (Default)

Two-pass conversion creates a custom palette from the source video, then applies it:

# Pass 1: Generate palette
ffmpeg -i input.mp4 \
  -vf "fps=10,scale=1280:-1:flags=lanczos,palettegen=stats_mode=diff" \
  -y /tmp/palette.png

# Pass 2: Create GIF
ffmpeg -i input.mp4 -i /tmp/palette.png \
  -filter_complex "fps=10,scale=1280:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=sierra2_4a:diff_mode=rectangle" \
  -loop 0 -y output.gif

Two-pass produces better color accuracy and typically smaller files.

Single-Pass

Single-pass skips palette generation and uses FFmpeg's default 256-color palette:

ffmpeg -i input.mp4 \
  -vf "fps=10,scale=1280:-1:flags=lanczos" \
  -loop 0 -y output.gif

Single-pass processes faster but produces lower quality output with potential color banding.

Use single-pass via

--skip-palette

-SkipPalette

Script Reference

convert.sh (Bash)

# Basic usage
scripts/convert.sh video.mp4

# Custom output path
scripts/convert.sh --input video.mp4 --output demo.gif

# Adjust quality parameters
scripts/convert.sh --input video.mp4 --fps 15 --width 640 --dither floyd_steinberg

# HDR video with custom tonemapping
scripts/convert.sh --input hdr-video.mov --tonemap reinhard

# Extract a 10-second clip starting at 5 seconds
scripts/convert.sh --input video.mp4 --start 5 --duration 10

# Create a GIF that plays only once
scripts/convert.sh --input video.mp4 --loop 1

# Fast single-pass mode
scripts/convert.sh --input video.mp4 --skip-palette

convert.ps1 (PowerShell)

# Basic usage
scripts/convert.ps1 -InputPath video.mp4

# Custom output path
scripts/convert.ps1 -InputPath video.mp4 -OutputPath demo.gif

# Adjust quality parameters
scripts/convert.ps1 -InputPath video.mp4 -Fps 15 -Width 640 -Dither floyd_steinberg

# HDR video with custom tonemapping
scripts/convert.ps1 -InputPath hdr-video.mov -Tonemap reinhard

# Extract a 10-second clip starting at 5 seconds
scripts/convert.ps1 -InputPath video.mp4 -Start 5 -Duration 10

# Create a GIF that plays only once
scripts/convert.ps1 -InputPath video.mp4 -Loop 1

# Fast single-pass mode
scripts/convert.ps1 -InputPath video.mp4 -SkipPalette

Examples

HDR Video Conversion

HDR content is detected automatically. No special flags are needed:

scripts/convert.sh hdr-footage.mov

The script applies hable tonemapping by default. Use

--tonemap

# Use reinhard for more saturated colors
scripts/convert.sh --input hdr-footage.mov --tonemap reinhard

Time Range Extraction

Extract a specific segment from a longer video:

# Convert seconds 30-45 of a screencast
scripts/convert.sh --input screencast.mp4 --start 30 --duration 15 --fps 15

Documentation Thumbnails

Create compact thumbnails for documentation:

scripts/convert.sh --input demo.mp4 --width 320 --fps 8

Troubleshooting

FFmpeg not found

Verify FFmpeg is in your PATH:

which ffmpeg  # macOS/Linux
where.exe ffmpeg  # Windows

If FFmpeg is installed but not found, add its directory to your PATH environment variable.

File not found

Ensure the file exists at the specified path. If providing only a filename, the script searches the workspace first, then common directories (

~/Movies/

~/Downloads/

~/Desktop/

Output file is too large

Reduce file size with these adjustments:

• Lower FPS (try 8 or 5)
• Reduce width (try 640 or 320)
• Use

  bayer

  dithering for faster processing
• Use

  --duration

  to convert only a portion of the video

Colors appear washed out

Switch to

floyd_steinberg

none

HDR content looks wrong

Ensure FFmpeg 4.0+ is installed with zscale filter support. The script requires libzimg for HDR tonemapping. Install via:

# macOS
brew install zimg
brew reinstall ffmpeg

# Ubuntu
sudo apt install libzimg-dev

If colors still appear off, try a different tonemapping algorithm with

--tonemap

reinhard

bt2390

Conversion fails with filter error

Ensure FFmpeg version 4.0 or later is installed. The

palettegen

paletteuse

ffmpeg -version

Temporary palette file remains

The scripts clean up

/tmp/palette.png

$env:TEMP\palette.png

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.