---
name: valtterimelkko/youtube-caption
source: https://app.decimal.ai/s/valtterimelkko-youtube-caption@1/SKILL.md
source_sha256: eab0c9a55a5b
---

# YouTube Caption Fetcher

Download captions/transcripts and metadata from any YouTube video using the `youtube-transcript-api` library with optional residential proxy support.

## Prerequisites

**Required Python package:**
```bash
pip install youtube-transcript-api
```

**Residential Proxy Credentials** (auto-loaded from environment or a shell startup file):
```bash
# Reddit proxy for YouTube caption and metadata fetching
export YOUTUBE_PROXY_URL="http://username:password@host:port"
# legacy fallback also supported:
export REDDIT_PROXY_URL="http://username:password@host:port"
```

The skill automatically fetches these credentials from the environment or a shell startup file when caption or metadata fetching requires proxy support.

## Quick Start

### Fetch captions and metadata:
```bash
python3 ./scripts/fetch_caption.py --url "https://www.youtube.com/watch?v=VIDEO_ID"
```

### Fetch only metadata (uses proxy):
```bash
python3 ./scripts/fetch_caption.py --url "https://youtu.be/VIDEO_ID" --metadata-only
```

### Fetch captions only (uses proxy):
```bash
python3 ./scripts/fetch_caption.py --url "https://www.youtube.com/watch?v=VIDEO_ID" --captions-only
```

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--url` or `-u` | **Yes** | - | YouTube video URL (supports various formats) |
| `--metadata-only` | No | false | Fetch only video metadata (uses proxy) |
| `--captions-only` | No | false | Fetch only captions (uses proxy) |
| `--language` or `-l` | No | en | Language code for captions (e.g., en, es, fr) |
| `--output` or `-o` | No | - | Save output to JSON file |

## Output Format

Returns JSON with both captions and metadata:

```json
{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "metadata": {
    "title": "Video Title",
    "description": "Full video description...",
    "channel": "Channel Name",
    "channel_id": "UC...",
    "published_at": "2025-01-15T10:00:00Z",
    "duration": "10:30",
    "duration_seconds": 630,
    "view_count": 1000000,
    "thumbnail": "https://i.ytimg.com/vi/...",
    "links_in_description": [
      "https://example.com/link1",
      "https://example.com/link2"
    ]
  },
  "captions": {
    "text": "Full transcript text...",
    "language": "en",
    "is_generated": true,
    "word_count": 1500,
    "duration_seconds": 630
  }
}
```

## How It Works

1. **Caption fetching**: Uses `youtube-transcript-api` with residential proxy (to avoid IP blocks)
2. **Metadata fetching**: Uses `urllib` with residential proxy (to bypass YouTube bot detection)
3. **Proxy credentials**: Automatically loaded from the environment or a shell startup file (`YOUTUBE_PROXY_URL`, or legacy `REDDIT_PROXY_URL`)

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `TranscriptsDisabled` | Video has captions disabled | Try another video |
| `NoTranscriptFound` | No captions in requested language | Try `--language` with different code |
| `VideoUnavailable` | Video is private/deleted | Check video URL |
| `ProxyError` | Proxy connection failed | Check proxy credentials in your environment or shell startup file |

## Usage Examples

### Get full video data:
```bash
python3 ./scripts/fetch_caption.py --url "https://www.youtube.com/watch?v=VIDEO_ID" -o output.json
```

### Get captions in Spanish:
```bash
python3 ./scripts/fetch_caption.py --url "https://youtu.be/VIDEO_ID" --language es
```

### Extract just the transcript text:
```bash
python3 ./scripts/fetch_caption.py --url "URL" --captions-only | jq -r '.captions.text'
```

### Get metadata with links from description:
```bash
python3 ./scripts/fetch_caption.py --url "URL" --metadata-only | jq '.metadata.links_in_description'
```

## Notes

- **Proxy is used for both caption AND metadata fetching** to bypass YouTube bot detection
- Supports auto-generated and manual captions
- Falls back gracefully if captions are unavailable
- Metadata includes `links_in_description` array extracted from the video description