yt-dlp

name	yt-dlp
description	Comprehensive skill for yt-dlp - feature-rich command-line audio/video downloader supporting thousands of sites Use when this capability is needed.
metadata	{"author":"aeonbridge"}

yt-dlp Skill

Expert assistance for using yt-dlp, a feature-rich command-line audio/video downloader with support for thousands of websites. Fork of youtube-dl with enhanced features and active maintenance.

When to Use This Skill

This skill should be used when:

• Downloading videos or audio from YouTube, Vimeo, or thousands of other sites
• Extracting audio from videos in various formats (MP3, M4A, OPUS, etc.)
• Downloading entire playlists or channels
• Selecting specific video quality or format combinations
• Embedding metadata, subtitles, or thumbnails
• Automating media downloads with scripts
• Recording live streams
• Converting video formats with FFmpeg integration
• Extracting video information without downloading
• Troubleshooting download issues or understanding yt-dlp options
• Setting up advanced configurations for batch processing

Overview

yt-dlp is a powerful command-line tool that:

• Supports thousands of sites: YouTube, Vimeo, Twitter, Facebook, Instagram, TikTok, and many more
• Actively maintained: Regular updates with bug fixes and new features
• Feature-rich: Extensive options for format selection, metadata handling, and post-processing
• Fast and efficient: Multi-threaded downloads with resume capability
• Extensible: Plugin system for custom extractors and post-processors

Key Improvements Over youtube-dl

• Better performance and stability
• More format options and quality selection
• Enhanced metadata handling
• Improved playlist and channel downloads
• Better error handling and retry logic
• Active development and frequent updates
• SponsorBlock integration for YouTube

Installation

Recommended Methods

Windows

# Download standalone executable
# Visit: https://github.com/yt-dlp/yt-dlp/releases/latest
# Download: yt-dlp.exe (64-bit)

# Or use winget
winget install yt-dlp

# Or use scoop
scoop install yt-dlp

macOS

# Using Homebrew
brew install yt-dlp

# Or download directly
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos -o /usr/local/bin/yt-dlp
chmod a+rx /usr/local/bin/yt-dlp

Linux

# Using pip (recommended)
python3 -m pip install -U yt-dlp

# Or download binary
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

# Debian/Ubuntu (via apt)
sudo add-apt-repository ppa:tomtomtom/yt-dlp
sudo apt update
sudo apt install yt-dlp

Using pip (cross-platform)

# Install or upgrade
python3 -m pip install -U yt-dlp

# Or with pipx (isolated environment)
pipx install yt-dlp

Essential Dependencies

FFmpeg (Strongly Recommended)

Required for merging video+audio formats and post-processing:

# Windows (scoop)
scoop install ffmpeg

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

Optional Dependencies

# For better performance and features
pip install brotli certifi mutagen pycryptodomex websockets

# For browser cookie support
pip install secretstorage  # Linux
pip install pywin32        # Windows

# For HTTP/3 and impersonation
pip install curl-cffi

Quick Start

Basic Downloads

# Download a video
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Download from multiple URLs
yt-dlp URL1 URL2 URL3

# Download from a file containing URLs
yt-dlp -a urls.txt

# Download entire playlist
yt-dlp "https://www.youtube.com/playlist?list=PLAYLIST_ID"

# Download channel
yt-dlp "https://www.youtube.com/@channelname"

Audio-Only Downloads

# Extract audio as MP3
yt-dlp -x --audio-format mp3 URL

# Extract audio as best quality
yt-dlp -x --audio-quality 0 URL

# Extract audio with metadata
yt-dlp -x --audio-format mp3 --embed-metadata --embed-thumbnail URL

# Download music with best quality
yt-dlp -f 'bestaudio[ext=m4a]' --embed-thumbnail --add-metadata URL

Format Selection

Understanding Formats

# List all available formats
yt-dlp -F URL

# Download best quality (video+audio)
yt-dlp -f "best" URL

# Download best video and best audio separately, then merge
yt-dlp -f "bestvideo+bestaudio" URL

# Download specific format by ID
yt-dlp -f 22 URL

# Download best video up to 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" URL

# Download best MP4 format
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" URL

Advanced Format Selection

# Best quality with size limit (under 100MB)
yt-dlp -f "best[filesize<100M]" URL

# Specific resolution
yt-dlp -f "bestvideo[height=720]+bestaudio" URL

# Prefer 60fps
yt-dlp -f "bestvideo[fps>30]+bestaudio" URL

# Download only video (no audio)
yt-dlp -f "bestvideo" URL

# Download only audio
yt-dlp -f "bestaudio" URL

