Video To Gif

# 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)  |

### Frame Rate (FPS)

FPS controls animation smoothness and file siz