video-to-gif

# Video → GIF Converter Skill

**Purpose**: Turn video files (MP4, MOV, etc.) into optimized animated GIFs with precise control over FPS while balancing quality and file size.

**Triggers** (activate on these or similar):
- "convert this video to gif at 23 fps"
- "make a gif from the video" / "video to gif"
- "turn the [mp4/mov] into gif at [X]fps"
- "gif at 23 fps" from attachment or file
- Any request for video file + GIF + frame rate or smooth playback

## Core Capabilities & Defaults
- **FPS**: User-specified (23 is excellent for smooth motion; original video often ~23.21). Default suggestion: 15-23 if not given.
- **Scaling**: Intelligent auto-downscale
  - Source res > 720px → target 480px (preferred for complex/artistic/gradient-heavy scenes to keep file < ~15-25MB)
  - Or 720px for simpler content or higher quality request
  - Square sources (e.g. 1080x1080 phone video): maintain square (480:480 or 720:720)
  - Use high-quality `lanczos` filter
- **Method**: Always **two-pass palette** (palettegen + paletteuse) for superior color accuracy vs single-pass.
- **Dither**: `sierra2` (excellent quality)
- **Looping**: `-loop 0` (plays forever)
- **Audio**: Removed (`-an`)
- **Output**: `/home/workdir/artifacts/<originalname>_<fps>fps.gif`

## Exact Workflow (use via bash tool)

1. **Inspect source**
   Run ffprobe to learn duration, resolution, fps, audio presence.
   Example quick:
   ```bash
   ffprobe -v error -show_format -show_streams -of json "$INPUT" | head -c 2000
   ```

2. **Set params** (confirm with user if needed)
   - FPS = requested or 23
   - SCALE e.g. "480:480" or "720:-2"

3. **Palette generation (pass 1)**
   ```bash
   _tmpd="$(mktemp -d)"
   trap 'rm -rf "$_tmpd"' EXIT

   ffmpeg -y -i "$INPUT" \
     -vf "fps=${FPS},scale=${SCALE}:flags=lanczos,palettegen=stats_mode=full" \
     "$_tmpd/palette.png"
   ```

4. **GIF render (pass 2)**
   ```bash
   OUTPUT="/home/workdir/artifacts/$(basename "${INPUT%.*}")_${FPS}fps.gif"

   ffmpeg -y -i "$INPUT" -i "$_tmpd/palette.png" \
     -filter_complex "fps=${FPS},scale=${SCALE}:flags=lanczos[x];[x][1:v]paletteuse=dither=sierra2" \
     -loop 0 \
     -an \
     "$OUTPUT"
   ```

5. **Verify & present**
   ```bash
   ls -lh "$OUTPUT"
   ffprobe -hide_banner -i "$OUTPUT"
   ```
   Then use the Render File component to let the user download it.
   Report size, duration, fps to user.

## Lessons from Real Use (e.g. artistic red sunset cowboy video)
- 1080x1080 source at 23 FPS + 480px scale → ~25 MB GIF
- Gradients + dithering = larger files than flat-color GIFs. This is normal.
- For sharing: 360-480px + 12-23 FPS is practical sweet spot.
- Offer re-run with lower params if user wants smaller file.

## Safety & Quality Rules
- Quote all paths and variables.
- Use temp dirs + trap for cleanup.
- Verify output with ffprobe before declaring success.
- Do not overwrite user originals.
- If dimensions odd: add `scale=trunc(iw/2)*2:trunc(ih/2)*2` or similar.
- For very large/long videos: suggest trim first or lower FPS/scale.
- GIF has 256 color limit → complex scenes will dither. Be transparent with user.

## Bonus Features
- User can request extras: trim (`-ss` `-t`), speed change, text overlay, different dither, specific output name, batch processing.
- Combine with core ffmpeg skill knowledge for advanced filters.

This skill delivers reliable, high-quality GIFs while guiding on format limitations and optimization.