Video Loop

---
name: video-loop
description: Create a looping background video — crossfade the loop point, encode optimized MP4 + WebM, optional poster frame. Use whenever the user has a video that needs to loop for web use (hero sections, backgrounds, landing-page ambience), wants to fix a visible jump at the loop point, or needs to optimize a clip for web delivery — even if they just say "make this loop smoothly" or "compress this for the site".
when_to_use: When the user has a video that needs to loop without visible artifacts on the web (hero sections, backgrounds), or when the end-to-start transition is visible and needs a crossfade fix, or when optimizing video assets for web delivery (MP4 + WebM). Keywords — loop, video, background, hero, seamless, crossfade, encode, webm, mp4, ffmpeg, compress video, optimize video. For audio loops use `/audio-loop` (sibling — parallel architecture, loudness + gapless FLAC + Web Audio snippet). Skip for audio processing, cuts/trimming beyond looping, or motion-graphics work.
argument-hint: "<input.mp4> [options] — e.g. /video-loop hero.mp4 -d 1.5"
allowed-tools: Bash(ffmpeg *) Bash(ffprobe *) Bash(command *) Bash(bash *) Bash(stat *) Read
license: MIT
metadata:
  author: coroboros
  sources:
    - ffmpeg.org
---

# Video Loop

Create a seamless looping background video from any source clip. A crossfade blends the last and first frames so the `<video loop>` transition is invisible, then the pipeline encodes web-optimized MP4 + WebM.

All ffmpeg work happens in `scripts/video-loop.sh` — this skill validates inputs, optionally helps pick a good fade duration, invokes the script, and turns the script's summary into a human-readable report.

## Parameters

| Flag | Default | Description |
|------|---------|-------------|
| `-d <seconds>` | `1.5` | Crossfade duration in seconds |
| `-q <crf>` | `26` | H.264 CRF — 18 = high quality, 28 = smaller file |
| `-w <crf>` | `32` | VP9 WebM CRF |
| `-o <dir>` | Same as input | Output directory |
| `-p` | off | Also extract a poster frame (first frame as JPEG) |
| `-C` | off | Disable the crossfade — optimize and encode only (`-n` accepted as a deprecated alias) |

> **No `-s/-S` save-mode flag.** Unlike media-cluster siblings (`/audio-loop`, `/markitdown`), video-loop outputs are web assets (MP4 / WebM / poster) the user drops directly into their site's video directory. No downstream skill consumes video files via `-f`, so the `~/.agents/output/<skill>/<project>/` convention would add ceremony without enabling anything — `-o <dir>` is the direct path.

## Workflow

### 1. Validate tools

Confirm `ffmpeg` and `ffprobe` are available: `command -v ffmpeg ffprobe`. If either is missing, stop and ask the user to install (macOS: `! brew install ffmpeg`, Debian/Ubuntu: `! sudo apt install ffmpeg`). Never auto-install.

### 2. Analyze loop quality (optional but recommended)

Before committing to a crossfade, extract the first and last frames and compare them — this is the one step in the pipeline that genuinely benefits from the model's visual reasoning:

```bash
ffmpeg -y -ss 0 -i <input> -frames:v 1 -update 1 /tmp/vl-first.png
ffmpeg -y -sseof -0.1 -i <input> -frames:v 1 -update 1 /tmp/vl-last.png
```

Read both frames. If they're nearly identical, suggest `-C` (the source already loops cleanly, crossfade would only blur motion). If they differ significantly, proceed with the default fade or recommend a longer `-d` for more gradual blending.

### 3. Run the pipeline

`$SKILL_DIR` = this skill's folder — `${CLAUDE_SKILL_DIR}` in Claude Code, the directory containing this SKILL.md elsewhere.

```bash
bash "$SKILL_DIR"/scripts/video-loop.sh <input> [flags]
```

The script does the rest: probes metadata, builds the lossless loop intermediate when crossfade is requested, encodes MP4 (H.264 + faststart) and WebM (VP9), optionally extracts a poster frame. It emits a machine-readable summary on stdout, one `RESULT: key=value` line per fact.

### 4. Report

Parse the `RESULT:` lines to compose:

- A size table comparing input vs outputs (absolute MB and delta percent)
- A ready-to-paste HTML snippet for the user's site

**Report template:**

```
| File | Size | Codec | vs Original |
|------|------|-------|-------------|
| `*-opt.mp4` | X MB | H.264 | -XX% |
| `*.webm` | X MB | VP9 | -XX% |
| `*-poster.jpg` | X KB | JPEG | — |
```

**HTML snippet:**

```html
<video autoplay muted loop playsinline preload="metadata" poster="/videos/poster.jpg">
  <source src="/videos/name.webm" type="video/webm" />
  <source src="/videos/name-opt.mp4" type="video/mp4" />
</video>
```

WebM first — browsers pick the first supported source.

## Why crossfade-first matters

Useful background for debugging "I still see a jump" reports. The script places the xfade at the **start** of the output, not the end:

- `[xfade]` (F seconds): blends `A[end]` → `A[start]`. First frame = `A[D-F]`, last frame = `A[F]`
- `[middle]` (D−2F seconds): untouched frames from `A[F]` to `A[D-F]`

At the loop boundary, `[middle]` ends at `A[D-F]` and the player loops back to `[xfade]`, which starts at the same frame — invisible transition. If the xfade were placed at the end (`[middle][xfade]`), the xfade would end at `A[F]` but loop back to `A[0]` — a visible jump of F seconds.

If the user reports a visible jump despite running the skill, first check whether they pointed at an already-encoded file (re-running re-encodes but doesn't re-loop). If the source is correct, try a longer `-d` — short fades are more visible on high-motion content.

## Rules

- NEVER upscale — the script encodes at source resolution
- NEVER re-encode an already-encoded output (double compression). Always start from the original source
- Audio is always stripped (`-an`) — background videos are muted
- The script rejects `-d >= duration/2` — a too-long fade would leave the middle segment empty
- Always report original vs output sizes so the user sees the quality/size tradeoff