image-converter

A fast CLI for converting images and videos into web-friendly formats. Powered by ffmpeg.

Supports APNG, AVIF, GIF, JPEG, PNG, and WebP -- both still and animated.

Features

• Interactive & non-interactive modes -- run bare for a guided TUI, or pass flags for scripting and CI
• Video to animation -- extract animated APNG/GIF/WebP clips from video files with configurable FPS, duration, and resolution
• Video to still -- grab a single frame from any video
• Target file size -- specify a budget like --target-size 1.5MB and the tool binary-searches for the best quality or resolution to hit it
• Size estimation -- preview estimated output size before committing to a conversion
• Batch conversion -- point at a directory and convert everything, optionally recursive
• Progress bars -- real-time progress for animated conversions

Requirements

ffmpeg and ffprobe must be available on your PATH.

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

Installation

go install github.com/YOUR_USERNAME/image-converter@latest

Or build from source:

git clone https://github.com/YOUR_USERNAME/image-converter.git
cd image-converter
go build -o image-converter .

Usage

Interactive mode

Run without arguments to launch the interactive TUI. It will scan the current directory, let you pick files and format, preview estimated sizes, and tweak settings before converting.

image-converter

Non-interactive mode

# Convert a photo to WebP
image-converter --input photo.jpg --format webp

# Convert a photo to AVIF under 1.5 MB
image-converter --input photo.jpg --format avif --target-size 1.5MB

# Create an animated APNG from a video (24fps, 6 seconds, max 1280px)
image-converter --input video.mov --format apng --fps 24 --duration 6 --max-dim 1280

# Batch-convert a directory
image-converter --input ./photos --format webp --recursive

# Extract a still frame from a video as JPEG
image-converter --input clip.mp4 --format jpeg --still

Flags

Flag	Description	Default
--input	Input file or directory	(required in non-interactive mode)
--format	Output format: apng, avif, gif, jpeg, png, webp	auto
--output-dir	Output directory	same as input
--quality	Quality for lossy formats (1-100)	80
--target-size	Target output size, e.g. 1.5MB, 900KB
--recursive	Scan directories recursively	false
--animated	Force animated output	false
--still	Force still output (e.g. single frame from video)	false
--fps	Frames per second for animated outputs	24
--duration	Duration in seconds for animated outputs	10
--max-dim	Max pixel dimension (longest side). Animated outputs default to 1280 when unset
--interactive	Force interactive mode	false

Supported formats

Format	Animated	Lossy	Notes
APNG	yes	no	Best quality for animation with alpha. Default for video inputs
AVIF	no	yes	Excellent compression for stills. Default for image inputs
GIF	yes	yes	Universal support, limited to 256 colors
JPEG	no	yes	Best for photos without transparency
PNG	no	no	Lossless stills with transparency
WebP	yes	yes	Good compression, supports both animation and transparency

How target size works

When you pass --target-size, the tool runs a binary search to find the best settings that fit your budget:

• Lossy stills (JPEG, WebP, AVIF) -- adjusts quality
• Lossless stills (PNG) -- adjusts resolution
• Animated outputs -- adjusts resolution (max-dim)

The search encodes sample outputs at different settings and converges on the best fit, showing a progress bar along the way.

License

MIT