Most YouTube transcript tools either require paid APIs, use suspicious proxies, or just dump raw text without structure. This skill extracts transcripts locally using yt-dlp, preserves timestamps for navigation, detects chapters automatically, and exports to any format you need.

When to Use

User shares a YouTube link and wants to read instead of watch. User asks what someone says about a topic at a specific moment. User needs to extract quotes with timestamps for research or content creation. User wants to summarize a video or search within its content.

How It Works

CODEBLOCK0

The Extraction Process

1. 📋 Get Metadata First

Always fetch video info before extracting subtitles:

CODEBLOCK1

This gives you title, duration, official chapters, and available languages. Use it to confirm the right video and check what subtitles exist.

2. 📝 Prefer Manual Subtitles

Manual (uploaded) subtitles are higher quality than auto-generated:

CODEBLOCK2

Auto-generated transcripts often have errors, missing punctuation, and wrong word boundaries. Manual subtitles are human-verified.

3. 🕐 Preserve Timestamps Always

Every segment must include timestamps. Format: [HH:MM:SS] or [MM:SS] for videos under 1 hour.

Why this matters: Users need to jump to specific moments. "Take me to where they discuss pricing" requires knowing the timestamp.

Output format:
CODEBLOCK3

Chapter Detection

From Video Markers

Many videos have chapter markers embedded. Extract from metadata:

CODEBLOCK4

Smart Detection (No Markers)

When video lacks chapters, detect natural breaks from transcript:

• - Topic changes (semantic shift in content)
• Speaker changes (different voice patterns)
• Explicit transitions ("Now let's talk about...", "Moving on...")
• Long pauses between segments

Search Within Transcripts

When user asks "where do they talk about X":

1. 1. Search transcript for keywords and semantic matches
2. Return segments with timestamps
3. Include surrounding context (10-15 seconds before/after)

Response format:
CODEBLOCK5

Generate clickable links: INLINECODE2

Architecture

Memory lives in ~/youtube-video-transcript/. See memory-template.md for structure.

CODEBLOCK6

Quick Reference

Topic	File
Setup process	INLINECODE5
Memory template

memory-template.md | | Advanced patterns | patterns.md |

Core Rules

1. Metadata Before Extraction

Always run yt-dlp -j URL first. This confirms the video, shows available languages, and reveals official chapters. Never extract blind.

2. Manual Over Auto

Subtitle Type	Quality	When to Use
Manual	High	Always try first
Auto-generated

Medium | Fallback only |

Check with yt-dlp --list-subs URL for unfamiliar channels.

3. Timestamps Are Sacred

Never strip timestamps during any operation. They enable navigation, citation, and deep linking into the video.

4. Cache With Consent

User Response	Action
"Yes, save it"	Cache to ~/youtube-video-transcript/videos/
"No thanks"

Don't cache, show once | | Not asked yet | Ask after first extraction |

Always tell user where files are saved and offer to show or delete them.

5. Handle Multiple Languages

If user doesn't specify:

1. 1. Check available languages
2. Prefer manual over auto
3. Default to English
4. Report which language was used

CODEBLOCK7

6. Quote Extraction Includes Context

When extracting quotes for research:

• - 10-15 seconds before/after for context
• Exact timestamp for the quote start
• Speaker identification if multiple speakers

7. Transparency on Quality

Subtitle Type	Tell User
Manual	"Using official subtitles"
Auto-generated

"Using auto-generated (may have errors)" | | None available | "No subtitles found for this video" |

Export Formats

Format	Use Case	Command
Markdown	Reading, notes	Default
SRT

Video editors | --sub-format srt | | Plain text | Search, grep | Strip timestamps | | JSON | Programmatic | --write-info-json |

Common Traps

Trap	Consequence	Prevention
Not checking subtitles first	Wasted time on unavailable video	Always --list-subs first
Ignoring auto-generated quality

Garbage text with errors | Prefer manual, warn about auto | | Losing timestamps | Can't navigate video | Never strip in any operation | | Extracting without metadata | Missing title, chapters | Always fetch -j first | | Caching without consent | Privacy violation | Ask before saving |

Quick Commands

User Says	Action
"Transcribe this video"	Extract + display
"What do they say about X?"

Search + timestamps | | "Save this transcript" | Cache with confirmation | | "Export as SRT" | Convert format | | "Show saved videos" | List ~/youtube-video-transcript/videos/ | | "Delete video X" | Remove from cache |

Security & Privacy

Data that stays local (with your consent):

• - Transcripts cached in ~/youtube-video-transcript/ (only if you agree)
• Preferences stored locally (only after confirmation)
• No external API calls beyond YouTube's public subtitle endpoints

Transparency guarantees:

• - Always asks before saving transcripts locally
• Tells you where files are saved
• Offers to show or delete saved data anytime

This skill does NOT:

• - Use proxy services or third-party APIs
• Send your queries to external services
• Store credentials or authentication
• Save anything without your explicit consent

Related Skills

Install with clawhub install <slug> if user confirms:

• - summarizer — create summaries from any content
• INLINECODE16 — generate and edit video subtitles
• INLINECODE17 — advanced video and audio processing

Feedback

• - If useful: INLINECODE18
• Stay updated: INLINECODE19