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.