Video-to-GIF conversion skill with FFmpeg two-pass optimization - Brought to you by microsoft/hve-core
This skill converts video files to optimized GIF animations using FFmpeg two-pass palette optimization.
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.
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.
FFmpeg is required and must be available in your system PATH.
brew install ffmpeg
sudo apt update && sudo apt install ffmpeg
Using Chocolatey:
choco install ffmpeg
Using winget:
winget install FFmpeg.FFmpeg
Verify installation:
ffmpeg -version
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.
When a filename is provided without a full path, the script searches in this order:
~/Movies/ (macOS) or ~/Videos/ (Linux)~/Downloads/~/Desktop/This allows natural commands like convert.sh demo.mov without specifying full paths.
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:
| Algorithm | Characteristics |
|---|---|
| hable | Filmic curve, good highlight rolloff (default) |
| reinhard | Preserves more color saturation |
| mobius | Similar to reinhard with better highlights |
| bt2390 | ITU standard, more conservative |
| Parameter | Flag (bash) | Flag (PowerShell) | Default | Description |
|---|---|---|---|---|
| Input file | --input | -InputPath | (required) | Source video file path |
| Output file | --output | -OutputPath | input.gif | Destination GIF file path |
| Frame rate | --fps | -Fps | 10 | Frames per second |
| Width | --width | -Width | 1280 | Output width in pixels |
| Dithering | --dither | -Dither | sierra2_4a | Dithering algorithm |
| Tonemapping | --tonemap | -Tonemap | hable | HDR tonemapping algorithm |
| Skip palette | --skip-palette | -SkipPalette | false | Use single-pass mode |
| Start time | --start | -Start | 0 | Start time in seconds |
| Duration | --duration | -Duration | (full video) | Duration to convert in seconds |
| Loop count | --loop | -Loop | 0 | GIF loop count (0 = infinite) |
FPS controls animation smoothness and file size. Lower values reduce file size but create choppier motion.
| FPS | Use Case |
|---|---|
| 5 | Simple animations, icons |
| 10 | General use (default) |
| 15 | Smooth motion, UI demos |
| 24 | Near-video quality |
Width sets the output horizontal resolution in pixels. Height scales proportionally to maintain aspect ratio.
| Width | Use Case |
|---|---|
| 320 | Thumbnails, previews |
| 640 | Documentation |
| 800 | Presentations |
| 1280 | High detail (default) |
Dithering determines how the 256-color GIF palette approximates the original colors.
| Algorithm | Quality | Speed | Best For |
|---|---|---|---|
| sierra2_4a | High | Medium | General use (default) |
| floyd_steinberg | High | Slow | Photographic content |
| bayer | Medium | Fast | Graphics with solid colors |
| none | Low | Fastest | Stylized/posterized look |
Use --start and --duration to convert a specific portion of the video:
# Start at 5 seconds, convert 10 seconds
scripts/convert.sh --input video.mp4 --start 5 --duration 10
Use --loop to control GIF repeat behavior:
| Value | Behavior |
|---|---|
| 0 | Loop forever |
| 1 | Play once |
| N | Play N times |
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 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 (bash) or -SkipPalette (PowerShell).
# 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
# 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
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 to try different algorithms:
# Use reinhard for more saturated colors
scripts/convert.sh --input hdr-footage.mov --tonemap reinhard
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
Create compact thumbnails for documentation:
scripts/convert.sh --input demo.mp4 --width 320 --fps 8
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.
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/). Use an absolute path if the file is in a different location.
Reduce file size with these adjustments:
bayer dithering for faster processing--duration to convert only a portion of the videoSwitch to floyd_steinberg dithering for photographic content. Avoid none dithering unless a stylized look is intended.
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. The reinhard algorithm preserves more saturation, while bt2390 provides more conservative results.
Ensure FFmpeg version 4.0 or later is installed. The palettegen and paletteuse filters require this version.
ffmpeg -version
The scripts clean up /tmp/palette.png (or $env:TEMP\palette.png on Windows) automatically. If conversion fails mid-process, remove this file manually.
🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.