gifmeta is a small, focused tool for inspecting and modifying GIF metadata.
It’s designed for developers, artists, and anyone needing loop control and timing tweaks — fast and reliably.
❤️ Built with Rust. Sacredly simple. Zero bloat.
🌐 Website: gifmeta.com
Because changing loop count or frame delays in GIFs was a pain.
Most tools were too heavy, too raw, or lacked reliable preview/testing.
gifmeta was born to fix that — with precise CLI commands, minimalism, and full test coverage.
- 🔁 Loop forever (
--infinite) or a fixed number of plays (--loop-count 3) - ⏱️ Apply fixed delay to all frames (
--delay) - 🎯 Set specific frame delays (
--delays 1=30,4=60) - 📤 Output JSON metadata (
--json) - 🖼️ Extract any frame as PNG (to file or base64)
- 🧩 Detect frame-optimized GIFs (🔑 keyframes vs Δ delta frames)
- ⚡ Render / export all frames in one pass (
--all,FrameRenderer) - ✂️ Delete frames safely, 🔑 convert frames to full images, 🧱 unoptimize (
--delete,--keyframe,--unoptimize) - 🎬 Create a GIF from images (
gifmeta create a.png b.png c.jpg -o out.gif) - ➕ Insert, 📑 duplicate and 🔀 re-order frames (
--insert,--duplicate,--order) — even in frame-optimized GIFs - 🧪 CLI + doc tests for core functions
- 🖼️ Side-by-side visual preview reports via
run-visual-preview.sh
You can — and should, if you need full encoding pipelines.
But gifmeta wraps just the things most of us need quickly:
- 🔁 Loop control (infinite or fixed)
- ⏱ Frame delay override (global + selective)
- ✅ Verified, minimal changes
- 🔍 Human-friendly reports
- ⚙️ Ideal for future GUI integration or scripting
- ❌ Not a full GIF encoder
- ❌ Not for image content editing
- ❌ Not a general-purpose wrapper
gifmeta lives in a small, useful space — metadata tuning and clarity. Nothing more.
GIFs are still everywhere — especially in messaging, memes, and UI loaders. But modifying timing or loop behavior often requires heavy tools.
gifmeta lets you do it instantly, with:
- 🦀 Native Rust speed
- 🧼 Zero bloat
- 🖥️ CLI-first ergonomics
Install via crates.io!:
cargo install gifmetaOr use directly with:
cargo run -- <command>Install via GitHub
git clone https://github.com/madspaaskesen/gifmeta.git
cd gifmeta
cargo build --release
./target/release/gifmeta --helpDownload the zip for your platform from the latest release:
| Platform | File |
|---|---|
| macOS, Apple Silicon (M1–M4) | gifmeta-<version>-macos-aarch64.zip |
| macOS, Intel | gifmeta-<version>-macos-x86_64.zip |
| Windows | gifmeta-<version>-windows-x86_64.zip |
| Linux | gifmeta-<version>-linux-x86_64.zip |
The macOS binaries are signed and notarized by Apple and the Windows gifmeta.exe is signed (from v0.7.0),
so they run without security warnings.
./gifmeta info yourfile.gifBuilds before v0.7.0 were unsigned. If macOS blocks one, remove the quarantine flag once:
xattr -d com.apple.quarantine gifmeta
chmod +x gifmeta--json: Get output in json format
You can combine any of the following:
--infinite: Loop forever--loop-count <n>: Play exactly n times (1 = once, 2 = twice…). Can't be combined with--infinite. (--loop-count 0still means infinite but is deprecated.)--delay <n>: Set same delay for all frames. Unit is centiseconds (1 = 10ms).--delays <csv>: Override specific frames. Format:1=15,3=50(in centiseconds).--delete <csv>: Delete frames, e.g.2,5(--delete-mode merge|drop, defaultmerge).--keyframe <csv>: Convert frames to full images, e.g.3,7.--unoptimize: Convert every frame to a full image.--insert <FRAME=IMAGE>: Insert an image before a frame, e.g.3=logo.png. Repeat the flag for several images.--insert-delay <n>sets their delay (default: delay of the frame they're inserted before).--duplicate <csv>: Copy frames, e.g.2,5(the copy goes right after the frame;2,2= two copies).--order <csv>: New frame order, every frame exactly once, e.g.4,3,2,1,0.
All frame numbers are 0-based and refer to the original GIF.
gifmeta info tests/testdata/loop/10frame-rainbow.gifgifmeta info tests/testdata/loop/10frame-rainbow.gif --jsongifmeta info tests/testdata/optimize/moving-square-optimized.gif --show-framesShows 🧩 Optimized : yes (1 keyframes / 5 frames) and marks every frame 🔑 (keyframe, a full
image on its own) or Δ (delta frame that only stores changes on top of earlier frames).
gifmeta mod tests/testdata/loop/loop-once.gif --infinite --output loop-forever.gifgifmeta mod tests/testdata/loop/loop-once.gif --loop-count 10 --output tests/testdata/loop/loop-once-modified.gifgifmeta mod tests/testdata/timing/zero-delay.gif --delay 10 --output tests/testdata/timing/zero-delay-modified.gifgifmeta mod tests/testdata/timing/zero-delay.gif --delays "0=1,1=20" --output tests/testdata/timing/zero-delay-modified2.gifgifmeta mod tests/testdata/timing/zero-delay.gif --delay 15 --delays "0=2,1=20" --output tests/testdata/timing/zero-delay-modified3.gifgifmeta mod input.gif --delete 2,5 --output output.gifFrames that depended on a deleted frame (frame-optimized GIFs) are automatically written as full images,
so the rest of the animation looks exactly the same. The deleted delay is added to the previous frame
(same total duration) — use --delete-mode drop to make the animation shorter instead.
gifmeta mod input.gif --keyframe 3,7 --output output.gif # selected frames become full images
gifmeta mod input.gif --unoptimize --output output.gif # every frame becomes a full imagegifmeta create frame1.png frame2.png frame3.jpg -o out.gif # 100 ms per frame, loops forever
gifmeta create a.png b.png -o out.gif --delay 50 --delays 1=100 --loop-count 3At least 2 images (PNG, JPEG or WebP), all the same size. Each image becomes one frame with its own palette: exact for ≤ 256 colours, otherwise colour-reduced. Fully transparent pixels stay transparent (semi-transparent pixels are drawn opaque — GIF has no partial transparency).
gifmeta mod input.gif --insert 3=logo.png -o out.gif # new frame before frame 3
gifmeta mod input.gif --insert 10=end.png --insert-delay 200 -o out.gif # 10 frames → append, show 2 s
gifmeta mod input.gif --insert 3=fixed.png --delete 3 -o out.gif # replace frame 3
gifmeta mod input.gif --duplicate 0,0 -o out.gif # hold the first frame 3× as long
gifmeta mod input.gif --order 4,3,2,1,0 -o out.gif # play backwardsInserted images must have the same size as the GIF (fit / crop options may come later). Like deleting,
frames that depended on their old neighbour are re-written as full images, so everything still looks
exactly right in frame-optimized GIFs. --order can't be combined with --delete, --insert or
--duplicate — run two commands. It keeps all frames in memory while writing.
gifmeta mod tests/testdata/timing/zero-delay.gif --infinite --delay 15 --delays "0=2,1=20" --output tests/testdata/timing/zero-delay-modified4.gifYou can now extract a specific frame from any GIF and output it as a PNG image — either as a file or directly as base64 for web previews:
gifmeta preview path/to/input.gif --frame 0 --output frame0.pnggifmeta preview path/to/input.gif --frame 3 --as-base64By default the preview shows the frame as it looks when the GIF plays (earlier frames are
composited with the correct disposal + transparency). Add --raw to see only the pixels stored
in that frame — handy for inspecting frame-optimized GIFs:
gifmeta preview path/to/input.gif --frame 1 --raw --output frame1-raw.pngIf
--frameis omitted, it defaults to the first frame (0). You must specify either--as-base64or--output.
Render every frame in one fast pass and write them as numbered PNGs:
gifmeta preview path/to/input.gif --all --output-dir frames/ # frame_000.png, frame_001.png, …
gifmeta preview path/to/input.gif --all --output-dir frames-raw/ --rawuse gifmeta::{FrameRenderer, PreviewMode};
for frame in FrameRenderer::open("input.gif", PreviewMode::Composited)? {
let frame = frame?; // RenderedFrame { index, delay_cs, image }
frame.image.save(format!("frame_{}.png", frame.index))?;
}use gifmeta::{create_gif, modify_gif_with_report, CreateOptions, FrameInsert, ModOptions};
// Images → GIF
create_gif(&["a.png".into(), "b.png".into()], CreateOptions {
output: Some("out.gif".into()),
delay: Some(20),
..Default::default()
})?;
// Insert + duplicate in an existing GIF
let report = modify_gif_with_report(&"in.gif".into(), ModOptions {
output: Some("edited.gif".into()),
inserts: Some(vec![FrameInsert::new(3, "logo.png").with_delay(50)]),
duplicates: Some(vec![0]),
..Default::default()
})?;
println!("{} → {} frames", report.frames_in, report.frames_out);| Command | Description |
|---|---|
info |
Display GIF metadata (dimensions, loop, delays) |
mod |
Loop, delays, delete / insert / duplicate / re-order frames |
create |
Create an animated GIF from images (PNG/JPEG/WebP) |
preview |
Extract a single frame as PNG (file or base64) |
You can run:
./run-visual-preview.shIt will:
- Apply a set of metadata modifications
- Generate side-by-side comparisons
- Output a beautiful
tests/visual/report.html
This is useful for testing transparency, timing, or human-visible playback changes.
- Set loop count (v0.2.0)
-
--infinite+ correct "plays once" handling (v0.5.0) - CLI structure with
clap v4 - Set per-frame delays (v0.3.0)
- Delete frames, keyframes, unoptimize (v0.6.0)
- Create GIFs from images, insert / duplicate / re-order frames (v0.7.0)
- GUI Companion (gifmeta-gui)
- Optimize (shrink file size)
- Fit / pad / crop images of a different size
These are best handled externally with scripting or shell tooling.
Wanna help? Fork, clone, and PRs welcome. You can also suggest Codex tasks or open issues 💛
- gif
- Rust 2021
- Love, frustration, and sacred formatting
MIT — do good things with it.
Built by Mads Paaskesen with Rust and a soft spot for retro formats.