tl;dw - YouTube Video Summarizer

tldw - YouTube Video Summarizer

too long; didn't watch

Extract and summarize YouTube video transcripts quickly and efficiently.

Overview

The tldw skill takes a YouTube URL, extracts the video transcript, and provides a comprehensive summary of the content. This allows you to quickly understand video content without watching the entire video.

Purpose

This skill solves the problem of information overload from video content. Instead of spending 10-60 minutes watching a video, you can get the key points, main arguments, and conclusions in a concise summary within seconds.

When to Use

Use this skill when:

How It Works

1. Extraction: Uses yt-dlp to download video transcripts (captions/subtitles) 2. Cleaning: Applies deduplication to remove artifacts from auto-generated captions 3. Processing: Analyzes the cleaned transcript directly in the main agent session 4. Summary: Returns a structured summary with main points, key arguments, and conclusions

Key Features

Attribution

This skill is based on the tldw project by stong. Full attribution and licensing details are available in ATTRIBUTION.md.

Requirements

System Requirements

Required Dependencies

The skill uses a Python virtual environment with the following dependencies:

All dependencies are installed in the local virtual environment at venv/.

Optional Dependencies

Directory Structure

tldw/
├── SKILL.md              # This documentation
├── ATTRIBUTION.md        # Credit to original project
├── LICENSE               # AGPL-3.0 license
├── scripts/
│   └── extract_transcript.py   # Main extraction script
├── cache/                # Cached transcripts (auto-created)
└── venv/                 # Python virtual environment
    ├── bin/
    │   └── yt-dlp        # Video transcript downloader
    └── lib/              # Python packages

Setup

Follow these steps to set up the tldw skill:

1. Navigate to the skill directory:

   cd tldw/
   

2. Create a Python virtual environment:

   python3 -m venv venv
   

3. Install dependencies:

   venv/bin/pip install yt-dlp webvtt-py
   

4. Verify installation:

   venv/bin/yt-dlp --version
   

5. The cache directory will be created automatically on first use

The skill is now ready to use!

Usage Instructions

Basic Usage

When a user provides a YouTube URL and requests a summary, use the following workflow:

1. Extract the transcript using the extraction script 2. Parse the JSON output to get the cleaned transcript 3. Summarize the transcript directly (do not use sub-agents for large transcripts) 4. Return a structured summary to the user

Command Syntax

cd tldw/ && \
venv/bin/python scripts/extract_transcript.py \
  --json --cache-dir cache "YOUTUBE_URL"

Processing the Output

The script returns JSON with the following structure:

{
  "transcript": "Full cleaned transcript text...",
  "video_id": "video_id_here",
  "title": "Video Title",
  "description": "Video description...",
  "duration": 1234,
  "uploader": "Channel Name",
  "upload_date": "20260101",
  "view_count": 12345,
  "webpage_url": "https://www.youtube.com/watch?v=..."
}

Extract the transcript field and process it directly to create a comprehensive summary.

Command Options

Example Workflow

# 1. Extract transcript
cd tldw/ && \
venv/bin/python scripts/extract_transcript.py \
  --json --cache-dir cache "https://www.youtube.com/watch?v=VIDEO_ID"
2. Parse the JSON output and extract the transcript field
3. Summarize the transcript directly (include main points, key arguments, conclusions)
4. Return formatted summary to user

Accessing Age-Restricted Content

For age-restricted or members-only videos, export cookies from your browser:

1. Install a browser extension like "Get cookies.txt LOCALLY" 2. Navigate to YouTube while logged in 3. Export cookies in Netscape format 4. Save to the tldw directory (e.g., youtube_cookies.txt) 5. Use with: --cookies youtube_cookies.txt

Error Handling

No Captions Available

Error message: "No subtitles/captions found"

What it means: The video has no auto-generated or manual captions available.

Solution: Inform the user that the video cannot be transcribed because it lacks captions.

Invalid URL

Error message: "ERROR: unable to download video data"

What it means: The URL is malformed, the video doesn't exist, or it's private/deleted.

Solution: Verify the URL is correct and check if the video is publicly accessible.

Age-Restricted Content

Error message: "Sign in to confirm your age" or similar authentication errors

What it means: The video requires age verification or YouTube login.

Solution: Use the --cookies flag with exported browser cookies (see "Accessing Age-Restricted Content" above).

Network/Connection Errors

Error messages: "Unable to download", "Connection timeout", extraction failures

What it means: Network issues, YouTube blocking the request, or outdated yt-dlp that's incompatible with current YouTube.

Solution: 1. First, update yt-dlp:

   cd tldw/ && \
   venv/bin/pip install --upgrade yt-dlp
   

YouTube frequently changes their API, so keeping yt-dlp updated is essential.

Cache Issues

Symptoms: Permission errors, disk full errors

What it means: The cache directory has permission problems or insufficient disk space.

Solution: Check available disk space with df -h and verify write permissions on the cache/ directory.

Large Transcript Handling

Note: Transcripts over 50,000 characters may take longer to process.

Best practice: Process large transcripts directly in the main agent session. Do not delegate to sub-agents, as they have been found unreliable with large payloads.

Debugging

To see full error output (not just the last 100 lines):

cd tldw/ && \
venv/bin/python scripts/extract_transcript.py \
  --json --cache-dir cache "YOUTUBE_URL"

To inspect cached transcripts:

ls -lh tldw/cache/

Limitations

Caption Dependency

Language Support

Video Length

YouTube-Only

Private/Restricted Content

Deduplication Limitations

No Audio Extraction

Follow these steps to set up the tldw skill:

1. Navigate to the skill directory:

   cd tldw/
   

2. Create a Python virtual environment:

   python3 -m venv venv
   

3. Install dependencies:

   venv/bin/pip install yt-dlp webvtt-py
   

4. Verify installation:

   venv/bin/yt-dlp --version
   

5. The cache directory will be created automatically on first use

The skill is now ready to use!