fetch-youtube-transcript

What this skill does

# 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

```bash
/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:

```python
# 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:

```bash
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:

```python
# 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:

```bash
/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:

```bash
/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:

```bash
/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:

```bash
/fetch-youtube-transcript "dQw4w9WgXcQ"
```

Result:
- Same as full URL
- Simpler syntax for known video IDs

## Error Handling

### Validation Errors

**Missing URL:**
```bash
/fetch-youtube-transcript
```
Response: "Error: Video URL or ID required. Usage: /fetch-youtube-transcript <video-url-or-id> [--output DIR]"

**Invalid URL format:**
```bash
/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:
```bash
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 d