gifvid

gifvid is a local-first CLI for turning a URL or local media file into a size-constrained GIF, MP4, or WebM that is actually usable in Slack, docs, and the web.

The product shape is simple:

1. bring in a video source
2. pick the exact clip window that matters
3. export something that fits where you need to send it

gifvid starts with the reliable primitives that already work on a real machine:

• yt-dlp for URL-based ingestion
• ffmpeg and ffprobe for clipping and rendering
• optional Cloudflare R2 upload for sharing

Requirements

• Node.js 20+
• ffmpeg
• ffprobe
• yt-dlp for URL inputs

On macOS with Homebrew:

brew install ffmpeg yt-dlp

Install

Run without installing globally:

npx gifvid --help

Install globally:

npm install -g gifvid

With pnpm:

pnpm dlx gifvid --help

Quick Start

Inspect a source:

npx gifvid inspect "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Make a Slack-sized GIF from a URL:

npx gifvid make "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --start 0:42 \
  --duration 4 \
  --preset slack

Make a GIF from a local file with a hard size budget:

npx gifvid make ./clip.mp4 \
  --start 1:03 \
  --end 1:07 \
  --preset web \
  --max-bytes 3mb

Generate GIF, MP4, and WebM plus a manifest:

npx gifvid make ./clip.mp4 \
  --start 1:03 \
  --duration 4 \
  --preset slack \
  --format all

If a URL host requires a real browser session, let yt-dlp read local cookies:

npx gifvid make "https://www.youtube.com/watch?v=..." \
  --browser chrome \
  --start 0:15 \
  --duration 3

Commands

gifvid inspect <input>

Shows source metadata and rough preset estimates.

Useful flags:

• --browser <profile> for URL sources that need browser cookies
• --json for structured output

gifvid make <input>

Generates a clip asset from a URL or local media file.

Required:

• --start <time>

Choose one:

• --end <time>
• --duration <time>

Optional:

• --preset <slack|web|tiny|hq>
• --format <gif|mp4|webm|all>
• --width <pixels>
• --fps <frames>
• --colors <count>
• --max-bytes <value>
• --browser <profile>
• --output-dir <path>
• --name <basename>
• --publish
• --json

Every make run writes a sidecar manifest:

<basename>.manifest.json

When --format all is used, the command emits:

• <basename>.gif
• <basename>.mp4
• <basename>.webm
• <basename>.manifest.json

gifvid publish <file>

Uploads an existing asset to Cloudflare R2.

Optional:

• --key <bucket/key.gif>
• --json

Cloudflare R2

Publishing is optional and env-driven.

Required env vars:

GIFVID_R2_ACCOUNT_ID=...
GIFVID_R2_ACCESS_KEY_ID=...
GIFVID_R2_SECRET_ACCESS_KEY=...
GIFVID_R2_BUCKET=...

Optional:

GIFVID_R2_PUBLIC_BASE_URL=https://cdn.example.com/
GIFVID_R2_KEY_PREFIX=gifs

If GIFVID_R2_PUBLIC_BASE_URL is set, gifvid returns a shareable public URL after upload.

Presets

• tiny: low-friction reaction GIFs
• slack: default preset for chat usage
• web: bigger embed-friendly GIFs
• hq: highest-quality GIF master before you need a tighter byte budget

Each preset defines:

• a default clip length
• a max clip length
• a starting width, fps, and color count
• a default byte target

If the first GIF render is too large, gifvid iterates downward on palette, fps, and width until it lands under budget or returns the smallest viable result.

Notes

• URL reliability is only as good as the local yt-dlp setup and the target site's defenses.
• GIF is the compatibility format. MP4 and WebM are often the better output.
• You are responsible for respecting source platform terms and any copyright or licensing constraints.

Repository

Source, docs, and the public site live at:

github.com/danielgwilson/gifvid

If you are working from the repo itself instead of the published package, the workspace root exposes:

pnpm cli make ...