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 by default.

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 without specifying full paths.

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 to select the tonemapping algorithm:

Parameters Reference

Frame Rate (FPS)

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

Width

…