Skip to content
madspaaskesenPublic

About

A sacred CLI tool for inspecting and editing GIF metadata. Frame count, loop settings, delays — with clarity and care.

Topics

Resources

Code of conduct

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

🦀 gifmeta

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

Crates.io Downloads License CI Tests


🧍‍♂️ Why I Built This

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.

Rust FFmpeg SacredAI mySiteChart


🔧 Features

  • 🔁 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

🙋‍♂️ Why Not Use gifsicle or gif-rs?

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

⚠️ What It’s Not

  • ❌ 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.


🧠 Why This Exists

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

📦 Installation

Install via crates.io!:

cargo install gifmeta

Or 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 --help

🧰 Download a binary

Download 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.gif

Older macOS builds

Builds before v0.7.0 were unsigned. If macOS blocks one, remove the quarantine flag once:

xattr -d com.apple.quarantine gifmeta
chmod +x gifmeta

🛠️ Usage

Info options

  • --json: Get output in json format

Modify (mod) options

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 0 still 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, default merge).
  • --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.

Show metadata

gifmeta info tests/testdata/loop/10frame-rainbow.gif

Show metadata output as json

gifmeta info tests/testdata/loop/10frame-rainbow.gif --json

Detect delta-optimized frames

gifmeta info tests/testdata/optimize/moving-square-optimized.gif --show-frames

Shows 🧩 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).

Loop forever

gifmeta mod tests/testdata/loop/loop-once.gif --infinite --output loop-forever.gif

Modify loop count (plays exactly 10 times)

gifmeta mod tests/testdata/loop/loop-once.gif --loop-count 10 --output tests/testdata/loop/loop-once-modified.gif

Modify delay on all frames to 100ms or 10 centiseconds

gifmeta mod tests/testdata/timing/zero-delay.gif --delay 10 --output tests/testdata/timing/zero-delay-modified.gif

Modify frame delays using centiseconds (1 = 10ms): frame 0 → 1, frame 1 → 20

gifmeta mod tests/testdata/timing/zero-delay.gif --delays "0=1,1=20" --output tests/testdata/timing/zero-delay-modified2.gif

Modify delay on all frames to 150ms, set specific frame 0 to 20ms and frame 1 to 200ms.

gifmeta mod tests/testdata/timing/zero-delay.gif --delay 15 --delays "0=2,1=20" --output tests/testdata/timing/zero-delay-modified3.gif

✂️ Delete frames

gifmeta mod input.gif --delete 2,5 --output output.gif

Frames 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.

🔑 Convert frames to full images / 🧱 unoptimize

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 image

🎬 Create a GIF from images

gifmeta 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 3

At 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).

➕ Insert, 📑 duplicate and 🔀 re-order frames

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 backwards

Inserted 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.

Modify all values at once example

gifmeta mod tests/testdata/timing/zero-delay.gif --infinite --delay 15 --delays "0=2,1=20" --output tests/testdata/timing/zero-delay-modified4.gif

🖼️ Preview a GIF Frame as PNG

You 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:

🔹 Output frame 0 as PNG to a file

gifmeta preview path/to/input.gif --frame 0 --output frame0.png

🔹 Output frame 3 as base64 (for GUI, web, etc.)

gifmeta preview path/to/input.gif --frame 3 --as-base64

🔹 Raw view of a delta frame

By 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.png

If --frame is omitted, it defaults to the first frame (0). You must specify either --as-base64 or --output.

🔹 Export all frames

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/ --raw

🦀 As a library

use 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);

🛠️ Commands

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)

📊 Visual Preview Report

You can run:

./run-visual-preview.sh

It 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.


🛤️ Roadmap

  • 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

⚠️ Batch processing and WASM are intentionally skipped.
These are best handled externally with scripting or shell tooling.


👩‍💻 Contributing

Wanna help? Fork, clone, and PRs welcome. You can also suggest Codex tasks or open issues 💛


🔗 Links


🛠 Built With

  • gif
  • Rust 2021
  • Love, frustration, and sacred formatting

🕊️ License

MIT — do good things with it.


🌟 Author

Built by Mads Paaskesen with Rust and a soft spot for retro formats.

About

A sacred CLI tool for inspecting and editing GIF metadata. Frame count, loop settings, delays — with clarity and care.

Topics

Resources

Code of conduct

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages