fetch-youtube-transcript

name	fetch-youtube-transcript
description	Download YouTube video transcripts as readable text files. Use when extracting transcripts from videos for analysis, documentation, or content review.
argument-hint	<video-url-or-id> [--output DIR] [--language LANG]

YouTube Transcript Download Skill

Purpose

Download transcripts from YouTube videos as readable text files with timestamps. This skill wraps the youtube-transcript-api tool with a simple interface for quick transcript extraction.

Usage

/fetch-youtube-transcript <video-url-or-id> [--output DIR] [--language LANG]

Arguments

Required

• <video-url-or-id>: YouTube video URL or video ID
  • Full URLs: https://www.youtube.com/watch?v=VIDEO_ID
  • Short URLs: https://youtu.be/VIDEO_ID
  • Video ID only: VIDEO_ID (11 characters)
  • URLs with timestamps and query parameters are supported

Optional

• --output DIR: Output directory for transcript files

  • Default: .work/transcripts/
  • Directory will be created if it doesn't exist
  • Transcript saved as VIDEO_ID.txt

• --language LANG: Preferred transcript language code

  • Default: Auto-select (usually English if available)
  • Examples: en, es, fr, de, ja
  • Falls back to auto-generated if manual transcript unavailable

Execution Instructions for Claude Code

When the user invokes /fetch-youtube-transcript, follow these steps:

1. Parse Arguments

Extract the video URL/ID and optional parameters from the user's command:

# Example argument parsing logic
import re
from pathlib import Path

def parse_args(args_string):
    """Parse /fetch-youtube-transcript arguments."""
    parts = args_string.split()

    if not parts:
        return None, None, None, "Error: Video URL or ID required"

    video_url = parts[0]
    output_dir = ".work/transcripts"
    language = None

    # Parse optional flags
    i = 1
    while i < len(parts):
        if parts[i] == "--output" and i + 1 < len(parts):
            output_dir = parts[i + 1]
            i += 2
        elif parts[i] == "--language" and i + 1 < len(parts):
            language = parts[i + 1]
            i += 2
        else:
            i += 1

    return video_url, output_dir, language, None

2. Construct Command

Build the uvx command to run the transcript fetcher:

uvx --from youtube-transcript-api \
  python scripts/fetch-youtube-transcript.py \
  "<video-url>" \
  --output "<output-dir>"

If language is specified, add --language <lang>.

Important:

• The script is bundled with this plugin at scripts/fetch-youtube-transcript.py
• Quote the video URL to handle special characters
• Use the full path to the script in the plugin cache directory

3. Execute Command

Run the command using the Bash tool with appropriate error handling:

# Construct full command
cmd_parts = [
    "uvx --from youtube-transcript-api",
    "python scripts/fetch-youtube-transcript.py",
    f'"{video_url}"',
    f"--output {output_dir}"
]

if language:
    cmd_parts.append(f"--language {language}")

command = " ".join(cmd_parts)

# Execute via Bash tool
# The script will handle all video ID extraction and error cases

4. Handle Output

The script outputs structured information on success:

✅ Transcript downloaded successfully!

Video: 4_2j5wgt_ds
File: .work/transcripts/4_2j5wgt_ds.txt
Entries: 851

Parse this output and report to the user:

• Confirm successful download
• Show the output file location
• Indicate the number of transcript entries

5. Handle Errors

The script returns non-zero exit codes and error messages for failures:

Common error scenarios:

1. Invalid URL format

   ❌ Error: Invalid YouTube URL or video ID
   

   Report: "The provided URL or video ID is invalid. Please provide a valid YouTube URL or 11-character video ID."

2. No transcript available

   ❌ Error: No transcript found for video
   Could not retrieve a transcript for the video ID
   

   Report: "No transcript is available for this video. The creator may have disabled transcripts."

3. Video unavailable

   ❌ Error: Video unavailable or private
   

   Report: "The video is unavailable, private, or has been deleted."

4. Network errors

   ❌ Error: Network request failed
   

   Report: "Failed to connect to YouTube. Please check your internet connection."

5. Invalid output directory

   ❌ Error: Cannot create output directory
   

   Report: "Failed to create output directory. Please check permissions."

6. Report Success

On successful execution, provide a clear summary:

✅ Transcript downloaded successfully!

📹 Video ID: 4_2j5wgt_ds
📄 File: .work/transcripts/4_2j5wgt_ds.txt
📊 Entries: 851 transcript segments

You can now read the transcript file or use it for analysis.

Output Format

Transcripts are saved as plain text files with the following format:

[00:00] Welcome to this video about Product Forge!
[00:15] Today we'll be exploring how to build custom Claude Code plugins.
[00:32] First, let's talk about the plugin architecture.
...

Each line contains:

• Timestamp: [MM:SS] format for easy navigation
• Text: The spoken content at that timestamp

The format is designed for:

• Easy reading and searching
• Simple parsing if needed for analysis
• Clear temporal context

Examples

Example 1: Basic Usage

Download a transcript using a full YouTube URL:

/fetch-youtube-transcript "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Result:

• Transcript saved to .work/transcripts/dQw4w9WgXcQ.txt
• Auto-selected language (usually English)

Example 2: Custom Output Directory

Save transcript to a specific directory:

/fetch-youtube-transcript "https://youtu.be/dQw4w9WgXcQ" --output ./transcripts

Result:

