Video Context

---
name: video-context
description: Extract scene-change frames + audio transcript from any video so Claude can "watch" it. Use when user pastes a video URL or local video file path and asks to analyze, watch, summarize, or debug from a video. Triggers on .mp4/.mov/.webm/.mkv paths, video URLs (Loom, YouTube, raw mp4, private attachments), or phrases like "analyze this video", "watch this", "see the recording", "video shows the bug".
---

# video-context

Claude reads images, not videos. This skill turns any video into scene-change frames + audio transcript so Claude can reason about it.

Standalone — works on any source: local file, public URL, or private URL with auth.

## When to use

User shares a video and wants Claude to understand its content. Examples:
- "Analyze this video: <url>"
- "What does this recording show? /path/to/file.mp4"
- "The bug is in this Loom: https://loom.com/share/..."
- Bug ticket (Jira/Asana/GitHub/Linear) contains a video attachment.

## How to use

```
${CLAUDE_PLUGIN_ROOT}/skills/video-context/extract.sh <url-or-path>
```

Script auto-resolves the source:

| Source | How it's fetched |
|---|---|
| Local file path | Used directly. |
| Public URL (Loom, YouTube, Vimeo, public CDN, raw mp4) | `yt-dlp` first, falls back to `curl`. |
| Private URL needing auth | `curl` with `VIDEO_AUTH_HEADER` env var. |

### Private URL with auth

Set `VIDEO_AUTH_HEADER` to whatever the host needs:

```bash
# Bearer token
VIDEO_AUTH_HEADER="Authorization: Bearer $TOKEN" \
  ${CLAUDE_PLUGIN_ROOT}/skills/video-context/extract.sh "https://host.example/asset/123"

# Basic auth (e.g. Atlassian email + API token)
VIDEO_AUTH_HEADER="Authorization: Basic $(echo -n "$EMAIL:$TOKEN" | base64)" \
  ${CLAUDE_PLUGIN_ROOT}/skills/video-context/extract.sh "https://your-org.atlassian.net/rest/api/3/attachment/content/12345"
```

If user shares a private URL without a token, ask for one — or tell them to download the video and paste the local path.

## After it runs

Script prints `WORKDIR`, frame paths, transcript path. Then:

1. **`Read` each frame** — Claude sees JPEGs natively.
2. **`Read` the transcript** at `$WORKDIR/transcript.txt`.
3. Combine frames + transcript to answer the user.

## Tuning (env vars)

| Var | Default | What |
|---|---|---|
| `SCENE_THRESHOLD` | `0.4` | Lower = more frames. Screen recordings often need `0.2`. |
| `MAX_FRAMES` | `20` | Hard cap; trimmed evenly across timeline. |
| `FRAME_WIDTH` | `1280` | Downscale to save tokens. |
| `WHISPER_MODEL` | `/opt/homebrew/share/whisper-cpp/ggml-base.en.bin` | whisper-cpp model path. |

## Requirements

- `ffmpeg` (required)
- `yt-dlp` (recommended — handles Loom/YouTube/Vimeo)
- `whisper-cpp` + model (optional — for audio transcript)

Run `/video-context:setup` once for full install on macOS or Linux (apt/dnf/pacman/zypper; builds whisper-cpp from source). On macOS, `extract.sh` also auto-installs missing binaries via `brew` on first run; the whisper model (~150MB) is only fetched by setup.

Windows: install manually.