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:

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:

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:

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

Cut a vertical visualizer pack:

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:

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:

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:

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.