SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsyoutube-video-context

youtube-video-context

General & other

View repository

Updated 10-16 08:48

About this skill

YouTube Video Context

Turn a public YouTube video, playlist, or search topic into a local context pack before using it as coding, design, QA, or product context. This skill is evidence-oriented: agents should read generated codex_context.md files first, then inspect captions, manifests, or sampled frames only when a claim needs timestamp support.

How It Works

  1. Resolve the source as a single video, playlist, or bounded search.
  2. Capture metadata with yt-dlp when available.
  3. Download captions unless the caller asks for a faster Gemini-first run with --skip-captions.
  4. Ask Gemini to analyze the public YouTube URL when GEMINI_API_KEY or GOOGLE_API_KEY is set.
  5. Optionally download media and sample frames when local visual evidence is required.
  6. Write a portable context pack under .codex/video-context/.

Setup

Run the setup checker from this skill directory:

python scripts/setup_youtube_context.py

To install yt-dlp into the current Python user environment:

python scripts/setup_youtube_context.py --install-yt-dlp

For best visual/audio analysis, set a Gemini key in the shell before ingesting:

export GEMINI_API_KEY="..."

PowerShell:

$env:GEMINI_API_KEY = "..."

Do not paste API keys into prompts, SKILL.md, generated context packs, source files, or issue/PR comments.

Usage

Single video:

python scripts/ingest_youtube_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --focus "extract implementation-relevant UI, mechanics, and timestamped evidence"

Playlist:

python scripts/ingest_youtube_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --max-videos 8 --focus "extract reusable UI and gameplay references"

Search topic:

python scripts/ingest_youtube_video.py "cozy factory automation UI references" --source-type search --max-videos 5 --focus "find implementation inspiration for management-game HUDs"

Fast Gemini-first pass:

python scripts/ingest_youtube_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --skip-captions --json

Local frame evidence:

python scripts/ingest_youtube_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --download-video --sample-interval 3

Arguments

  • source: Public YouTube URL, playlist URL, or search topic.
  • --source-type auto|video|playlist|search: Override source detection. Auto treats playlist URLs and list= watch URLs as playlists; non-URL text as search.
  • --max-videos N: Bound playlist/search ingestion. Defaults to 5.
  • --focus TEXT: Tell the analyzer what evidence the downstream task needs.
  • --model MODEL: Gemini model. Defaults to GEMINI_MODEL or gemini-flash-latest.
  • --no-gemini: Skip Gemini direct video analysis.
  • --skip-captions: Skip caption download for a quicker pass.
  • --download-video: Download media for frame extraction.
  • --sample-interval N: Seconds between sampled frames when downloading media.
  • --json: Print a machine-readable result object.

Output

Single-video packs:

.codex/video-context/<video-id>/
  metadata.json
  captions/
  gemini_video_analysis.md
  codex_context.md
  run_manifest.json

Playlist and search runs also write:

.codex/video-context/_collections/<collection-slug>/
  collection_manifest.json
  codex_context.md

Present Results To User

Report the context pack path, the first-read codex_context.md file, whether captions/Gemini/frames were captured, and any missing dependency or rejected-key warnings. Keep design or implementation conclusions tied to timestamps when available.

Troubleshooting

  • yt-dlp is required for playlist expansion and search discovery: run python scripts/setup_youtube_context.py --install-yt-dlp.
  • ffmpeg was not found: frame extraction needs ffmpeg, but normal metadata/caption/Gemini ingestion can continue without it.
  • Gemini reports HTTP 400, 401, or 403: rotate or create a Google AI Studio key, set GEMINI_API_KEY, and rerun.
  • No timestamps were produced: inspect captions or rerun with a narrower --focus; do not invent exact timing.

References

  • references/context-pack-format.md documents the artifact contract.
  • scripts/ingest_youtube_video.py is the implementation surface.
  • scripts/test_ingest_youtube_video.py contains offline unit tests for discovery and context-pack behavior.