or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-download.mdexceptions.mdextractor-system.mdindex.mdpost-processing.mdutilities.md
tile.json

tessl/pypi-yt-dlp

A feature-rich command-line audio/video downloader forked from youtube-dl

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/yt-dlp@2024.12.x

To install, run

npx @tessl/cli install tessl/pypi-yt-dlp@2024.12.0

index.mddocs/

yt-dlp

A feature-rich command-line audio/video downloader forked from youtube-dl that supports downloading from thousands of video hosting sites including YouTube, Vimeo, Twitch, and many others. It provides extensive format selection capabilities, audio extraction, subtitle downloading, post-processing features, and advanced configuration options for customizing downloads.

Package Information

  • Package Name: yt-dlp
  • Package Type: PyPI
  • Language: Python
  • Installation: pip install yt-dlp
  • Requirements: Python 3.9+

Core Imports

import yt_dlp

For main functionality:

from yt_dlp import YoutubeDL

For extractor system:

from yt_dlp import gen_extractors, list_extractors
from yt_dlp.extractor import gen_extractor_classes, list_extractor_classes, get_info_extractor

For utilities:

from yt_dlp.utils import sanitize_filename, parse_duration, parse_bytes, unified_timestamp
from yt_dlp import Config, DateRange, FormatSorter, PlaylistEntries

For configuration and options:

from yt_dlp import parse_options, main
from yt_dlp.options import parseOpts

Basic Usage

import yt_dlp

# Basic download using the main API class
with yt_dlp.YoutubeDL() as ydl:
    ydl.download(['https://www.youtube.com/watch?v=example'])

# Download with custom options
ydl_opts = {
    'format': 'best[height<=720]',
    'outtmpl': '%(title)s.%(ext)s',
    'writesubtitles': True,
    'writeautomaticsub': True,
}

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

# Extract information without downloading
ydl_opts = {'skip_download': True}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info('https://www.youtube.com/watch?v=example')
    print(f"Title: {info['title']}")
    print(f"Duration: {info['duration']} seconds")

Architecture

yt-dlp follows a modular architecture designed for extensibility and robustness:

  • YoutubeDL Class: Central coordinator managing downloads, extractors, post-processors, and configuration
  • Extractor System: 1000+ site-specific extractors for different video platforms, each handling URL patterns, metadata extraction, and format discovery
  • Post-Processor Pipeline: Configurable chain of processors for audio extraction, video conversion, metadata embedding, and file manipulation
  • Networking Layer: Multi-backend HTTP handling with browser impersonation, proxy support, and cookie management
  • Utility System: Comprehensive utilities for filename sanitization, format parsing, template processing, and error handling

This design enables yt-dlp to handle the complexity of extracting media from diverse platforms while providing a simple Python API for integration into other applications.

Capabilities

Core Download API

The primary YoutubeDL class providing download management, information extraction, and configuration. This is the main interface for programmatic use of yt-dlp functionality.

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=None, process=True, force_generic_extractor=False): ...
    def process_ie_result(self, ie_result, download=True, extra_info=None): ...

Core Download API

Extractor System

Discovery and management of site-specific extractors that handle URL pattern matching, metadata extraction, and format enumeration for supported video platforms.

def gen_extractors(): ...
def list_extractors(age_limit=None): ...
def gen_extractor_classes(): ...
def list_extractor_classes(age_limit=None): ...
def get_info_extractor(ie_name): ...

Extractor System

CLI and Configuration

Command-line interface functions and option parsing for configuring yt-dlp behavior programmatically.

def main(argv=None): ...
def parse_options(argv=None): ...
def parseOpts(overrideArguments=None, ignore_config_files='if_override'): ...

Configuration Options

Utility Functions

Comprehensive utility functions for file handling, data parsing, URL processing, format conversion, and template processing commonly needed when working with media downloads.

def sanitize_filename(s, restricted=False, is_id=False): ...
def parse_duration(s): ...
def parse_bytes(s): ...
def unified_timestamp(date_str, day_first=True): ...
class Config: ...
class DateRange: ...
class FormatSorter: ...
class PlaylistEntries: ...

Utility Functions

Post-Processing

Configurable pipeline of processors for audio extraction, video conversion, subtitle handling, metadata embedding, and other file transformations applied after download.

class FFmpegExtractAudioPP: ...
class FFmpegMergerPP: ...
class FFmpegPostProcessor: ...
class FFmpegSubtitlesConvertorPP: ...
class FFmpegThumbnailsConvertorPP: ...
class FFmpegVideoConvertorPP: ...
class FFmpegVideoRemuxerPP: ...
class MetadataFromFieldPP: ...
class MetadataParserPP: ...

Post-Processing

Configuration Options

Comprehensive configuration system with 100+ parameters controlling download behavior, format selection, output templates, networking, and post-processing options.

def parse_options(argv=None): ...
def parseOpts(overrideArguments=None, ignore_config_files='if_override'): ...

Configuration Options

Exception Handling

Rich exception hierarchy providing detailed error information for different failure modes including network errors, extraction failures, and post-processing issues.

class YoutubeDLError(Exception): ...
class ExtractorError(YoutubeDLError): ...
class DownloadError(YoutubeDLError): ...
class DownloadCancelled(YoutubeDLError): ...
class SameFileError(YoutubeDLError): ...
class PostProcessingError(YoutubeDLError): ...

Exception Handling

Types

# Core configuration dictionary for YoutubeDL
YDLOptions = dict[str, Any]

# Information dictionary returned by extractors
InfoDict = dict[str, Any]

# Format information dictionary
FormatDict = dict[str, Any]

# Progress hook function signature
ProgressHook = Callable[[dict[str, Any]], None]

# Post-processor hook function signature
PostProcessorHook = Callable[[dict[str, Any]], None]