# Prefer free codecs (VP9/Opus over H.264/AAC)
yt-dlp -f "bestvideo[vcodec^=vp]+bestaudio[acodec^=opus]" URL

Common Use Cases

1. Download Entire Channel or Playlist

# Download all videos from a channel
yt-dlp -f "bestvideo[height<=1080]+bestaudio" \
       --output "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" \
       "https://www.youtube.com/@channelname"

# Download playlist with numbered files
yt-dlp --output "%(playlist_index)s-%(title)s.%(ext)s" PLAYLIST_URL

# Download only videos uploaded in last 7 days
yt-dlp --dateafter now-7days CHANNEL_URL

# Download specific date range
yt-dlp --dateafter 20230101 --datebefore 20231231 CHANNEL_URL

2. Download with Subtitles

# Download video with all subtitles
yt-dlp --write-subs --write-auto-subs URL

# Download with specific subtitle language
yt-dlp --write-subs --sub-lang en URL

# Embed subtitles in video file
yt-dlp --write-subs --embed-subs --sub-lang en URL

# Download all available subtitle languages
yt-dlp --write-subs --all-subs URL

# Convert subtitles to SRT format
yt-dlp --write-subs --convert-subs srt URL

3. Download with Metadata and Thumbnails

# Embed metadata and thumbnail
yt-dlp --embed-metadata --embed-thumbnail URL

# Download thumbnail as separate file
yt-dlp --write-thumbnail URL

# Convert thumbnail to JPG
yt-dlp --write-thumbnail --convert-thumbnails jpg URL

# Full metadata preservation
yt-dlp --embed-metadata --embed-thumbnail --embed-subs \
       --embed-chapters --write-description --write-info-json URL

4. Live Stream Recording

# Record live stream from the beginning
yt-dlp --live-from-start URL

# Record live stream from current time
yt-dlp URL

# Wait for stream to start
yt-dlp --wait-for-video 60 URL

# Monitor and download when live
yt-dlp --wait-for-video 3600 --live-from-start URL

5. Download Specific Playlist Items

# Download first 10 videos
yt-dlp --playlist-end 10 PLAYLIST_URL

# Download videos 5-15
yt-dlp --playlist-start 5 --playlist-end 15 PLAYLIST_URL

# Download specific video from playlist
yt-dlp --playlist-items 1,5,8,12 PLAYLIST_URL

# Download every 5th video
yt-dlp --playlist-items "::5" PLAYLIST_URL

# Skip first 20 videos
yt-dlp --playlist-start 21 PLAYLIST_URL

6. Archive and Download History

# Skip already downloaded videos
yt-dlp --download-archive archive.txt URL

# Continue interrupted downloads
yt-dlp --continue URL

# Don't overwrite files
yt-dlp --no-overwrites URL

# Force resume from beginning if interrupted
yt-dlp --no-continue URL

Advanced Features

Output Templates

# Custom filename pattern
yt-dlp -o "%(title)s.%(ext)s" URL

# Organize by uploader and date
yt-dlp -o "%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" URL

# Include video ID and resolution
yt-dlp -o "%(id)s - %(title)s [%(resolution)s].%(ext)s" URL

# Organized folder structure
yt-dlp -o "Downloads/%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" URL

# Available template fields:
# %(title)s - Video title
# %(id)s - Video ID
# %(ext)s - File extension
# %(uploader)s - Channel/uploader name
# %(upload_date)s - Upload date (YYYYMMDD)
# %(duration)s - Video duration in seconds
# %(resolution)s - Video resolution (e.g., 1920x1080)
# %(playlist)s - Playlist name
# %(playlist_index)s - Position in playlist
# %(channel)s - Channel name
# %(channel_id)s - Channel ID

Post-Processing

# Convert to MP4
yt-dlp --merge-output-format mp4 URL

# Re-encode video to H.264
yt-dlp --recode-video mp4 URL

# Extract audio and convert to MP3 with 320kbps
yt-dlp -x --audio-format mp3 --audio-quality 0 URL

# Remux to MKV without re-encoding
yt-dlp --remux-video mkv URL

# Embed thumbnail as cover art (audio files)
yt-dlp -x --audio-format mp3 --embed-thumbnail URL

# Add metadata and chapters
yt-dlp --embed-metadata --embed-chapters URL

# Split video by chapters
yt-dlp --split-chapters URL

# Execute command after download
yt-dlp --exec "echo Downloaded: {}" URL

SponsorBlock Integration (YouTube)

# Skip sponsored segments
yt-dlp --sponsorblock-mark all URL

# Remove sponsored segments
yt-dlp --sponsorblock-remove all URL

# Mark and remove specific categories
yt-dlp --sponsorblock-mark sponsor,intro --sponsorblock-remove outro URL

