youtube-dl

A comprehensive Python library for downloading videos from YouTube and over 1000 other video sites. It provides extensive format selection capabilities, supports playlist downloading, offers video/audio extraction options, includes subtitle downloading functionality, and maintains cross-platform compatibility. The library is designed for maximum flexibility with configurable output templates, post-processing capabilities, authentication support, and batch processing features.

Package Information

• Package Name: youtube-dl
• Language: Python
• Installation: pip install youtube-dl
• Python Support: 2.6+, 3.2+

Core Imports

from youtube_dl import YoutubeDL

For extractors and utilities:

from youtube_dl import main, gen_extractors, list_extractors
from youtube_dl.YoutubeDL import YoutubeDL

Basic Usage

import youtube_dl

# Simple download using default options
ydl_opts = {}
with youtube_dl.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])

# Download with custom options
ydl_opts = {
    'format': 'bestaudio/best',
    'outtmpl': '%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'mp3',
        'preferredquality': '192',
    }],
}
with youtube_dl.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/playlist?list=PLrAXtmRdnEQy'])

Architecture

youtube-dl follows a modular architecture with these key components:

• YoutubeDL: Main controller class that orchestrates the download process
• InfoExtractors: Site-specific modules that extract video metadata and URLs (1000+ sites supported)
• FileDownloaders: Protocol-specific download handlers (HTTP, HLS, DASH, RTMP, etc.)
• PostProcessors: Media processing modules for format conversion, subtitle embedding, etc.
• Utilities: Helper functions for text processing, network operations, and platform compatibility

This design allows youtube-dl to support hundreds of video sites while maintaining a consistent API and enabling extensive customization through configuration options.

Capabilities

Main Downloader Class

Core functionality for video downloading, metadata extraction, and media processing. The YoutubeDL class provides the primary interface for all download operations.

class YoutubeDL:
    def __init__(self, params=None, auto_init=True): ...
    def download(self, url_list): ...
    def extract_info(self, url, download=True, ie_key=None, extra_info={}, process=True, force_generic_extractor=False): ...
    def process_info(self, info_dict): ...

Main Downloader

Information Extractors

Site-specific modules that handle video metadata extraction from over 1000 supported sites. Each extractor understands the specific URL patterns and API interfaces for its target site.

def gen_extractors(): ...
def list_extractors(age_limit): ...
def get_info_extractor(ie_name): ...

Extractors

File Downloaders

Protocol-specific download handlers that manage the actual file transfer process, supporting various streaming protocols and network conditions.

def get_suitable_downloader(info_dict, params={}): ...
class FileDownloader:
    def __init__(self, ydl, params): ...
    def download(self, filename, info_dict): ...

Downloaders

Post-Processors

Media processing modules for format conversion, audio extraction, subtitle handling, and metadata manipulation after download completion.

class FFmpegExtractAudioPP: ...
class FFmpegVideoConvertorPP: ...
class FFmpegEmbedSubtitlePP: ...
class FFmpegMetadataPP: ...

Post-Processors

Utilities and Helpers

Comprehensive utility functions for text processing, network operations, date parsing, file handling, and cross-platform compatibility.

def sanitize_filename(s, restricted=False, is_id=False): ...
def format_bytes(bytes): ...
def parse_filesize(s): ...
def determine_ext(url, default_ext='unknown_video'): ...

Utilities

Error Handling

youtube-dl defines several exception classes for different error conditions:

class YoutubeDLError(Exception): ...
class ExtractorError(YoutubeDLError): ...
class DownloadError(YoutubeDLError): ...
class UnavailableVideoError(ExtractorError): ...
class ContentTooShortError(YoutubeDLError): ...
class GeoRestrictedError(ExtractorError): ...
class MaxDownloadsReached(YoutubeDLError): ...

These exceptions provide specific error information for different failure scenarios during the download process.

Command-Line Interface

Main Entry Point

Command-line interface function that parses arguments and executes download operations.

def main(argv=None):
    """
    Main command-line entry point for youtube-dl.
    
    Parameters:
    - argv (list, optional): Command-line arguments list. If None, uses sys.argv
    
    Note: This function handles argument parsing, configuration, and execution.
    For programmatic use, prefer using YoutubeDL class directly.
    """