---
name: clip-hunter
description: Find, download, scout, cut, and prepare real footage packs for Instagram Reels, YouTube Shorts, YouTube visualizers, music videos, archive edits, mood boards, and beat-synced video workflows. Use when the user asks to hunt clips, scrape or gather footage, find visualizer assets, build a source pack, pull public archive clips, ingest user-provided video URLs, index local footage, make contact sheets, trim footage into vertical or widescreen segments, or prepare clips for visualizer/editing skills.
---


# Clip Hunter

Clip Hunter builds footage packs for fast visualizer work. It searches public archive sources, ingests local files, accepts user-provided public/authorized URLs, generates contact sheets, and cuts footage into edit-ready vertical, square, or widescreen MP4 segments.

## Guardrails

- Do not encode a blanket "scrape anything" rule into the workflow.
- Use public-domain, Creative Commons, government, user-owned, licensed, or user-authorized footage for public deliverables.
- For Instagram, YouTube, TikTok, or other platform URLs, use only user-provided public/authorized URLs. Do not bypass login, paywalls, private accounts, DRM, region blocks, or access controls.
- Keep source URLs, rights notes, and local paths in the manifest. Do not claim a clip is cleared unless the source metadata supports it.

## Quick Start

Search Internet Archive and download candidates:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" search-ia \
  --query "night city neon crowd dance" \
  --download \
  --out-dir ./clip_pack_sources \
  --limit 8
```

Download user-provided public/authorized URLs:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" download-url \
  "https://example.com/video" \
  --out-dir ./clip_pack_sources \
  --rights-note "user supplied; authorized for this edit"
```

Index local footage:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" index-local \
  ~/Downloads ~/Desktop \
  --out-dir ./clip_pack_sources
```

Cut a vertical visualizer pack:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" cut-pack \
  --manifest ./clip_pack_sources/clip_manifest.json \
  --out-dir ./visualizer_clips \
  --profile instagram-reel \
  --segments 24 \
  --segment-duration 2.0 \
  --contact-sheet
```

## Workflow

1. Pick the target: `instagram-reel`, `youtube-short`, `youtube-16x9`, `square`, or `source`.
2. Gather source material:
   - Use `search-ia` for public archive footage.
   - Use `download-url` for user-provided public/authorized URLs.
   - Use `index-local` for local libraries, downloads, camera folders, or assets from other skills.
3. Make contact sheets before editing if the footage is unfamiliar.
4. Cut a short segment pack with `cut-pack`.
5. Hand the resulting folder and `cut_manifest.json` to visualizer, Black Mirror, ffmpeg, Premiere, Sora remix, or any video edit workflow.

## Commands

Create a contact sheet:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" contact-sheet \
  --input ./clip_pack_sources/source.mp4 \
  --out ./source-contact.jpg \
  --cols 6 \
  --rows 5
```

Cut one clip:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" cut \
  --input ./source.mp4 \
  --start 12.4 \
  --duration 2.0 \
  --profile youtube-short \
  --out ./cut_001.mp4
```

List available render profiles:

```bash
python3 "$HOME/.codex/skills/clip-hunter/scripts/clip_hunter.py" profiles
```

## Source Taste

Read `references/source-veins.md` when a search needs stronger keywords. Good visualizer clips usually have motion, silhouettes, crowds, signs, screens, machines, hands, city lights, old cameras, analog damage, hard shadows, or strong graphic shapes.

## Dependencies

- `ffmpeg` and `ffprobe` are required for contact sheets and cutting.
- `yt-dlp` is required for `download-url`.
- Network access is required for `search-ia` and `download-url`.