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

---

🧍‍♂️ 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.

---

🔧 Features

• 🔁 Set infinite or fixed loop count (--loop-count)
• ⏱️ 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)
• 🧪 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

Absolutely. Here’s a clean and helpful section you can add to your README.md under the Installation section:

---

🧰 Installation

Download the binary for your platform from the latest release.

✅ macOS Users

If you see a warning when trying to run gifmeta, macOS may have quarantined the file because it's unsigned.

To allow execution:

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

Then run it with:

./gifmeta info yourfile.gif

You only need to do this once per download. After this, gifmeta will run normally.

---

Let me know if you want the same clarity for Windows (e.g., SmartScreen warnings) or Linux permissions 💛

---

🛠️ Usage

Info options

• --json: Get output in json format

Modify (mod) options

You can combine any of the following:

• --loop-count <n>: Set loop behavior (0 = infinite, 1 = once, 2 = twice…)
• --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).

Show metadata

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

Show metadata output as json

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

Modify loop count

gifmeta mod --input 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 --input 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 --input 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 --input tests/testdata/timing/zero-delay.gif --delay 15 --delays "0=2,1=20" --output tests/testdata/timing/zero-delay-modified3.gif

Modify all values at once example

gifmeta mod --input tests/testdata/timing/zero-delay.gif --loop-count 0 --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 --input path/to/input.gif --frame 0 --output frame0.png

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

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

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

---

🛠️ Commands

Command	Description
info	Display GIF metadata (dimensions, loop, delays)
mod	Apply metadata modifications (loop/delays/output)
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)
• CLI structure with clap v4
• Set per-frame delays (v0.3.0)
• Frame editing with duration visuals (experimental)
• GUI Companion (Tauri, optional)

⚠️ 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

• Crates.io
• Documentation (coming soon)
• GitHub

---

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