yt-dlp Documentation Guide

yt-dlp is a feature-rich command-line audio/video downloader with support for thousands of sites. It's a maintained fork of youtube-dl with many additional features and fixes.

Documentation Structure

This skill includes the complete README.md and the official wiki. When working with yt-dlp, reference the appropriate documentation based on the task:

For Installation and Setup

• README.md - Section: # INSTALLATION - Installation methods, dependencies, and updates
• wiki/Installation.md - Detailed installation guide for various platforms
• wiki/FAQ.md - Common installation issues and solutions

For Basic Downloads

• README.md - Section: # USAGE AND OPTIONS - Complete command-line reference
• README.md - Section: ## Download Options: - File selection, rate limiting, retries
• README.md - Section: ## Video Selection: - Playlist handling, filtering, date ranges

For Format Selection (Quality, Audio/Video)

• README.md - Section: ## Video Format Options: - Format selection syntax and filtering
• README.md - Section: # FORMAT SELECTION - Detailed format selection guide
• wiki/FAQ.md - Common format selection questions

For Audio Extraction

• README.md - Section: ## Post-Processing Options: - Audio extraction, conversion, embedding
• Look for examples with -x or --extract-audio flags
• Format selection for audio-only downloads

For Subtitles and Captions

• README.md - Section: ## Subtitle Options: - Subtitle downloading, conversion, embedding
• Examples with --write-subs, --write-auto-subs, --sub-lang

For Output Customization

• README.md - Section: # OUTPUT TEMPLATE - Filename templates and field formatting
• README.md - Section: ## Filesystem Options: - Path formatting, file naming
• Use this for custom file naming patterns and organization

For Metadata and Embedding

• README.md - Section: # MODIFYING METADATA - Adding/modifying metadata during download
• README.md - Section: ## Post-Processing Options: - Embedding thumbnails, metadata, chapters

For Authentication and Cookies

• README.md - Section: ## Authentication Options: - Username/password, cookies, netrc
• README.md - Section: # CONFIGURATION - Subsection: ### Authentication with netrc
• Use for sites requiring login

For Troubleshooting

• wiki/FAQ.md - Frequently asked questions and common issues
• README.md - Section: ## Workarounds: - Handling rate limits, geo-restrictions, errors
• README.md - Section: ## Extractor Options: - Site-specific options
• wiki/Extractors.md - List of supported sites and extractor-specific details

For YouTube-Specific Issues

• wiki/PO-Token-Guide.md - YouTube PO Token authentication (for bot detection issues)
• wiki/EJS.md - YouTube cipher decryption setup
• README.md - Section: ## SponsorBlock Options: - SponsorBlock integration for YouTube

For Playlists and Channels

• README.md - Section: ## Video Selection: - Playlist filtering, item selection
• Use --playlist-start, --playlist-end, --playlist-items options
• Archive functionality to track downloaded items

For Configuration Files

• README.md - Section: # CONFIGURATION - Configuration file locations and syntax
• Configuration file examples and environment variables

For Advanced Usage

• wiki/Plugins.md - Using community plugins for additional functionality
• wiki/Plugin-Development.md - Creating custom plugins
• README.md - Section: # EMBEDDING - Using yt-dlp as a Python library

For Proxy and Network Issues

• README.md - Section: ## Network Options: - Proxy configuration, network settings
• README.md - Section: ## Geo-restriction: - Bypassing geo-blocks

Common Usage Patterns

When the user asks to:

• Download a video → Check # USAGE AND OPTIONS and ## Download Options:
• Extract audio → Check ## Post-Processing Options: and look for -x examples
• Download best quality → Check # FORMAT SELECTION for format sorting
• Download playlists → Check ## Video Selection: for playlist options
• Fix download errors → Check wiki/FAQ.md and ## Workarounds:
• Customize filenames → Check # OUTPUT TEMPLATE
• Download with cookies → Check ## Authentication Options:
• Handle YouTube issues → Check wiki/PO-Token-Guide.md and wiki/EJS.md

Related Skills

For audio transcription workflows:

• parakeet - Transcribe downloaded audio to text (SRT format)
• llm - Clean up transcripts into articles using audio-to-article.yaml template

Example workflow (download → transcribe → article):

yt-dlp -x --audio-format mp3 "URL"
uvx parakeet-mlx audio.mp3
python3 srt_to_text.py audio.srt | llm -t audio-to-article.yaml

Important Notes

1. Always check README.md first - It contains the complete command-line reference
2. Use the wiki for troubleshooting - FAQ.md covers most common issues
3. Format selection is powerful - The # FORMAT SELECTION section has extensive examples
4. YouTube requires special handling - See wiki/PO-Token-Guide.md and wiki/EJS.md for modern YouTube downloads
5. Post-processing requires ffmpeg - Many features depend on ffmpeg being installed

Quick Reference

Installation

# macOS via Homebrew
brew install yt-dlp

# Python pip
pip install yt-dlp

# Update
yt-dlp -U

Basic Commands

# Download video (best quality)
yt-dlp URL

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

# Download playlist
yt-dlp -o "%(playlist_index)s-%(title)s.%(ext)s" PLAYLIST_URL

# List available formats
yt-dlp -F URL

# Download specific format
yt-dlp -f FORMAT_ID URL

File Locations

• README.md - Complete command-line reference and documentation
• wiki/FAQ.md - Frequently asked questions and troubleshooting
• wiki/Installation.md - Detailed installation instructions
• wiki/PO-Token-Guide.md - YouTube authentication guide
• wiki/EJS.md - YouTube cipher decryption setup
• wiki/Extractors.md - Supported sites and extractor details
• wiki/Plugins.md - Plugin usage guide
• wiki/Plugin-Development.md - Plugin development guide

When in Doubt

1. Read the relevant section from README.md
2. Check wiki/FAQ.md for common issues
3. Use yt-dlp --help for complete option list
4. For site-specific issues, check wiki/Extractors.md