YouTube Video Downloader (yt-dlp)

Description

When to Use

• Provide YouTube URLs and want to download videos
• Mention "download video", "下载视频", "save video from YouTube"
• Want to extract audio from videos (MP3)
• Need to download playlists or channels
• Want subtitles/captions from videos
• Request video download from supported sites (Bilibili, Twitter, TikTok, etc.)

Features

• Multi-Platform Support: YouTube, Bilibili, Twitter/X, TikTok, Vimeo, and 1000+ sites
• Format Selection: Choose video quality (1080p, 720p, 4K) or audio-only
• Audio Extraction: Extract audio as MP3, M4A, or other formats
• Subtitle Download: Auto-download subtitles in multiple languages
• Playlist Support: Download entire playlists or channels
• Metadata Preservation: Save video info, thumbnails, and descriptions
• Resume Support: Continue interrupted downloads
• Progress Display: Real-time download progress

Usage

Basic Syntax

python scripts/download_video.py "VIDEO_URL" [OPTIONS]

Common Scenarios

python scripts/download_video.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" -f 1080

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --audio-only

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --subtitles

python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist

python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist -n 5

python scripts/download_video.py "URL" -o /path/to/output

Arguments

url

-o, --output

-f, --format

best

1080

720

480

360

best

--audio-only

--subtitles

--sub-lang

en,zh-Hans

--playlist

-n, --count

--metadata

--thumbnail

--cookies

Dependencies

# Install yt-dlp
pip install yt-dlp --break-system-packages

# For audio extraction (optional)
# macOS
brew install ffmpeg

# Ubuntu/Debian
apt-get install ffmpeg

Output Structure

Single Video

OutputDir/
├── Video Title [VIDEO_ID].mp4     # Video file
├── Video Title [VIDEO_ID].json    # Metadata (if --metadata)
├── Video Title [VIDEO_ID].jpg     # Thumbnail (if --thumbnail)
└── Video Title [VIDEO_ID].en.vtt  # Subtitles (if --subtitles)

Playlist

OutputDir/
└── PlaylistName/
    ├── playlist_info.json
    ├── 001 - Video Title.mp4
    ├── 001 - Video Title.json
    ├── 002 - Another Video.mp4
    └── ...

Metadata Example

{
  "title": "Video Title",
  "uploader": "Channel Name",
  "upload_date": "2024-01-15",
  "duration": 300,
  "view_count": 1000000,
  "description": "Video description...",
  "tags": ["tag1", "tag2"],
  "video_file": "Video Title [VIDEO_ID].mp4"
}

Claude Integration

1. Read skill documentation:
   python

   view("/mnt/skills/user/youtube-downloader/SKILL.md")

2. Install dependencies (if needed):
   bash

   pip install yt-dlp --break-system-packages

3. Execute download:
   bash

   python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
     "USER_URL" -o /mnt/user-data/outputs

4. Present files to user:
   python

   present_files(["/mnt/user-data/outputs/..."])

Supported Platforms

Major Platforms

• YouTube: Videos, Shorts, Playlists, Channels, Live streams
• Bilibili: Videos, Episodes (may need cookies)
• Twitter/X: Video tweets
• TikTok: Videos (may need cookies)
• Vimeo: Videos
• Twitch: VODs, Clips

Full List

yt-dlp --list-extractors

Common Issues

--cookies

--cookies cookies.txt

--cookies

brew install ffmpeg

apt install ffmpeg

Example Conversations

# Install yt-dlp
pip install yt-dlp --break-system-packages

# Download video
python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -o /mnt/user-data/outputs

# Present files
present_files([...])

python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "VIDEO_URL" \
  --audio-only \
  -o /mnt/user-data/outputs

python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "PLAYLIST_URL" \
  --playlist -n 5 \
  -o /mnt/user-data/outputs

How It Works

Workflow

1. URL Parsing: Detect platform and content type (video/playlist)
2. Format Selection: Determine best available format based on user preference
3. Download: Stream video/audio with progress display
4. Post-Processing: Extract audio (if requested), embed subtitles
5. Metadata: Save video information to JSON

Under the Hood

• Automatic format selection for best quality
• Proper filename sanitization
• Retry logic for failed downloads
• Progress display with ETA

Limitations

• Some sites may require authentication (cookies)
• Age-restricted content needs browser cookies
• Download speed depends on source server
• Some DRM-protected content cannot be downloaded
• Live streams can only be downloaded after they end (VOD)

Legal Notice

• YouTube Terms of Service
• Copyright laws in your jurisdiction
• Content creators' rights

Version History

• Initial release with yt-dlp wrapper
• Support for video, audio, subtitles, playlists
• Metadata and thumbnail preservation
• Multi-platform support

References

• yt-dlp GitHub
• yt-dlp Documentation
• Supported Sites