YouTube Transcripts Skill

Extract transcripts from YouTube videos with three-tier fallback:

1. Direct - youtube-transcript-api (fastest)
2. Proxy - IPRoyal residential proxy rotation (handles rate limits)
3. Whisper - yt-dlp audio download → OpenAI Whisper (last resort)

Quick Start

# Get transcript (auto-fallback through all tiers)
python .agents/skills/youtube-transcripts/youtube_transcript.py get -i dQw4w9WgXcQ

# Skip proxy tier
python .agents/skills/youtube-transcripts/youtube_transcript.py get -i VIDEO_ID --no-proxy

# Skip whisper tier
python .agents/skills/youtube-transcripts/youtube_transcript.py get -i VIDEO_ID --no-whisper

# List available transcript languages
python .agents/skills/youtube-transcripts/youtube_transcript.py list-languages -i VIDEO_ID

# Check proxy configuration
python .agents/skills/youtube-transcripts/youtube_transcript.py check-proxy

Commands

Get Transcript

python .agents/skills/youtube-transcripts/youtube_transcript.py get \
  --url "https://youtube.com/watch?v=dQw4w9WgXcQ" \
  --lang en

Options:

Option	Short	Description
--url	-u	YouTube video URL
--video-id	-i	Video ID directly
--lang	-l	Language code (default: en)
--no-proxy		Skip proxy tier
--no-whisper		Skip Whisper fallback tier
--retries	-r	Max retries per tier (default: 3)

Output: JSON with transcript segments (text, start time, duration)

List Available Languages

python .agents/skills/youtube-transcripts/youtube_transcript.py list-languages -i VIDEO_ID

Output: JSON with available transcript languages

Check Proxy

python .agents/skills/youtube-transcripts/youtube_transcript.py check-proxy
python .agents/skills/youtube-transcripts/youtube_transcript.py check-proxy --test-rotation

Tests IPRoyal proxy connectivity and IP rotation.

Output Format

{
  "meta": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "took_ms": 3029,
    "method": "direct"
  },
  "transcript": [
    {"text": "Hello world", "start": 0.0, "duration": 2.5},
    {"text": "This is a test", "start": 2.5, "duration": 3.0}
  ],
  "full_text": "Hello world This is a test...",
  "errors": []
}

Method values: direct, proxy, whisper, or null (if all failed)

Three-Tier Fallback

Tier 1: Direct

• Uses youtube-transcript-api without proxy
• Fastest, no additional cost
• May fail with rate limits on repeated requests

Tier 2: IPRoyal Proxy

• Uses IPRoyal residential proxy (auto-rotates IPs)
• Handles rate limiting (429) and blocking (403)
• Requires proxy credentials

Environment variables:

Variable	Description
IPROYAL_HOST	Proxy host (e.g., geo.iproyal.com)
IPROYAL_PORT	Proxy port (e.g., 12321)
IPROYAL_USER	Proxy username
IPROYAL_PASSWORD	Proxy password

Tier 3: Whisper Fallback

• Downloads audio with yt-dlp
• Transcribes with OpenAI Whisper API
• Works for videos with disabled captions
• Costs ~$0.006/minute of audio

Environment variables:

Variable	Description
OPENAI_API_KEY	OpenAI API key for Whisper

Dependencies

pip install youtube-transcript-api requests yt-dlp openai

• youtube-transcript-api - Tier 1 & 2
• requests - Proxy support
• yt-dlp - Tier 3 audio download
• openai - Tier 3 transcription

Integration with Memory

# Get transcript
python .agents/skills/youtube-transcripts/youtube_transcript.py get -i VIDEO_ID > transcript.json

# Ingest into memory
memory-agent workspace-ingest --source transcript.json --scope youtube

Limitations

• Tier 1-2 require captions (auto-generated or manual)
• Tier 3 (Whisper) works for any video but costs money
• Private/unlisted videos may not be accessible
• Very long videos may exceed Whisper file size limits (25MB)