y2b-nuggets

Extract the most valuable clips ("nuggets") from YouTube videos automatically using Claude Code.

Overview

This project provides a Claude Code skill that analyzes YouTube video transcripts to find high-value segments based on controversy, insightful analysis, or user-specified topics. It then downloads those clips with burned-in subtitles ready for social media sharing.

Features

• Smart Clip Detection: Uses AI to identify the most engaging, controversial, or insightful moments
• Automatic Subtitles: Burns subtitles directly into videos using Whisper for accurate timestamps
• Complete Sentence Boundaries: Ensures clips start and end with complete thoughts, not mid-sentence
• Retry Logic: Handles YouTube's intermittent 403 errors gracefully
• Progress Reporting: Clear console output showing each stage of extraction

Dependencies

Before using, ensure you have these tools installed:

# Check if installed
command -v yt-dlp || echo "MISSING: yt-dlp"
command -v ffmpeg || echo "MISSING: ffmpeg"

Installation

macOS (Homebrew):

brew install yt-dlp ffmpeg

Linux:

sudo apt update && sudo apt install -y yt-dlp ffmpeg

Python (for subtitles with Whisper):

pip install stable-ts

Usage

Simply provide Claude Code with a YouTube URL and ask for clips:

Extract the best clips from https://www.youtube.com/watch?v=VIDEO_ID

Or be more specific:

Get 3 clips about "startup funding" from https://youtube.com/watch?v=VIDEO_ID

What Gets Created

For each video, a timestamped folder is created with clips organized like:

clips/
└── 2024-01-15_10-30-00_video-title/
    ├── segments.json              # Parsed transcript with timestamps
    ├── full_transcript.txt        # Complete transcript for reference
    └── 01_clip_title/
        ├── Clip Title metadata.json     # Selection rationale & scores
        ├── Clip Title Transcript.txt    # Human-readable transcript
        ├── Clip Title Video.mp4         # Raw video clip
        └── Clip Title Subtitled.mp4     # Video with burned-in captions

How It Works

1. Fetch Video Info: Gets video metadata and duration
2. Download Transcript: Prioritizes manual subtitles → auto-generated → Whisper
3. Analyze Content: Scores segments on controversy, insight, engagement, and relevance
4. Extract Clips: For each selected clip:
   • Creates metadata with selection rationale
   • Extracts transcript with proper sentence boundaries
   • Downloads video at exact timestamps
   • Burns in subtitles for social sharing

Scoring Criteria

Clips are scored on:

Signal	Weight	Examples
Controversy	30%	"I disagree", strong opinions, debate markers
Insight	35%	Statistics, predictions, frameworks, expert knowledge
Engagement	20%	Rhetorical questions, stories, emotional peaks
Topic Match	15%	Keyword presence (40% if user specified topics)

Available Scripts

The skill includes helper scripts in .claude/skills/get-y2b-clips/:

Script	Purpose
parse_vtt.py	Parse VTT subtitles into segments.json
extract_transcript.py	Extract transcript with sentence boundary detection
download_clip.py	Download video clip with retry logic
burn_subtitles.py	Generate subtitled video with Whisper or YouTube transcript
utils.py	Shared utilities for timestamp parsing

Clip Duration Guidelines

Video Length	Recommended Clips	Default Clip Length
< 15 min	1-2	30-60 seconds
15-30 min	2-3	45-90 seconds
30-60 min	3-4	60-120 seconds
1-2 hours	4-5	90-180 seconds
> 2 hours	5-7	90-180 seconds