YouTube Video Downloader (yt-dlp)

Download videos from YouTube and 1000+ other sites using yt-dlp.

Description

A powerful video downloader skill based on yt-dlp that supports YouTube, Bilibili, Twitter/X, TikTok, and many other platforms. Features include format selection, audio extraction, subtitle download, playlist support, and metadata preservation.

When to Use

Use this skill when users:

• 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

Download single video (best quality):

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

Download video in specific quality:

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

Extract audio only (MP3):

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

Download with subtitles:

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

Download playlist:

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

Download N videos from playlist:

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

Specify output directory:

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

Arguments

Argument	Description	Default
url	Video/Playlist URL (required)	-
-o, --output	Output directory	Current directory
-f, --format	Video quality: best, 1080, 720, 480, 360	best
--audio-only	Extract audio only (MP3)	False
--subtitles	Download subtitles	False
--sub-lang	Subtitle language(s)	en,zh-Hans
--playlist	Enable playlist download	False
-n, --count	Number of videos from playlist	All
--metadata	Save video metadata JSON	True
--thumbnail	Download thumbnail	False
--cookies	Path to cookies file (for age-restricted content)	None

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

When user requests video download:

1. Read skill documentation:

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

2. Install dependencies (if needed):

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

3. Execute download:

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

4. Present files to user:

   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 supports 1000+ sites. Run yt-dlp --list-extractors for full list.

Common Issues

Q: Age-restricted videos? A: Use --cookies with exported browser cookies: --cookies cookies.txt

Q: Format not available? A: Some videos may not have all quality options. Script will auto-select best available.

Q: Download speed slow? A: This is usually server-side throttling. Consider using a VPN or waiting.

Q: Need to login for private videos? A: Export cookies from your browser after logging in, then use --cookies.

Q: Audio extraction fails? A: Install ffmpeg: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)

Example Conversations

User: "帮我下载这个 YouTube 视频: https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Claude:

# 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([...])

---

User: "下载这个 YouTube 视频的音频，我只要 MP3"

Claude:

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

---

User: "Download this playlist, but only the first 5 videos"

Claude:

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

This skill wraps yt-dlp with sensible defaults:

• 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

This tool is for personal use only. Please respect:

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

Only download content you have the right to access. Do not redistribute copyrighted material.

Version History

v1.0 (Current)

• 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