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

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

Example:

• ❌ [01:30] - User opens the dashboard

• ✅ 01:30 — 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