YouTube Video Analyzer

Analyze YouTube videos with Gemini and extract screenshots at key moments.

Agent Workflow

IMPORTANT: Cursor agents must use required_permissions: ["all"] when running the shell command. The default sandbox blocks network access, causing DNS errors like [Errno 8] nodename nor servname provided, or not known.

cd ~/brain/git/personal/agent-instructions

Basic Usage

poetry run python scripts/youtube_analyzer.py analyze \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output ~/brain/obsidian/Timatron/Raw\ Transcripts\ \&\ Research/research/

Multiple Videos

poetry run python scripts/youtube_analyzer.py analyze \
  "https://www.youtube.com/watch?v=VIDEO1" \
  "https://www.youtube.com/watch?v=VIDEO2" \
  --output ~/brain/obsidian/Timatron/Raw\ Transcripts\ \&\ Research/research/

With Custom Title and Prompt

poetry run python scripts/youtube_analyzer.py analyze \
  "https://youtu.be/VIDEO_ID" \
  --title "AI Agent Architecture Review" \
  --prompt "Focus on the technical implementation details" \
  --output ~/brain/obsidian/Timatron/Raw\ Transcripts\ \&\ Research/research/

Skip Screenshots (Analysis Only)

poetry run python scripts/youtube_analyzer.py analyze \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --no-screenshots \
  --output ~/brain/obsidian/Timatron/Raw\ Transcripts\ \&\ Research/research/

Prompt Templates

Use --prompt to focus the analysis. Here are useful patterns:

Product Demo Analysis

For product walkthroughs, demos, or UI tours:

--prompt "Give me (1) a deep step-by-step analysis of the workflow steps, with as much detail as you can glean about what exactly the user is doing in the UI (what features they're using, what values they're entering, etc.). Link each step to the right timestamp. Then (2) produce a concise bullet point summary that (a) synthesizes what this product does (b) summarizes the features it has and (c) summarizes the workflow shown."

Minute-by-Minute Summary

For talks, interviews, or educational content:

--prompt "Give me a bullet point list, one bullet per minute, with each bullet summarizing what was said in that minute. Group bullets under topic headings where natural. At the top add a concise 10 bullet point summary of the whole video."

Options

Option	Description
urls	One or more YouTube URLs (positional, required)
--output	Output directory (default: current dir)
--title	Custom report title
--prompt	Additional analysis instructions
--no-media	Skip screenshot and clip extraction
--max-screenshots	Max screenshots per video (default: 5)
--max-clips	Max clips per video (default: 3)
--model	Gemini model (default: gemini-2.5-flash)
--profile	Google API profile name

Output

Creates a markdown file at {output}/youtube-analysis-{date}.md with:

• Video metadata (title, channel, URL, duration)
• AI-generated summary
• Key points with timestamps
• Screenshots for static content (diagrams, slides, code)
• Animated clips for dynamic content (demos, UI interactions, animations)

Timestamp Formatting

All timestamps MUST be clickable links to the YouTube video at that moment.

Format: **[MM:SS](https://www.youtube.com/watch?v=VIDEO_ID&t=XXs)**

Where XX is the timestamp converted to seconds (e.g., 01:30 = 90s).

Example:

• ❌ **[01:30]** - User opens the dashboard
• ✅ **[01:30](https://www.youtube.com/watch?v=abc123&t=90s)** — User opens the dashboard

When consolidating YouTube analyses into reports, ensure ALL timestamps (in Key Points, Screenshots, Clips sections) are linked.

Media Files

Saved to ~/brain/obsidian/Timatron/attachments/:

Type	Format	Naming	Purpose
Screenshot	PNG	yt-{video_id}-{MMmSSs}.png	Static visuals
Clip (preview)	GIF	yt-{video_id}-{MMmSSs}-{duration}s.gif	Auto-plays in Obsidian
Clip (AI)	MP4	yt-{video_id}-{MMmSSs}-{duration}s.mp4	High-quality for AI consumption

Clips are extracted as both GIF (for Obsidian autoplay) and MP4 (for AI model consumption). GIFs are embedded in the report; MP4 paths are noted for reference.

Usage Stats

After each run, the script displays detailed usage statistics:

==================================================
USAGE STATS
==================================================
  Model: gemini-2.5-flash
  Videos analyzed: 1
  Screenshots extracted: 5
  Clips extracted: 3 (GIF + MP4 each)

  Input tokens: 155,332
  Output tokens: 1,050
  Total tokens: 158,359

  Analysis time: 57.1s
  Media extraction time: 16.4s
  Total time: 73.9s

  Estimated cost: $0.0492
==================================================

Pricing (per 1M tokens):

Model	Input	Output
gemini-2.5-flash	$0.30	$2.50
gemini-2.5-pro	$2.50	$15.00
gemini-2.0-flash	$0.10	$0.40

API Key Setup

Edit ~/.config/google/profiles.json:

{
  "default": "personal",
  "profiles": {
    "personal": {
      "api_key": "AIza..."
    }
  }
}

Get an API key from: https://aistudio.google.com/apikey

Requirements

• ffmpeg: Required for screenshot extraction (brew install ffmpeg)
• yt-dlp: Installed via poetry dependencies

Limitations

• Only works with public YouTube videos (not private/unlisted)
• Free tier: 8 hours of YouTube video per day
• Videos longer than 1 hour use more tokens (~300 tokens/second)

Troubleshooting

• "[Errno 8] nodename nor servname provided": Cursor sandbox is blocking network access. Use required_permissions: ["all"] in the Shell tool call.
• "ModuleNotFoundError: No module named 'google'": Run poetry install first to install dependencies.
• "API key not found": Configure ~/.config/google/profiles.json
• "Video unavailable": Check if video is public and URL is correct
• "ffmpeg not found": Install with brew install ffmpeg
• No screenshots extracted: Ensure ffmpeg is installed and video downloaded successfully