• Transcript saved to ./transcripts/dQw4w9WgXcQ.txt
• Directory created if it doesn't exist

Example 3: Specific Language

Request a Spanish transcript:

/fetch-youtube-transcript "dQw4w9WgXcQ" --language es

Result:

• Spanish transcript if available
• Falls back to auto-generated Spanish if manual unavailable
• Error if Spanish not available at all

Example 4: Video ID Only

Use just the video ID:

/fetch-youtube-transcript "dQw4w9WgXcQ"

Result:

• Same as full URL
• Simpler syntax for known video IDs

Error Handling

Validation Errors

Missing URL:

/fetch-youtube-transcript

Response: "Error: Video URL or ID required. Usage: /fetch-youtube-transcript [--output DIR]"

Invalid URL format:

/fetch-youtube-transcript "not-a-youtube-url"

Response: "Error: Invalid YouTube URL or video ID. Please provide a valid YouTube URL or 11-character video ID."

API Errors

No transcript available:

• The video creator has disabled transcripts
• Automatic captions are disabled
• Video is too new (transcripts not yet generated)

Response: "No transcript available for this video. The creator may have disabled transcripts or automatic captions."

Video unavailable:

• Video is private or unlisted
• Video has been deleted
• Video is region-restricted

Response: "Video is unavailable. It may be private, deleted, or region-restricted."

Network Errors

Connection failed:

• Internet connection issues
• YouTube API temporarily unavailable

Response: "Failed to connect to YouTube. Please check your internet connection and try again."

Rate limiting:

• Too many requests in short time
• YouTube API quota exceeded

Response: "Request rate limited. Please wait a moment and try again."

Implementation Tips for Claude Code

Argument Parsing

The script expects arguments in this order:

python script.py <video_url> [--output DIR] [--language LANG]

Parse the user's /fetch-youtube-transcript command to extract these values:

• Strip the /fetch-youtube-transcript prefix
• Extract the first argument as video URL
• Look for --output flag and next argument
• Look for --language flag and next argument

Error Detection

Monitor the exit code and stderr:

• Exit code 0 = Success
• Exit code 1 = Error (check stderr for details)

Common error patterns in stderr:

• "Invalid YouTube URL" → URL validation failed
• "No transcript found" → Transcripts disabled
• "Video unavailable" → Private/deleted video
• "Network" → Connection issues

Path Handling

The script is bundled with this plugin at scripts/fetch-youtube-transcript.py (relative to the plugin directory).

Claude Code will resolve this path automatically when executing from the plugin context.

Output directory handling:

• Relative paths are relative to current working directory
• Absolute paths work as expected
• Default .work/transcripts/ is relative to current directory

User Communication

Be conversational: Don't just dump the raw script output. Parse it and present it naturally:

Instead of:

✅ Transcript downloaded successfully!
Video: 4_2j5wgt_ds
File: .work/transcripts/4_2j5wgt_ds.txt

Say:

I've downloaded the transcript for video 4_2j5wgt_ds.
The file is saved at .work/transcripts/4_2j5wgt_ds.txt with 851 transcript entries.

Provide context: If the user might want to do something with the transcript, suggest next steps:

Transcript downloaded successfully! You can now:
- Read the file to review the content
- Search for specific topics or keywords
- Use it as reference material
- Process it further with other tools

Handle errors gracefully: Don't just report the error, explain what it means and what to do:

Instead of:

❌ Error: No transcript found

Say:

This video doesn't have a transcript available. This usually means the creator
disabled automatic captions. Unfortunately, there's no transcript to download.

Working Directory

The script path is relative to the plugin directory and Claude Code handles path resolution automatically.

Output directory considerations:

• Relative paths are relative to current working directory
• Default .work/transcripts/ will be created relative to where the command is run
• Use absolute paths if you need transcripts in a specific location

Testing Verification

Before reporting success, verify:

1. Exit code is 0
2. Output file exists at expected path
3. Output file has content (size > 0)

This prevents false positives from script failures.

Technical Details

Dependencies

The skill uses youtube-transcript-api via uvx:

• No installation required
• Isolated execution environment
• Automatic dependency management

Script Location

The Python script is bundled with the plugin at scripts/fetch-youtube-transcript.py (relative to plugin directory).

Supported URL Formats

The script handles these YouTube URL formats:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/watch?v=VIDEO_ID&t=123s
• https://m.youtube.com/watch?v=VIDEO_ID
• VIDEO_ID (11 characters)

Language Codes

Common language codes for --language:

• en - English
• es - Spanish
• fr - French
• de - German
• ja - Japanese
• ko - Korean
• zh - Chinese
• pt - Portuguese
• ru - Russian
• ar - Arabic

Full list: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

Output File Naming

Files are named using the video ID:

• Video ID extracted from URL
• Extension: .txt
• Example: dQw4w9WgXcQ.txt

This ensures:

• Unique filenames per video
• Easy to identify source video
• No special character issues

Limitations

• Requires internet connection to YouTube
• Only works with public videos or unlisted videos with link
• Requires video to have transcripts enabled (manual or automatic)
• Cannot bypass region restrictions
• Subject to YouTube API rate limits
• Language availability depends on video creator settings

Future Enhancements

Potential improvements for future versions:

• Batch download multiple videos from a playlist
• Merge transcripts from multiple videos
• Format conversion (SRT, VTT, JSON)
• Translation of transcripts
• Timestamp filtering (download specific time ranges)
• Integration with video analysis tools