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

Optional external binaries

Python packages (optional)

---

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

Clip options

Output options

Quality / optimization options

Batch options

Miscellaneous

---

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

---

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.