youtube-analysis

YouTube Analysis

Extract transcripts from YouTube videos and produce structured concept analysis — key ideas, arguments, technical terms, takeaways, and multi-level summaries — all without API keys or MCP servers.

Reference Files

File	Purpose
scripts/fetch_transcript.py	Core transcript + metadata fetcher (CLI + importable)
scripts/analyze_video.py	Orchestrator: fetch → structure → export scaffold
scripts/utils.py	URL parsing, timestamp formatting, transcript chunking
references/analysis-patterns.md	Prompt patterns for each video type
assets/output-template.md	Markdown template for final output

Workflow

User provides YouTube URL
        │
        ▼
┌─────────────────────┐
│  Step 0: Deps check │
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 1: Parse URL  │
└────────┬────────────┘
         ▼
┌─────────────────────┐     ┌──────────────┐
│  Step 2: Transcript │────▶│  yt-dlp      │
│  (youtube-t-api)    │fail │  (fallback)  │
└────────┬────────────┘     └──────┬───────┘
         │◀───────────────-────────┘
         ▼
┌─────────────────────┐
│  Step 3: Metadata   │
│  (yt-dlp --dump-json│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 4: Claude     │
│  analyzes transcript│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 5: Export MD  │
└─────────────────────┘

Step 0: Ensure Dependencies

Before running any script, verify dependencies are installed:

uv pip install youtube-transcript-api yt-dlp -q

Or run scripts directly with uv run:

uv run --with youtube-transcript-api --no-project python scripts/fetch_transcript.py "URL"

Verify:

python -c "from youtube_transcript_api import YouTubeTranscriptApi; print('OK')"
yt-dlp --version

Step 1: URL Parsing and Validation

Use scripts/utils.py:parse_youtube_url() to extract the video ID. Supported formats:

Format	Example
Standard watch	youtube.com/watch?v=dQw4w9WgXcQ
Short URL	youtu.be/dQw4w9WgXcQ
Shorts	youtube.com/shorts/dQw4w9WgXcQ
Embed	youtube.com/embed/dQw4w9WgXcQ
Live	youtube.com/live/dQw4w9WgXcQ
With params	youtube.com/watch?v=dQw4w9WgXcQ&t=120&list=PLxxx
Bare ID	dQw4w9WgXcQ
Mobile	m.youtube.com/watch?v=dQw4w9WgXcQ
Music	music.youtube.com/watch?v=dQw4w9WgXcQ

If parsing fails, ask the user to provide the URL in a standard format.

Step 2: Transcript Extraction

Run fetch_transcript.py to get the transcript:

cd <skill_dir>/scripts
python fetch_transcript.py "YOUTUBE_URL" --lang en

This outputs JSON to stdout. The script:

1. Primary path: Uses youtube-transcript-api to scrape captions directly (no API key)
2. Fallback path: If primary fails, uses yt-dlp --write-sub --write-auto-sub to extract subtitle files
3. Language handling: Tries requested language first, falls back to any available transcript

The returned JSON contains both individual timestamped segments and a joined transcript_text field.

Or import as a module (used by analyze_video.py):

from fetch_transcript import fetch_video
data = fetch_video("https://youtube.com/watch?v=VIDEO_ID", lang="en")

Step 3: Metadata Extraction

Metadata is fetched automatically by fetch_transcript.py via yt-dlp --dump-json:

• Title, channel name
• Duration (seconds)
• Upload date (YYYY-MM-DD)
• Description (first 500 chars in scaffold)
• View count
• Tags

No separate step needed — fetch_video() returns everything.

Step 4: Concept Analysis

This is where you (Claude) do the work. The scripts provide raw data; you perform the analysis.

Analysis Depth

Choose based on user request or video duration:

Depth	When to Use	Sections to Fill
quick	User wants fast overview, or video < 10 min	TL;DR, Key Concepts, Takeaways
standard	Default for most videos	All template sections
deep	User wants thorough breakdown, or video > 30 min	All sections + timestamped section-by-section

Analysis Process

1. Read the full transcript from the JSON output
2. Identify the video type (or use user-provided hint). See references/analysis-patterns.md for type-specific guidance
3. Extract key concepts: Main ideas, arguments, claims — each as a bullet with brief explanation
4. Identify technical terms: Definitions as presented in the video
5. Pull notable statements: Paraphrase key quotes with approximate timestamps
6. Synthesize takeaways: Actionable items the viewer should consider
7. Write the TL;DR: One to three sentences capturing the core message
8. Suggest related topics: Based on concepts mentioned, what should the viewer explore next

For Deep Analysis

Use utils.chunk_transcript() to break the transcript into 5-minute segments, then analyze each chunk with timestamps:

from utils import chunk_transcript
chunks = chunk_transcript(data["transcript"], chunk_minutes=5)
for chunk in chunks:
    print(f"[{chunk['start_formatted']} - {chunk['end_formatted']}]")
    print(chunk["text"])

Or run the orchestrator with --depth deep:

python analyze_video.py "YOUTUBE_URL" --depth deep

Video Type Patterns

Type	Key Extraction Focus	See
Lecture	Thesis, arguments, citations, definitions	references/analysis-patterns.md
Tutorial	Steps, tools, prerequisites, gotchas	references/analysis-patterns.md
Interview	Perspectives, disagreements, attributed positions	references/analysis-patterns.md
Podcast	Topic threads, opinions, recommendations	references/analysis-patterns.md
Tech Talk	Architecture, trade-offs, benchmarks, lessons	references/analysis-patterns.md
Panel	Consensus vs. disagreement, per-speaker views	references/analysis-patterns.md

Read references/analysis-patterns.md for detailed extraction guidance per type.

Step 5: Export to Markdown

The orchestrator generates a scaffold:

cd <skill_dir>/scripts
python analyze_video.py "YOUTUBE_URL" --output ./analysis.md --depth standard --type auto

Flags:

• --output PATH: Where to write (default: ./{sanitized_title}.md)
• --depth quick|standard|deep: Analysis depth
• --type auto|lecture|tutorial|interview|podcast|tech-talk|panel: Video type hint
• --lang CODE: Transcript language (default: en)
• --json: Output raw JSON instead of Markdown scaffold

The scaffold contains populated metadata and [TO BE ANALYZED] placeholders. Claude replaces these with actual analysis.

Preferred workflow: Run fetch_transcript.py to get JSON, analyze in context, then produce the final Markdown directly using assets/output-template.md as the structure guide. The orchestrator is useful for batch processing or when the user wants a file written.

Error Handling

Error	Exit Code	Cause	Resolution
URL parse failure	1	Invalid or unsupported URL format	Ask user for standard YouTube URL
No transcript	2	Video has no captions (manual or auto)	Inform user; suggest a different video
Video unavailable	1	Private, deleted, or geo-blocked	Inform user of the restriction
Age-restricted	1	Requires authentication	Inform user; yt-dlp may work with cookies
Metadata fetch fail	0	yt-dlp network issue	Transcript still works; metadata shows "Unknown"
Language unavailable	0	Requested lang not available	Auto-falls back to available language
yt-dlp not installed	1	Missing dependency	Run Step 0 dependency installation

Limitations

• No visual analysis: Transcript-only; slides, diagrams, code on screen, and demos are not captured. Note this in output when relevant.
• Auto-caption quality: Auto-generated captions may contain errors, especially for technical terms, proper nouns, and non-English accents.
• Music videos: Lyrics may not be available as captions. Music-only content produces poor results.
• Live streams: Ongoing live streams may have incomplete or unavailable transcripts.
• Rate limiting: Excessive requests to YouTube may trigger temporary blocks. Space requests if processing multiple videos.
• Language coverage: Best results for English. Other languages depend on caption availability and quality.
• Speaker attribution: Transcripts rarely identify individual speakers. Claude infers from context where possible.