algorembrant/vid-to-gif

vid2gif

A fast, robust, command-line video-to-GIF converter built on a two-pass FFmpeg palette pipeline with optional gifsicle post-compression.
Supports single-file conversion, time-clipping, custom palettes, dithering algorithms, and fully parallelised batch processing.

---

Table of Contents

• Features
• Dependencies
• Installation
• Quick Start
• Usage
• Command Reference
• Batch Mode
• Dithering Algorithms
• Performance Tips
• Project Structure
• License

---

Features

• Two-pass FFmpeg palette generation for maximum colour fidelity
• Lanczos-scaled output with configurable resolution and frame rate
• Per-file time clipping (start time and duration)
• Parallel batch conversion with configurable worker count
• Optional gifsicle level-3 post-compression
• Zero mandatory Python dependencies (stdlib only for the core engine)
• Cross-platform: Linux, macOS, Windows

---

Dependencies

Required external binaries

Tool	Purpose	Installation
ffmpeg	Video decoding, palette generation, GIF rendering	See ffmpeg.org/download

Optional external binaries

Tool	Purpose	Installation
gifsicle	Post-process GIF compression (level 3)	See lcdf.org/gifsicle

Python packages (optional)

Package	Purpose
tqdm	Progress bars in batch mode
Pillow	Post-processing / thumbnail generation
colorlog	Coloured log output

---

Installation

1. Install FFmpeg

Linux (Debian/Ubuntu)

sudo apt update && sudo apt install ffmpeg -y

Linux (Fedora/RHEL)

sudo dnf install ffmpeg -y

macOS (Homebrew)

brew install ffmpeg

Windows

1. Download a pre-built binary from https://ffmpeg.org/download.html (select the Windows build by BtbN or gyan.dev).
2. Extract the archive (e.g. to C:\ffmpeg).
3. Add C:\ffmpeg\bin to your system PATH environment variable.
4. Verify: open a new terminal and run ffmpeg -version.

2. Install gifsicle (optional but recommended)

Linux (Debian/Ubuntu)

sudo apt install gifsicle -y

macOS

brew install gifsicle

Windows

1. Download the Windows binary from https://www.lcdf.org/gifsicle/.
2. Extract and place gifsicle.exe in a folder that is on your PATH.

3. Clone the repository

git clone https://github.com/algorembrant/vid2gif.git
cd vid2gif

4. Create a virtual environment and install Python dependencies

python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

pip install -r requirements.txt

---

Quick Start

# Convert a video to GIF with default settings
python vid2gif.py input.mp4 output.gif

# Preview what the tool detects
python vid2gif.py --verbose input.mp4 output.gif

---

Usage

usage: vid2gif [-h] [--batch DIR] [--output-dir DIR] [--extensions EXT [EXT ...]]
               [--start TIME] [--duration SECS]
               [--fps N] [--width PX] [--height PX] [--max-colors N]
               [--dither ALG] [--loop N] [--stats-mode {diff,full,single}]
               [--quality 1-100] [--no-optimize] [--threads N] [--workers N]
               [--verbose]
               [input] [output]

---

Command Reference

Positional arguments

Argument	Description
input	Path to the input video file
output	Path for the output GIF (defaults to <input>.gif)

Clip options

Flag	Default	Description
--start TIME / -s TIME	(none)	Start time — HH:MM:SS or seconds (e.g. 5, 00:00:05)
--duration SECS / -d SECS	(none)	Duration in seconds after the start point

Output options

Flag	Default	Description
--fps N	15	Output frame rate
--width PX	640	Output width in pixels
--height PX	-1	Output height (-1 = auto, preserves aspect ratio)
--max-colors N	256	Maximum palette colours (2 - 256)
--dither ALG	sierra2_4a	Dither algorithm (see table below)
--loop N	0	Loop count (0 = infinite)
--stats-mode	diff	Palette stats mode: diff, full, or single

Quality / optimization options

Flag	Default	Description
--quality 1-100	85	Quality hint passed to the rendering stage
--no-optimize	false	Disable gifsicle post-compression
--threads N	4	ffmpeg thread count per conversion

Batch options