# Available categories: sponsor, intro, outro, selfpromo, preview,
#                      filler, interaction, music_offtopic

Browser Cookie Support

# Use cookies from browser
yt-dlp --cookies-from-browser firefox URL

# Use cookies from Chrome
yt-dlp --cookies-from-browser chrome URL

# Use cookies from file
yt-dlp --cookies cookies.txt URL

# Export cookies (for authentication)
# First: Use browser extension to export cookies.txt
yt-dlp --cookies cookies.txt URL

Rate Limiting and Network Options

# Limit download speed (1MB/s)
yt-dlp --limit-rate 1M URL

# Use proxy
yt-dlp --proxy http://proxy.example.com:8080 URL

# Set custom user agent
yt-dlp --user-agent "Mozilla/5.0..." URL

# Add referer header
yt-dlp --referer "https://example.com" URL

# Set timeout
yt-dlp --socket-timeout 30 URL

# Retry on failure
yt-dlp --retries 10 URL

# Sleep between downloads
yt-dlp --sleep-interval 5 URL

Geo-Restriction Bypass

# Use VPN or proxy
yt-dlp --proxy socks5://127.0.0.1:1080 URL

# Use Tor
yt-dlp --proxy socks5://127.0.0.1:9050 URL

# Fake IP for geo-restricted content
yt-dlp --geo-bypass URL

# Specify geo-bypass country
yt-dlp --geo-bypass-country US URL

Configuration File

Create ~/.config/yt-dlp/config (Linux/macOS) or %APPDATA%/yt-dlp/config.txt (Windows):

# Default format selection
-f bestvideo[height<=1080]+bestaudio/best[height<=1080]

# Output template
-o ~/Downloads/%(uploader)s/%(title)s.%(ext)s

# Always embed metadata
--embed-metadata
--embed-thumbnail
--embed-subs

# Download subtitles
--write-subs
--sub-lang en

# Archive to avoid re-downloading
--download-archive ~/.config/yt-dlp/archive.txt

# No overwrite
--no-overwrites

# Continue incomplete downloads
--continue

# Prefer free formats
--prefer-free-formats

# Add metadata
--add-metadata

# SponsorBlock
--sponsorblock-mark all

# Rate limit (optional)
# --limit-rate 5M

# Retries
--retries 10

# Sleep between downloads
--sleep-interval 3

Information Extraction (No Download)

# Get video info as JSON
yt-dlp --dump-json URL

# Get only the title
yt-dlp --get-title URL

# Get direct video URL
yt-dlp --get-url URL

# Get filename without downloading
yt-dlp --get-filename URL

# Get thumbnail URL
yt-dlp --get-thumbnail URL

# Get video duration
yt-dlp --get-duration URL

# Get all available info
yt-dlp --dump-single-json URL

# Simulate download (show what would be done)
yt-dlp --simulate URL

# List formats without downloading
yt-dlp -F URL

Batch Processing and Automation

Bash Script Example

#!/bin/bash
# download_channel.sh

CHANNEL_URL="$1"
OUTPUT_DIR="$2"

yt-dlp \
    --download-archive archive.txt \
    --format "bestvideo[height<=1080]+bestaudio" \
    --output "${OUTPUT_DIR}/%(upload_date)s - %(title)s.%(ext)s" \
    --write-subs \
    --embed-subs \
    --embed-metadata \
    --embed-thumbnail \
    --no-overwrites \
    --continue \
    --retries 10 \
    --sleep-interval 5 \
    "$CHANNEL_URL"

Python Integration

import yt_dlp

# Basic download
ydl_opts = {
    'format': 'bestvideo+bestaudio/best',
    'outtmpl': '%(title)s.%(ext)s',
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])

# Extract info only
with yt_dlp.YoutubeDL({'quiet': True}) as ydl:
    info = ydl.extract_info('URL', download=False)
    title = info.get('title', None)
    duration = info.get('duration', None)
    print(f"Title: {title}, Duration: {duration}s")

# Audio extraction
ydl_opts = {
    'format': 'bestaudio/best',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'mp3',
        'preferredquality': '192',
    }],
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['URL'])

Common Options Reference

General Options

--help, -h              Show help message
--version               Print program version
--update                Update to latest version
--ignore-errors         Continue on download errors
--no-abort-on-error     Continue even if errors occur
--quiet, -q             Suppress output
--verbose, -v           Print debug information
--dump-json             Output info as JSON
--simulate, -s          Don't download, simulate

Download Options

-f, --format FORMAT     Format selection
-o, --output TEMPLATE   Output filename template
--playlist-items ITEMS  Playlist items to download
--min-filesize SIZE     Minimum file size
--max-filesize SIZE     Maximum file size
--date DATE             Download only on this date
--datebefore DATE       Download before this date
--dateafter DATE        Download after this date

