/video-to-gif

name: video-to-gif
description: Convert an MP4 (e.g. a HyperFrames render or a screen recording) to a high-quality GIF using FFmpeg's two-pass palette method. Picks the right preset for the target surface — Slack/DMs/Twitter/email/Reddit/GitHub — so you don't ship a 40MB GIF to a 5MB inbox.
version: "1.1.1"
author: Cogny AI
platforms: [ffmpeg]
user-invocable: true
argument-hint: "<input.mp4> [target: slack|twitter|reddit|email|github|web]"
allowed-tools:
  - Bash
  - Read
  - Write

Video to GIF

Convert a video (MP4, MOV, WebM) to a GIF that's **actually small** and **actually looks good** on the surface you're posting to. Pairs naturally with `/tiktok-launch-video`, `/reddit-launch-video`, and `/linkedin-launch-video` for sharing renders in places where MP4 isn't supported (Slack threads, X cards, GitHub READMEs, transactional emails).

GIF is a terrible video format — but it's everywhere, so we use FFmpeg's two-pass `palettegen` / `paletteuse` flow to make it look as good as the format allows.

Works with

Runs locally on FFmpeg with zero accounts. One optional hand-off:

| Job | Primary | Also answers it | What differs | |-----|---------|-----------------|--------------| | Make the GIF | FFmpeg (local) | — | Always available | | Post it to X (enhanced when connected) | X Organic `tool_upload_media` + `tool_create_post` | — | Asks first; needs the GIF at a public URL and ≤ 15 MB |

Usage

`/video-to-gif launch.mp4` — interactive, asks the target `/video-to-gif launch.mp4 slack` — Slack-tuned `/video-to-gif launch.mp4 reddit` — Reddit-comment-tuned `/video-to-gif launch.mp4 github` — GitHub README–tuned `/video-to-gif launch.mp4 twitter` — X / Twitter–tuned `/video-to-gif launch.mp4 email` — transactional / newsletter–tuned

Prerequisites

ffmpeg -version | head -1   # must exist
ffprobe -version | head -1

If FFmpeg isn't installed:

# macOS
brew install ffmpeg
# Debian/Ubuntu
sudo apt install ffmpeg

Steps

1. Inspect the source

Run `ffprobe` to get the source's duration, dimensions, and frame rate. You need these to pick the right preset and to warn the user before producing something that won't fit.

ffprobe -v error -show_entries stream=width,height,r_frame_rate -show_entries format=duration -of default=noprint_wrappers=1 <input>

Capture: source width, source height, source duration (seconds), source fps.

2. Pick the preset

If the user passed a target, use the matching preset. Otherwise ask. Each preset is tuned to the surface's actual size limits and aesthetic norms:

| Preset | Width | FPS | Loop | Why | |--------|------:|----:|------|-----| | **slack** | 480 | 12 | yes | 50MB upload cap; threads scroll fast; readability > smoothness | | **twitter** | 480 | 15 | yes | 15MB GIF cap; auto-converted to MP4 above the cap, kills the loop | | **reddit** | 600 | 15 | yes | 100MB cap but image-host sidebar dies past 20MB | | **github** | 720 | 15 | yes | 10MB README cap; over the cap GitHub silently drops the file | | **email** | 480 | 10 | yes | 5MB Gmail clip threshold; many ESPs strip animation past 1MB | | **web** | 800 | 18 | yes | Generic fallback for landing pages and product blogs |

**Rules of thumb:**

• If source is < 6 seconds, you can usually bump fps by ~3 without breaking the size budget.
• If source is > 12 seconds, drop fps by 2–3 and consider trimming.
• Never upscale — if source width is below the preset width, keep source width.
• Strip audio (GIF can't carry it) — saves a step and removes accidental noise from screen captures.

3. Two-pass palette render (this is the only correct way)

A single-pass GIF render produces banded, dithered, oversized garbage. The right approach is two passes:

1. Generate an optimal 256-color palette from the source. 2. Apply that palette with Floyd-Steinberg dithering.

The pipeline is FFmpeg's `palettegen` filter feeding `paletteuse`. Do it as a single command using filter splits:

ffmpeg -y -i "<input>" \
  -vf "fps=<FPS>,scale=<WIDTH>:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=dither=floyd_steinberg" \
  -loop 0 \
  "<output.gif>"

Notes on the filter chain:

• `fps=<FPS>` first — so palette is generated from the actual frames you'll keep.
• `scale=<WIDTH>:-1` keeps aspect; `-1` rounds the height. Use `-2` for codecs that need even dimensions (not needed for GIF, but harmless).
• `flags=lanczos` is the best general-purpose downscaler.
• `stats_mode=diff` weights moving regions higher when picking palette colors — sharper text, cleaner UI, less banding.
• `dither=floyd_steinberg` is the best default. For UI / sharp edges with no gradients, try `dither=bayer:bayer_scale=3` instead — slightly larger files but no dither noise on flat colors.
• `-loop 0` = infinite loop. Use `-loop 1` to play once. (For Slack and Twitter, infinite loop is what users expect.)

**Alternative for HyperFrames sources:** if the input is still a HyperFrames project (not just its MP4), you can render the GIF straight from the composition, skipping the MP4 step: `npx hyperframes render --format gif --fps 15 --gif-loop 0 --output out.gif` from the project directory (`--fps 15` is HyperFrames' recommended GIF rate; it still needs FFmpeg). It outputs at the composition's own size (its `--resolution` only scales up), so when the preset in step 2 is narrower than the composition, use the MP4 + palette pipeline below instead. Either way, check the cap as in step 4.

4. Render and verify

Run the command. Then verify:

# Check the file size
ls -lh "<output.gif>"

# Check the GIF's actual dimensions and frame count
ffprobe -v error -count_frames -select_streams v:0 \
  -show_entries stream=width,height,nb_read_frames \
  -of default=noprint_wrappers=1 "<output.gif>"

If the file is larger than the preset's surface cap (see table above), do **one** of:

1. Drop FPS by 2–3 and re-render (best quality preserved). 2. Drop width by ~80