Flag	Default	Description
--batch DIR	(none)	Directory to scan for video files
--output-dir DIR	./gifs	Output directory for batch results
--extensions EXT...	mp4 mkv mov avi webm flv wmv m4v	File extensions to match in batch mode
--workers N	4	Parallel worker threads for batch conversion

Miscellaneous

Flag	Description
--verbose / -v	Enable DEBUG-level logging
--help / -h	Show help and exit

---

Batch Mode

Point --batch at any directory. vid2gif will discover all matching video files, convert them in parallel, and write results to --output-dir.

python vid2gif.py --batch ./videos/ --output-dir ./gifs/ --workers 8 --fps 12 --width 480

---

Dithering Algorithms

Algorithm	Notes
sierra2_4a	Default. Excellent balance of quality and file size
floyd_steinberg	Classic error-diffusion. High quality, slightly larger
sierra2	Slightly smoother than sierra2_4a
bayer	Ordered dither. Fast, lower quality
bayer:bayer_scale=1..5	Bayer with scale control (1 = fine, 5 = coarse)
heckbert	Median-cut based, good for flat-colour content
none	No dithering. Fastest, lowest quality

---

Usage Examples

# 1. Simple conversion (default settings)
python vid2gif.py clip.mp4 clip.gif

# 2. High frame rate, wide output
python vid2gif.py clip.mp4 clip.gif --fps 30 --width 1280

# 3. Extract a 10-second segment starting at 1 minute 30 seconds
python vid2gif.py clip.mp4 clip.gif --start 00:01:30 --duration 10

# 4. Extract using raw seconds
python vid2gif.py clip.mp4 clip.gif --start 90 --duration 10

# 5. Lower quality for small file size
python vid2gif.py clip.mp4 clip.gif --fps 10 --width 320 --max-colors 64 --dither none

# 6. Maximum quality
python vid2gif.py clip.mp4 clip.gif --fps 30 --width 1080 --max-colors 256 --dither floyd_steinberg --stats-mode full

# 7. Skip gifsicle optimization (faster, larger output)
python vid2gif.py clip.mp4 clip.gif --no-optimize

# 8. Square output (fixed height and width)
python vid2gif.py clip.mp4 clip.gif --width 480 --height 480

# 9. Play once, do not loop
python vid2gif.py clip.mp4 clip.gif --loop 1

# 10. Play three times then stop
python vid2gif.py clip.mp4 clip.gif --loop 3

# 11. Batch convert an entire folder
python vid2gif.py --batch ./raw/ --output-dir ./output/ --fps 15 --width 600

# 12. Batch with specific extensions only
python vid2gif.py --batch ./raw/ --output-dir ./output/ --extensions mp4 mov

# 13. Batch with maximum parallelism
python vid2gif.py --batch ./raw/ --output-dir ./output/ --workers 16

# 14. Verbose / debug mode
python vid2gif.py clip.mp4 clip.gif --verbose

# 15. Bayer dithering at scale 3
python vid2gif.py clip.mp4 clip.gif --dither "bayer:bayer_scale=3"

# 16. Convert MKV with 8 ffmpeg threads
python vid2gif.py movie.mkv movie.gif --threads 8

# 17. WebM source
python vid2gif.py screencast.webm screencast.gif --fps 20 --width 900

# 18. Auto-name output (same name, .gif extension)
python vid2gif.py clip.mp4

# 19. Use diff palette stats mode (default, great for motion)
python vid2gif.py clip.mp4 clip.gif --stats-mode diff

# 20. Use full palette stats mode (better for static scenes)
python vid2gif.py clip.mp4 clip.gif --stats-mode full

---

Performance Tips

• Use --threads matching your CPU core count for single conversions.
• In batch mode, set --workers to the number of simultaneous conversions. Each worker itself uses --threads ffmpeg threads, so set workers * threads <= CPU_cores.
• --stats-mode diff (default) is faster and produces better results for animated content.
• --stats-mode full is slower but better for content with little motion.
• Skipping gifsicle (--no-optimize) cuts total time by 10-25% at the cost of larger output files.

---

Project Structure

vid2gif/
    vid2gif.py          Core conversion engine + CLI
    requirements.txt    Python dependencies (all optional extras)
    README.md           This file

---

License

MIT License. Copyright 2024 algorembrant.