0
# youtube-dl
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: youtube-dl
7
- **Language**: Python
8
- **Installation**: `pip install youtube-dl`
9
- **Python Support**: 2.6+, 3.2+
10

11
## Core Imports
12

13
```python
14
from youtube_dl import YoutubeDL
15
```
16

17
For extractors and utilities:
18

19
```python
20
from youtube_dl import main, gen_extractors, list_extractors
21
from youtube_dl.YoutubeDL import YoutubeDL
22
```
23

24
## Basic Usage
25

26
```python
27
import youtube_dl
28

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

34
# Download with custom options
35
ydl_opts = {
36
    'format': 'bestaudio/best',
37
    'outtmpl': '%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s',
38
    'postprocessors': [{
39
        'key': 'FFmpegExtractAudio',
40
        'preferredcodec': 'mp3',
41
        'preferredquality': '192',
42
    }],
43
}
44
with youtube_dl.YoutubeDL(ydl_opts) as ydl:
45
    ydl.download(['https://www.youtube.com/playlist?list=PLrAXtmRdnEQy'])
46
```
47

48
## Architecture
49

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

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

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

60
## Capabilities
61

62
### Main Downloader Class
63

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

66
```python { .api }
67
class YoutubeDL:
68
    def __init__(self, params=None, auto_init=True): ...
69
    def download(self, url_list): ...
70
    def extract_info(self, url, download=True, ie_key=None, extra_info={}, process=True, force_generic_extractor=False): ...
71
    def process_info(self, info_dict): ...
72
```
73

74
[Main Downloader](./main-downloader.md)
75

76
### Information Extractors
77

78
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.
79

80
```python { .api }
81
def gen_extractors(): ...
82
def list_extractors(age_limit): ...
83
def get_info_extractor(ie_name): ...
84
```
85

86
[Extractors](./extractors.md)
87

88
### File Downloaders
89

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

92
```python { .api }
93
def get_suitable_downloader(info_dict, params={}): ...
94
class FileDownloader:
95
    def __init__(self, ydl, params): ...
96
    def download(self, filename, info_dict): ...
97
```
98

99
[Downloaders](./downloaders.md)
100

101
### Post-Processors
102

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

105
```python { .api }
106
class FFmpegExtractAudioPP: ...
107
class FFmpegVideoConvertorPP: ...
108
class FFmpegEmbedSubtitlePP: ...
109
class FFmpegMetadataPP: ...
110
```
111

112
[Post-Processors](./post-processors.md)
113

114
### Utilities and Helpers
115

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

118
```python { .api }
119
def sanitize_filename(s, restricted=False, is_id=False): ...
120
def format_bytes(bytes): ...
121
def parse_filesize(s): ...
122
def determine_ext(url, default_ext='unknown_video'): ...
123
```
124

125
[Utilities](./utilities.md)
126

127
## Error Handling
128

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

131
```python { .api }
132
class YoutubeDLError(Exception): ...
133
class ExtractorError(YoutubeDLError): ...
134
class DownloadError(YoutubeDLError): ...
135
class UnavailableVideoError(ExtractorError): ...
136
class ContentTooShortError(YoutubeDLError): ...
137
class GeoRestrictedError(ExtractorError): ...
138
class MaxDownloadsReached(YoutubeDLError): ...
139
```
140

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

143
## Command-Line Interface
144

145
### Main Entry Point
146

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

149
```python { .api }
150
def main(argv=None):
151
    """
152
    Main command-line entry point for youtube-dl.
153
    
154
    Parameters:
155
    - argv (list, optional): Command-line arguments list. If None, uses sys.argv
156
    
157
    Note: This function handles argument parsing, configuration, and execution.
158
    For programmatic use, prefer using YoutubeDL class directly.
159
    """
160
```