vid2frames

English | Русский

A small, dependency-free CLI tool that extracts frames from videos through FFmpeg. Point it at a video (or a whole directory tree of videos), pick a sampling mode, and get neatly named image files out.

Features

• Five extraction modes — by FPS, by time interval, every Nth frame, a fixed number of evenly spaced frames, or every single frame.
• Batch processing — scan a directory tree recursively and either mirror its structure in the output or flatten everything into one folder with conflict-free names.
• Time ranges — extract only between --from and --to.
• JPG / PNG / WEBP output with a friendly 1–100 quality scale.
• Zero Go dependencies — the binary is pure standard library.
• Bundled FFmpeg builds — the build wrapper downloads FFmpeg/FFprobe for Windows and Linux, so end users install nothing.
• Dry-run mode — print the exact FFmpeg command without running it.

Requirements

• ffmpeg at runtime; count mode also needs ffprobe.
• Either keep them in bin/ next to the vid2frames binary (the dist layout does this for you) or have them in PATH.
• On macOS: brew install ffmpeg.

Quick start

# 1 frame per second into ./frames (all defaults)
vid2frames input.mp4

# ~30 evenly spaced preview frames
vid2frames --mode count --count 30 --out preview input.mp4

# Batch: every video under videos/, mirrored under frames/
vid2frames --input-dir videos --out frames --mode count --count 20

Usage

vid2frames [options] input.mp4
vid2frames [options] --input-dir videos --out frames

Mode	What it does	Key flag
fps	N frames per second (default: --fps 1)	--fps
every-seconds	One frame every N seconds	--seconds
every-frame	Every Nth decoded frame	--frame-step
count	About N evenly spaced frames over the video or range	--count
all	Every decoded frame	—

Common options:

--out frames          Output directory
--from 00:01:00       Optional start time
--to 00:02:00         Optional end time
--format jpg          jpg, png, or webp
--quality 90          jpg/webp quality, 1-100
--prefix frame        Output filename prefix
--input-dir videos    Batch input directory
--batch-layout mirror Batch output layout: mirror or flat
--recursive true      Scan input directory recursively
--extensions LIST     Video extensions for batch mode
--keep-going          Continue batch after per-file errors
--overwrite           Overwrite existing files
--dry-run             Print ffmpeg command without running it
--ffmpeg PATH         Explicit ffmpeg path
--ffprobe PATH        Explicit ffprobe path

The full flag reference, recipes and troubleshooting live in the user guide.

Output naming

Single-file output:

frames/frame_000001.jpg
frames/frame_000002.jpg

Batch with the default --batch-layout mirror (one directory per video, input tree mirrored):

videos/cam1/day/a.mp4       -> frames/cam1/day/a/frame_000001.jpg
videos/cam2/session/c.mov   -> frames/cam2/session/c/frame_000001.jpg

Batch with --batch-layout flat (everything in one directory, the relative video path becomes part of the prefix):

videos/cam1/day/a.mp4       -> frames/frame_cam1_day_a_mp4_000001.jpg
videos/cam2/session/c.mov   -> frames/frame_cam2_session_c_mov_000001.jpg

Build with bundled FFmpeg

The build wrapper downloads FFmpeg/FFprobe for the target platform, caches the archives in .cache/ffmpeg/, and places everything next to the app:

# current platform
go run ./tools/build

# cross-builds
go run ./tools/build --target-os windows --target-arch amd64
go run ./tools/build --target-os linux --target-arch amd64
go run ./tools/build --target-os darwin --target-arch arm64 --no-ffmpeg

Artifacts land in dist/<os>-<arch>/:

dist/windows-amd64/
  vid2frames.exe
  bin/ffmpeg.exe
  bin/ffprobe.exe

Bundled targets: windows/amd64, windows/arm64, linux/amd64, linux/arm64. macOS builds are app-only — install FFmpeg via Homebrew.

The prebuilt FFmpeg/FFprobe binaries are downloaded from the latest GPL release of BtbN/FFmpeg-Builds. Note that while this project's code is MIT-licensed, those bundled FFmpeg binaries are GPL-licensed — keep that in mind when redistributing dist packages.

Build without bundled FFmpeg

go build -o vid2frames .

# plain cross-builds
GOOS=windows GOARCH=amd64 go build -o dist/windows/vid2frames.exe .
GOOS=linux GOARCH=amd64 go build -o dist/linux/vid2frames .
GOOS=darwin GOARCH=arm64 go build -o dist/macos-arm64/vid2frames .

Documentation

Language	Markdown	PDF
English	docs/user-guide.en.md	docs/vid2frames-user-guide.en.pdf
Русский	docs/user-guide.ru.md	docs/vid2frames-user-guide.ru.pdf

Acknowledgements

• FFmpeg — the engine that does all the actual video decoding; this tool is just a thin, friendly wrapper around it.
• BtbN/FFmpeg-Builds — the high-quality automated static FFmpeg builds that make the zero-install dist packages possible.

Huge thanks to the authors and maintainers of both projects.

Contributing

Issues and pull requests are welcome. Please run go vet ./... and make sure go build ./... passes before submitting.

License

This project is licensed under the MIT License — see the LICENSE file for details.