0
# Main Downloader
1
2
The YoutubeDL class is the primary interface for video downloading operations. It orchestrates the entire download process from URL parsing to file output, providing extensive configuration options and hooks for customization.
3
4
## Capabilities
5
6
### YoutubeDL Constructor
7
8
Creates a new YoutubeDL instance with extensive configuration options for controlling download behavior, output formatting, and processing options.
9
10
```python { .api }
11
class YoutubeDL:
12
def __init__(self, params=None, auto_init=True):
13
"""
14
Main youtube-dl downloader class.
15
16
Parameters:
17
- params (dict): Configuration dictionary with download options
18
- auto_init (bool): Whether to automatically initialize the instance
19
"""
20
```
21
22
### Core Download Methods
23
24
Primary methods for downloading videos and extracting information from supported sites.
25
26
```python { .api }
27
def download(self, url_list):
28
"""
29
Download a list of URLs.
30
31
Parameters:
32
- url_list (list): List of URLs to download
33
34
Returns:
35
int: Return code (0 for success, non-zero for errors)
36
"""
37
38
def extract_info(self, url, download=True, ie_key=None, extra_info={}, process=True, force_generic_extractor=False):
39
"""
40
Extract information from URL without necessarily downloading.
41
42
Parameters:
43
- url (str): URL to extract information from
44
- download (bool): Whether to download the video file
45
- ie_key (str): Force specific info extractor
46
- extra_info (dict): Additional information to merge
47
- process (bool): Whether to process the extracted information
48
- force_generic_extractor (bool): Force using generic extractor
49
50
Returns:
51
dict/list: Video information dictionary or list of dictionaries
52
"""
53
54
def process_info(self, info_dict):
55
"""
56
Process extracted information and download if requested.
57
58
Parameters:
59
- info_dict (dict): Video information dictionary
60
61
Returns:
62
dict: Processed information dictionary
63
"""
64
```
65
66
### URL Processing
67
68
Methods for handling and validating URLs before processing.
69
70
```python { .api }
71
def urlopen(self, req):
72
"""
73
Open URL with configured request parameters.
74
75
Parameters:
76
- req: Request object or URL string
77
78
Returns:
79
Response object
80
"""
81
82
def cache_fn(self, path):
83
"""
84
Return cached file path for given path.
85
86
Parameters:
87
- path (str): File path
88
89
Returns:
90
str: Cache file path
91
"""
92
```
93
94
### Progress and Logging
95
96
Methods for handling progress reporting and logging during downloads.
97
98
```python { .api }
99
def to_screen(self, message, skip_eol=False):
100
"""
101
Print message to screen if not in quiet mode.
102
103
Parameters:
104
- message (str): Message to display
105
- skip_eol (bool): Whether to skip end-of-line
106
"""
107
108
def report_warning(self, message):
109
"""
110
Report a warning message.
111
112
Parameters:
113
- message (str): Warning message
114
"""
115
116
def report_error(self, message, tb=None):
117
"""
118
Report an error message.
119
120
Parameters:
121
- message (str): Error message
122
- tb (str): Optional traceback
123
"""
124
```
125
126
### Playlist and Batch Processing
127
128
Methods for handling playlists and multiple URL processing.
129
130
```python { .api }
131
def download_with_info_file(self, info_filename):
132
"""
133
Download using information from JSON file.
134
135
Parameters:
136
- info_filename (str): Path to info JSON file
137
138
Returns:
139
int: Return code
140
"""
141
142
def prepare_filename(self, info_dict):
143
"""
144
Generate filename from template and video information.
145
146
Parameters:
147
- info_dict (dict): Video information dictionary
148
149
Returns:
150
str: Generated filename
151
"""
152
```
153
154
## Configuration Parameters
155
156
The YoutubeDL constructor accepts a comprehensive params dictionary with these key options:
157
158
### Basic Options
159
- `username` (str): Username for authentication
160
- `password` (str): Password for authentication
161
- `videopassword` (str): Password for video access
162
- `quiet` (bool): Suppress console output
163
- `verbose` (bool): Enable verbose output
164
- `no_warnings` (bool): Suppress warning messages
165
166
### Download Control
167
- `format` (str): Video format selector (e.g., 'best', 'worst', 'bestaudio')
168
- `outtmpl` (str): Output filename template
169
- `restrictfilenames` (bool): Restrict filenames to ASCII characters
170
- `ignoreerrors` (bool): Continue on download errors
171
- `nooverwrites` (bool): Don't overwrite existing files
172
- `continuedl` (bool): Continue partial downloads
173
- `retries` (int/str): Number of retries or 'infinite'
174
175
### Network Options
176
- `socket_timeout` (float): Socket timeout in seconds
177
- `proxy` (str): Proxy URL
178
- `source_address` (str): Client-side IP address to bind to
179
- `sleep_interval` (float): Sleep interval between downloads
180
- `max_sleep_interval` (float): Upper bound of sleep interval
181
182
### Processing Options
183
- `postprocessors` (list): List of post-processor configurations
184
- `keepvideo` (bool): Keep video file after post-processing
185
- `min_filesize` (int): Minimum file size for download
186
- `max_filesize` (int): Maximum file size for download
187
- `daterange` (DateRange): Date range for video filtering
188
189
## Usage Examples
190
191
### Basic Download
192
```python
193
from youtube_dl import YoutubeDL
194
195
ydl_opts = {}
196
with YoutubeDL(ydl_opts) as ydl:
197
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])
198
```
199
200
### Extract Info Only
201
```python
202
with YoutubeDL({'quiet': True}) as ydl:
203
info = ydl.extract_info('https://www.youtube.com/watch?v=VIDEO_ID', download=False)
204
title = info.get('title', 'Unknown')
205
duration = info.get('duration', 0)
206
```
207
208
### Custom Output Template
209
```python
210
ydl_opts = {
211
'outtmpl': '%(uploader)s/%(title)s.%(ext)s',
212
'format': 'best[height<=720]'
213
}
214
with YoutubeDL(ydl_opts) as ydl:
215
ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])
216
```