video-to-gif · microsoft — Claude Code skill: what it does, how to install
video-to-gif converts video clips into optimized animated GIFs using two-pass FFmpeg palette generation. Useful for crafting UI demos and docs previews directly inside the CLI.
MIT ★ 1,627 updated 2026-10-25
npx skills add microsoft/hve-core --skill video-to-gif -a claude-codeWhat video-to-gif does
This skill converts video files into GIF animations via scripts/convert.sh and scripts/convert.ps1. Instead of a basic single-pass render, it uses FFmpeg two-pass processing. The first pass generates a custom 256-color palette based on the video contents, while the second pass applies it to build the finished graphic. Defaults set playback to 10 FPS, horizontal width to 1280 pixels, and dithering to sierra2_4a.
The script detects HDR input via ffprobe using BT.2020 or SMPTE 2084 metadata and tonemaps it to SDR automatically with the hable algorithm. When you provide just a filename, the script searches the working directory, workspace root, user movies folder, downloads, and desktop.
Without FFmpeg present in your system PATH, conversion fails immediately. Invocations timeout after 600 seconds, and the script stops if the destination path matches the source file.
What it helps with
- Convert screen recordings to GIF using a two-pass color palette
- Map HDR videos down to standard SDR without washed-out highlights
- Extract a specific video snippet using start offset and duration parameters
- Scale video resolution down for inclusion in pull requests or documentation
Example prompts for the agent
- Convert
demo.movto GIF with width 800 and 15 fps. - Cut a 10-second GIF from
screencast.mp4starting at second 5. - Turn
hdr_clip.mp4into a GIF using reinhard tonemapping.
How to install video-to-gif
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill video-to-gif -a claude-code2Manually: put the files in place
~/.claude/skills/video-to-gif/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/video-to-gif/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill video-to-gif -a codex2Manually: put the files in place
.agents/skills/video-to-gif/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill video-to-gif -a cursor2Manually: put the files in place
.cursor/skills/video-to-gif/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/hve-core .github/skills/experimental/video-to-gif2Manually: put the files in place
.github/skills/video-to-gif/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill video-to-gif -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/hve-core --path .github/skills/experimental/video-to-gifManually: put the files in place
.devin/skills/video-to-gif/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about video-to-gif
How to install video-to-gif in Claude Code?
Run npx skills add microsoft/hve-core --skill video-to-gif -a claude-code.
What does video-to-gif do?
It runs video-to-GIF conversion scripts powered by FFmpeg two-pass palette generation. The process extracts custom colors on the first pass and builds the final animation on the second.
What dependencies are needed before running it?
You must install FFmpeg and make sure it is accessible via the system PATH. Without FFmpeg available, the scripts abort immediately.
Source text
SKILL.md · MIT
--- name: video-to-gif description: 'Video-to-GIF conversion with FFmpeg two-pass optimization' license: MIT compatibility: 'Requires FFmpeg on PATH' metadata: authors: "microsoft/hve-core" spec_version: "1.0" last_updated: "2026-09-27" --- # Video-to-GIF Conversion Skill This skill converts video files to optimized GIF animations using FFmpeg two-pass palette optimization. ## Overview The two-pass conversion process generates superior quality GIFs compared to single-pass approaches. Pass one analyzes the video and creates an optimized color palette. Pass two applies that palette to produce the final GIF with better color fidelity and smaller file sizes. ## Response Format After successful conversion, include a file link to the GIF in the response with the absolute file path: ```markdown /absolute/path/to/filename.gif ``` This allows the user to open the file and review it. ## Prerequisites FFmpeg is required and must be available in your system PATH. ### macOS ```bash brew install ffmpeg ``` ### Linux (Debian/Ubuntu) ```bash sudo apt update && sudo apt install ffmpeg ``` ### Windows Using Chocolatey: ```powershell choco install ffmpeg ``` Using winget: ```powershell winget install FFmpeg.FFmpeg ``` Verify installation: ```bash ffmpeg -version ``` ## Quick Start Convert a video using default settings (10 FPS, 1280px width, sierra2_4a dithering): ```bash scripts/convert.sh input.mp4 ``` ```powershell scripts/convert.ps1 -InputPath input.mp4 ``` Output saves to `input.gif` by default. ### File Search Behavior When a filename is provided without a full path, the script searches in this order: 1. Current working directory 2. Workspace root (if inside a project) 3. `~/Movies/` (macOS) or `~/Videos/` (Linux) 4. `~/Downloads/` 5. `~/Desktop/` This allows natural commands like `convert.sh demo.mov` without specifying full paths. ### HDR Handling The script automatically detects HDR video content via ffprobe by checking for BT.2020 color primaries or SMPTE 2084 transfer characteristics. When HDR is detected, tonemapping is applied automatically to produce SDR-compatible GIF output with proper color preservation. Use `--tonemap` to select the tonemapping algorithm: | Algorithm | Characteristics | |-----------|------------------------------------------------| | hable | Filmic curve, good highlight rolloff (default) | | reinhard | Preserves more color saturation | | mobius | Similar to reinhard with better highlights | | bt2390 | ITU standard, more conservative | ## Parameters Reference | Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | |--------------|------------------------------|-------------------|--------------|---------------------------------------------| | Input file | `--input` | `-InputPath` | (required) | Source video file path | | Output file | `--output` | `-OutputPath` | `input.gif` | Destination GIF file path | | Frame rate | `--fps` | `-Fps` | 10 | Frames per second | | Width | `--width` | `-Width` | 1280 | Output width in pixels | | Dithering | `--dither` | `-Dither` | sierra2_4a | Dithering algorithm | | Tonemapping | `--tonemap` | `-Tonemap` | hable | HDR tonemapping algorithm | | Skip palette | `--skip-palette` | `-SkipPalette` | false | Use single-pass mode | | Start time | `--start` | `-Start` | 0 | Start time in seconds | | Duration | `--duration` | `-Duration` | (full video) | Duration to convert in seconds | | Loop count | `--loop` | `-Loop` | 0 | GIF loop count (0 = infinite) | | Timeout | `VIDEO_TO_GIF_TIMEOUT` (env) | `-TimeoutSeconds` | 600 | Seconds allowed for each ffprobe/ffmpeg run | The output path must differ from the input path. Both scripts refuse to run when the output resolves to the input, which includes the default output for a `.gif` input, so pass an explicit output path in that case. An existing file at a different output path is overwritten. Each ffprobe and ffmpeg invocation is stopped when it exceeds the timeout. When the HDR probe fails or times out, the input is treated as SDR and conversion continues. ### Frame Rate (FPS) FPS controls animation smoothness and file size. Lower values reduce file size but create choppier motion. | FPS | Use Case | |-----|--------------------------| | 5 | Simple animations, icons | | 10 | General use (default) | | 15 | Smooth motion, UI demos | | 24 | Near-video quality | ### Width Width sets the output horizontal resolution in pixels. Height scales proportionally to maintain aspect ratio. | Width | Use Case | |-------|-----------------------| | 320 | Thumbnails, previews | | 640 | Documentation | | 800 | Presentations | | 1280 | High detail (default) | ### Dithering Algorithms Dithering determines how the 256-color GIF palette approximates the original colors. | Algorithm | Quality | Speed | Best For | |-----------------|---------|---------|----------------------------| | sierra2_4a | High | Medium | General use (default) | | floyd_steinberg | High | Slow | Photographic content | | bayer | Medium | Fast | Graphics with solid colors | | none | Low | Fastest | Stylized/posterized look | ### Time Range Selection Use `--start` and `--duration` to convert a specific portion of the video: ```bash # Start at 5 seconds, convert 10 seconds scripts/convert.sh --input video.mp4 --start 5 --duration 10 ``` ### Loop Control Use `--loop` to control GIF repeat behavior: | Value | Behavior | |-------|--------------| | 0 | Loop forever | | 1 | Play once | | N | Play N times | ## Two-Pass vs Single-Pass ### Two-Pass (Default) Two-pass conversion creates a custom palette from the source video, then applies it: ```bash # Pass 1: Generate palette ffmpeg -i input.mp4 \ -vf "fps=10,scale=1280:-1:flags=lanczos,palettegen=stats_mode=diff" \ -y /tmp/palette.png # Pass 2: Create GIF ffmpeg -i input.mp4 -i /tmp/palette.png \ -filter_complex "fps=10,scale=1280:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=sierra2_4a:diff_mode=rectangle" \ -loop 0 -y output.gif ``` Two-pass produces better color accuracy and typically smaller files. ### Single-Pass Single-pass skips palette generation and uses FFmpeg's default 256-color palette: ```bash ffmpeg -i input.mp4 \ -vf "fps=10,scale=1280:-1:flags=lanczos" \ -loop 0 -y output.gif ``` Single-pass processes faster but produces lower quality output with potential color banding. Use single-pass via `--skip-palette` (bash) or `-SkipPalette` (PowerShell). ## Script Reference ### convert.sh (Bash) ```bash # Basic usage scripts/convert.sh video.mp4 # Custom output path scripts/convert.sh --input video.mp4 --output demo.gif # Adjust quality parameters scripts/convert.sh --input video.mp4 --fps 15 --width 640 --dither floyd_steinberg # HDR video with custom tonemapping scripts/convert.sh --input hdr-video.mov --tonemap reinhard # Extract a 10-second clip starting at 5 seconds scripts/convert.sh --input video.mp4 --start 5 --duration 10 # Create a GIF that plays only once scripts/convert.sh --input video.mp4 --loop 1 # Fast single-pass mode scripts/convert.sh --input video.mp4 --skip-palette ``` ### convert.ps1 (PowerShell) ```powershell # Basic usage scripts/convert.ps1 -InputPath video.mp4 # Custom output path scripts/convert.ps1 -InputPath video.mp4 -OutputPath demo.gif # Adjust quality parameters scripts/convert.ps1 -InputPath video.mp4 -Fps 15 -Width 640 -Dither floyd_steinberg # HDR video with custom tonemapping scripts/convert.ps1 -InputPath hdr-video.mov -Tonemap reinhard # Extract a 10-second clip starting at 5 seconds scripts/convert.ps1 -InputPath video.mp4 -Start 5 -Duration 10 # Create a GIF that plays only once scripts/convert.ps1 -InputPath video.mp4 -Loop 1 # Fast single-pass mode scripts/convert.ps1 -InputPath video.mp4 -SkipPalette ``` ## Examples ### HDR Video Conversion HDR content is detected automatically. No special flags are needed: ```bash scripts/convert.sh hdr-footage.mov ``` The script applies hable tonemapping by default. Use `--tonemap` to try different algorithms: ```bash # Use reinhard for more saturated colors scripts/convert.sh --input hdr-footage.mov --tonemap reinhard ``` ### Time Range Extraction Extract a specific segment from a longer video: ```bash # Convert seconds 30-45 of a screencast scripts/convert.sh --input screencast.mp4 --start 30 --duration 15 --fps 15 ``` ### Documentation Thumbnails Create compact thumbnails for documentation: ```bash scripts/convert.sh --input demo.mp4 --width 320 --fps 8 ``` ## Troubleshooting ### FFmpeg not found Verify FFmpeg is in your PATH: ```bash which ffmpeg # macOS/Linux where.exe ffmpeg # Windows ``` If FFmpeg is installed but not found, add its directory to your PATH environment variable. ### File not found Ensure the file exists at the specified path. If providing only a filename, the script searches the workspace first, then common directories (`~/Movies/`, `~/Downloads/`, `~/Desktop/`). Use an absolute path if the file is in a different location. ### Output file is too large Reduce file size with these adjustments: * Lower FPS (try 8 or 5) * Reduce width (try 640 or 320) * Use `bayer` dithering for faster processing * Use `--duration` to convert only a portion of the video ### Colors appear washed out Switch to `floyd_steinberg` dithering for photographic content. Avoid `none` dithering unless a stylized look is intended. ### HDR content looks wrong Ensure FFmpeg 4.0+ is installed with zscale filter support. The script requires libzimg for HDR tonemapping. Install via: ```bash # macOS brew install zimg brew reinstall ffmpeg # Ubuntu sudo apt install libzimg-dev ``` If colors still appear off, try a different tonemapping algorithm with `--tonemap`. The `reinhard` algorithm preserves more saturation, while `bt2390` provides more conservative results. ### Conversion fails with filter error Ensure FFmpeg version 4.0 or later is installed. The `palettegen` and `paletteuse` filters require this version. ```bash ffmpeg -version ``` ### Temporary palette file remains The scripts clean up `/tmp/palette.png` (or `$env:TEMP\palette.png` on Windows) automatically. If conversion fails mid-process, remove this file manually.
© microsoft · MIT · microsoft/hve-core
Similar skills
All skills for Automation and no-code: n8n, Zapier, Make →video-to-gif by other authors comes first.