Post-Processing

-x, --extract-audio           Extract audio only
--audio-format FORMAT         Audio format (mp3, m4a, opus, etc.)
--audio-quality QUALITY       Audio quality (0-9, 0=best)
--recode-video FORMAT         Re-encode video
--remux-video FORMAT          Remux to different container
--embed-subs                  Embed subtitles in video
--embed-thumbnail             Embed thumbnail
--embed-metadata              Add metadata to file
--embed-chapters              Add chapter markers
--split-chapters              Split by chapters
--sponsorblock-mark CATS      Mark SponsorBlock categories
--sponsorblock-remove CATS    Remove SponsorBlock segments

Subtitle Options

--write-subs                Write subtitles
--write-auto-subs           Write auto-generated subtitles
--all-subs                  Download all subtitles
--sub-lang LANGS            Subtitle languages (comma-separated)
--sub-format FORMAT         Subtitle format (srt, vtt, etc.)
--convert-subs FORMAT       Convert subtitles to format

Best Practices

1. Use Download Archive

Always use --download-archive archive.txt to avoid re-downloading videos:

yt-dlp --download-archive archive.txt CHANNEL_URL

2. Set Reasonable Rate Limits

Be respectful of bandwidth:

yt-dlp --limit-rate 5M --sleep-interval 3 URL

3. Use Configuration Files

Store commonly used options in config file instead of typing them each time.

4. Handle Errors Gracefully

Use retry options and error handling:

yt-dlp --retries 10 --ignore-errors --no-abort-on-error URL

5. Organize Downloads

Use meaningful output templates:

yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" URL

6. Keep yt-dlp Updated

Update regularly for bug fixes and new features:

yt-dlp -U
# or
pip install -U yt-dlp

Troubleshooting

Common Issues

"Unable to extract video data"

# Update yt-dlp
yt-dlp -U

# Clear cache
yt-dlp --rm-cache-dir

# Try different format
yt-dlp -f 'best' URL

"HTTP Error 403: Forbidden"

# Use cookies from browser
yt-dlp --cookies-from-browser firefox URL

# Or use cookies file
yt-dlp --cookies cookies.txt URL

"Requested format not available"

# List available formats first
yt-dlp -F URL

# Then select compatible format
yt-dlp -f "bestvideo+bestaudio" URL

Geo-restricted Content

# Use proxy or VPN
yt-dlp --proxy socks5://127.0.0.1:1080 URL

# Or bypass geo-restriction
yt-dlp --geo-bypass --geo-bypass-country US URL

Slow Downloads

# Use multiple connections
yt-dlp --concurrent-fragments 4 URL

# Check your rate limit setting
# Remove or increase --limit-rate if set

Getting Help

# Show all options
yt-dlp --help

# Search for specific option
yt-dlp --help | grep subtitle

# Check version
yt-dlp --version

# Verbose output for debugging
yt-dlp --verbose URL

Update and Maintenance

Updating yt-dlp

# Self-update (if installed as binary)
yt-dlp -U

# Update via pip
pip install -U yt-dlp

# Update to specific channel
yt-dlp --update-to nightly  # or stable, or master

# Check current version
yt-dlp --version

Release Channels

• stable: Well-tested releases (default)
• nightly: Daily builds, recommended for regular users
• master: Latest development after each commit

Supported Sites

yt-dlp supports thousands of sites, including:

• Video: YouTube, Vimeo, Dailymotion, Twitch, TikTok
• Social: Facebook, Instagram, Twitter/X, Reddit
• Streaming: Twitch, Crunchyroll, Netflix (with cookies), Disney+
• Education: Coursera, Udemy, Khan Academy, edX
• News: BBC, CNN, NBC, ABC
• And many more: Full list at https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

Legal and Ethical Considerations

Important Notes:

• Respect copyright and terms of service of websites
• Only download content you have the right to download
• Some content may be protected by DRM or geo-restrictions
• Always check local laws regarding downloading copyrighted content
• Use yt-dlp responsibly and ethically

Resources

• GitHub: https://github.com/yt-dlp/yt-dlp
• Documentation: https://github.com/yt-dlp/yt-dlp/blob/master/README.md
• Supported Sites: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
• Issue Tracker: https://github.com/yt-dlp/yt-dlp/issues
• Wiki: https://github.com/yt-dlp/yt-dlp/wiki

License

yt-dlp is licensed under the Unlicense (public domain). Some bundled components may use different licenses.

---

Note: This skill provides comprehensive guidance for using yt-dlp. Always ensure your use complies with local laws and website terms of service.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.