gif-utils

A lightweight Bash CLI (giftool) for everyday media chores, built as a wrapper around FFmpeg. It started as a GIF maker and now also handles common audio/video tasks — replacing an audio track, extracting or stripping audio, grabbing a still frame, and inspecting media — while automating the fiddly FFmpeg filter chains (palette generation, smart cropping) behind simple commands.

Prerequisites

The following must be installed and available on your PATH:

• FFmpeg & FFprobe — used for all processing and inspection. ffprobe ships with FFmpeg. Check with ffmpeg -version / ffprobe -version.
• Bash — the tool is a Bash script. macOS/Linux have it natively; on Windows use Git Bash or WSL.

For the npm install path you also need Node.js ≥ 20.19.

Installation

Via npm (global)

npm install -g @jml6m/gif-utils

This puts a giftool command on your PATH everywhere. (The npm package is a thin Node launcher around the Bash script, so Bash and FFmpeg still need to be installed per above.)

From a clone

git clone https://github.com/jml6m/gif-utils.git
cd gif-utils
chmod +x giftool

Run it as ./giftool, or symlink it onto your PATH (e.g. into ~/bin) to call giftool from anywhere.

Usage

./giftool <command> [args] [options]

Commands

| Command | Arguments | Description | | :--- | :--- | :--- | | create | <file> <start> <dur> | Create a GIF from a video clip starting at start for dur seconds. | | autocrop | <file> <start> <dur> | Same as create, but auto-detects and removes black bars. | | trim | <file.gif> | Smart-trim solid/letterboxed edges from an existing GIF. | | audio | <video> <audio> | Replace the video's audio track with <audio> (re-encoded to AAC). | | extract | <video> | Extract the audio track to a separate file (default .mp3). | | mute | <video> | Remove the audio track (video stream copied, no re-encode). | | frame | <video> <time> | Grab a single still frame at <time> (default .png). | | info | <file> | Print container, duration, and per-stream codec/dimension info (via FFprobe). |

Times accept either plain seconds (90) or HH:MM:SS (00:01:30).

Options

| Flag | Description | Default | Applies to | | :--- | :--- | :--- | :--- | | -w [px] | Output width (maintains aspect ratio). | 480 | gif commands | | -f [fps] | Framerate. | 15 | gif commands | | -o [name] | Custom output filename. | derived from input | all | | -v | Verbose — prints the underlying FFmpeg commands. | off | all | | -h, --help | Show help. | — | — | | --version | Print the version. | — | — |

Default output names

When -o is omitted, the output is derived from the input:

| Command | Output | | :--- | :--- | | create / autocrop | <input>.gif | | trim | <input>_trimmed.gif | | audio | <input>_audio.<ext> | | extract | <input>.mp3 | | mute | <input>_muted.<ext> | | frame | <input>_frame.png |

Examples

Create a 5-second GIF starting at 00:10

./giftool create video.mp4 10 5

Create a smaller, smoother GIF

./giftool create video.mp4 0 3 -w 320 -f 24

Remove letterboxing (black bars) while making a GIF

./giftool autocrop movie_clip.mp4 45 4

Trim solid edges from an existing GIF

./giftool trim animation.gif

Overlay a new audio track onto an existing MP4

./giftool audio clip.mp4 soundtrack.mp3 -o clip_scored.mp4

The video stream is copied untouched and the audio is re-encoded to AAC. Output ends at whichever stream is shorter (-shortest), keeping things in sync.

Extract a video's audio to MP3 (or any format, by extension)

./giftool extract clip.mp4              # -> clip.mp3
./giftool extract clip.mp4 -o track.aac # AAC instead

Strip audio from a video

./giftool mute noisy.mp4

Grab a poster frame at 12 seconds

./giftool frame clip.mp4 12 -o poster.png

Inspect a file

./giftool info clip.mp4

Testing

A self-contained test harness generates throwaway media and exercises every command:

chmod +x test_giftool.sh
./test_giftool.sh

It cleans up its temporary files on exit and prints a pass/fail summary (non-zero exit on failure). The same suite runs in CI alongside ShellCheck — see .github/workflows/ci.yml.

Contributing

See AGENTS.md for conventions, and CHANGELOG.md for the version history.

License

MIT © jml6m