]> Raphaël G. Git Repositories - youtubedl/blob - README.txt
69cab28b5900b8300034139d0d191a42633c1c05
[youtubedl] / README.txt
1 NAME
2 ====
3
4 youtube-dl - download videos from youtube.com or other video platforms
5
6 SYNOPSIS
7 ========
8
9 youtube-dl OPTIONS URL [URL...]
10
11 DESCRIPTION
12 ===========
13
14 youtube-dl is a small command-line program to download videos from
15 YouTube.com and a few more sites. It requires the Python interpreter,
16 version 2.6, 2.7, or 3.3+, and it is not platform specific. It should
17 work on your Unix box, on Windows or on Mac OS X. It is released to the
18 public domain, which means you can modify it, redistribute it or use it
19 however you like.
20
21 OPTIONS
22 =======
23
24 -h, --help print this help text and exit
25 --version print program version and exit
26 -U, --update update this program to latest version. Make sure
27 that you have sufficient permissions (run with
28 sudo if needed)
29 -i, --ignore-errors continue on download errors, for example to to
30 skip unavailable videos in a playlist
31 --abort-on-error Abort downloading of further videos (in the
32 playlist or the command line) if an error occurs
33 --dump-user-agent display the current browser identification
34 --user-agent UA specify a custom user agent
35 --referer REF specify a custom referer, use if the video access
36 is restricted to one domain
37 --list-extractors List all supported extractors and the URLs they
38 would handle
39 --extractor-descriptions Output descriptions of all supported extractors
40 --proxy URL Use the specified HTTP/HTTPS proxy. Pass in an
41 empty string (--proxy "") for direct connection
42 --no-check-certificate Suppress HTTPS certificate validation.
43 --cache-dir DIR Location in the filesystem where youtube-dl can
44 store some downloaded information permanently. By
45 default $XDG_CACHE_HOME/youtube-dl or ~/.cache
46 /youtube-dl . At the moment, only YouTube player
47 files (for videos with obfuscated signatures) are
48 cached, but that may change.
49 --no-cache-dir Disable filesystem caching
50 --socket-timeout None Time to wait before giving up, in seconds
51 --bidi-workaround Work around terminals that lack bidirectional
52 text support. Requires bidiv or fribidi
53 executable in PATH
54
55 Video Selection:
56 ----------------
57
58 --playlist-start NUMBER playlist video to start at (default is 1)
59 --playlist-end NUMBER playlist video to end at (default is last)
60 --match-title REGEX download only matching titles (regex or caseless
61 sub-string)
62 --reject-title REGEX skip download for matching titles (regex or
63 caseless sub-string)
64 --max-downloads NUMBER Abort after downloading NUMBER files
65 --min-filesize SIZE Do not download any videos smaller than SIZE
66 (e.g. 50k or 44.6m)
67 --max-filesize SIZE Do not download any videos larger than SIZE (e.g.
68 50k or 44.6m)
69 --date DATE download only videos uploaded in this date
70 --datebefore DATE download only videos uploaded on or before this
71 date (i.e. inclusive)
72 --dateafter DATE download only videos uploaded on or after this
73 date (i.e. inclusive)
74 --min-views COUNT Do not download any videos with less than COUNT
75 views
76 --max-views COUNT Do not download any videos with more than COUNT
77 views
78 --no-playlist download only the currently playing video
79 --age-limit YEARS download only videos suitable for the given age
80 --download-archive FILE Download only videos not listed in the archive
81 file. Record the IDs of all downloaded videos in
82 it.
83
84 Download Options:
85 -----------------
86
87 -r, --rate-limit LIMIT maximum download rate in bytes per second (e.g.
88 50K or 4.2M)
89 -R, --retries RETRIES number of retries (default is 10)
90 --buffer-size SIZE size of download buffer (e.g. 1024 or 16K)
91 (default is 1024)
92 --no-resize-buffer do not automatically adjust the buffer size. By
93 default, the buffer size is automatically resized
94 from an initial value of SIZE.
95
96 Filesystem Options:
97 -------------------
98
99 -t, --title use title in file name (default)
100 --id use only video ID in file name
101 -l, --literal [deprecated] alias of --title
102 -A, --auto-number number downloaded files starting from 00000
103 -o, --output TEMPLATE output filename template. Use %(title)s to get
104 the title, %(uploader)s for the uploader name,
105 %(uploader_id)s for the uploader nickname if
106 different, %(autonumber)s to get an automatically
107 incremented number, %(ext)s for the filename
108 extension, %(format)s for the format description
109 (like "22 - 1280x720" or "HD"), %(format_id)s for
110 the unique id of the format (like Youtube's
111 itags: "137"), %(upload_date)s for the upload
112 date (YYYYMMDD), %(extractor)s for the provider
113 (youtube, metacafe, etc), %(id)s for the video
114 id, %(playlist)s for the playlist the video is
115 in, %(playlist_index)s for the position in the
116 playlist and %% for a literal percent. Use - to
117 output to stdout. Can also be used to download to
118 a different directory, for example with -o '/my/d
119 ownloads/%(uploader)s/%(title)s-%(id)s.%(ext)s' .
120 --autonumber-size NUMBER Specifies the number of digits in %(autonumber)s
121 when it is present in output filename template or
122 --auto-number option is given
123 --restrict-filenames Restrict filenames to only ASCII characters, and
124 avoid "&" and spaces in filenames
125 -a, --batch-file FILE file containing URLs to download ('-' for stdin)
126 --load-info FILE json file containing the video information
127 (created with the "--write-json" option)
128 -w, --no-overwrites do not overwrite files
129 -c, --continue force resume of partially downloaded files. By
130 default, youtube-dl will resume downloads if
131 possible.
132 --no-continue do not resume partially downloaded files (restart
133 from beginning)
134 --cookies FILE file to read cookies from and dump cookie jar in
135 --no-part do not use .part files
136 --no-mtime do not use the Last-modified header to set the
137 file modification time
138 --write-description write video description to a .description file
139 --write-info-json write video metadata to a .info.json file
140 --write-annotations write video annotations to a .annotation file
141 --write-thumbnail write thumbnail image to disk
142
143 Verbosity / Simulation Options:
144 -------------------------------
145
146 -q, --quiet activates quiet mode
147 -s, --simulate do not download the video and do not write
148 anything to disk
149 --skip-download do not download the video
150 -g, --get-url simulate, quiet but print URL
151 -e, --get-title simulate, quiet but print title
152 --get-id simulate, quiet but print id
153 --get-thumbnail simulate, quiet but print thumbnail URL
154 --get-description simulate, quiet but print video description
155 --get-duration simulate, quiet but print video length
156 --get-filename simulate, quiet but print output filename
157 --get-format simulate, quiet but print output format
158 -j, --dump-json simulate, quiet but print JSON information
159 --newline output progress bar as new lines
160 --no-progress do not print progress bar
161 --console-title display progress in console titlebar
162 -v, --verbose print various debugging information
163 --dump-intermediate-pages print downloaded pages to debug problems (very
164 verbose)
165 --write-pages Write downloaded intermediary pages to files in
166 the current directory to debug problems
167
168 Video Format Options:
169 ---------------------
170
171 -f, --format FORMAT video format code, specify the order of
172 preference using slashes: "-f 22/17/18". "-f mp4"
173 and "-f flv" are also supported
174 --all-formats download all available video formats
175 --prefer-free-formats prefer free video formats unless a specific one
176 is requested
177 --max-quality FORMAT highest quality format to download
178 -F, --list-formats list all available formats
179
180 Subtitle Options:
181 -----------------
182
183 --write-sub write subtitle file
184 --write-auto-sub write automatic subtitle file (youtube only)
185 --all-subs downloads all the available subtitles of the
186 video
187 --list-subs lists all available subtitles for the video
188 --sub-format FORMAT subtitle format (default=srt) ([sbv/vtt] youtube
189 only)
190 --sub-lang LANGS languages of the subtitles to download (optional)
191 separated by commas, use IETF language tags like
192 'en,pt'
193
194 Authentication Options:
195 -----------------------
196
197 -u, --username USERNAME account username
198 -p, --password PASSWORD account password
199 -n, --netrc use .netrc authentication data
200 --video-password PASSWORD video password (vimeo, smotri)
201
202 Post-processing Options:
203 ------------------------
204
205 -x, --extract-audio convert video files to audio-only files (requires
206 ffmpeg or avconv and ffprobe or avprobe)
207 --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a", "opus", or
208 "wav"; best by default
209 --audio-quality QUALITY ffmpeg/avconv audio quality specification, insert
210 a value between 0 (better) and 9 (worse) for VBR
211 or a specific bitrate like 128K (default 5)
212 --recode-video FORMAT Encode the video to another format if necessary
213 (currently supported: mp4|flv|ogg|webm)
214 -k, --keep-video keeps the video file on disk after the post-
215 processing; the video is erased by default
216 --no-post-overwrites do not overwrite post-processed files; the post-
217 processed files are overwritten by default
218 --embed-subs embed subtitles in the video (only for mp4
219 videos)
220 --add-metadata write metadata to the video file
221 --xattrs write metadata to the video file's xattrs (using
222 dublin core and xdg standards)
223 --prefer-avconv Prefer avconv over ffmpeg for running the
224 postprocessors (default)
225 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
226 postprocessors
227
228 CONFIGURATION
229 =============
230
231 You can configure youtube-dl by placing default arguments (such as
232 --extract-audio --no-mtime to always extract the audio and not copy the
233 mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl.conf. On
234 Windows, the configuration file locations are
235 %APPDATA%\youtube-dl\config.txt and C:\Users\<Yourname>\youtube-dl.conf.
236
237 OUTPUT TEMPLATE
238 ===============
239
240 The -o option allows users to indicate a template for the output file
241 names. The basic usage is not to set any template arguments when
242 downloading a single file, like in
243 youtube-dl -o funny_video.flv "http://some/video". However, it may
244 contain special sequences that will be replaced when downloading each
245 video. The special sequences have the format %(NAME)s. To clarify, that
246 is a percent symbol followed by a name in parenthesis, followed by a
247 lowercase S. Allowed names are:
248
249 - id: The sequence will be replaced by the video identifier.
250 - url: The sequence will be replaced by the video URL.
251 - uploader: The sequence will be replaced by the nickname of the
252 person who uploaded the video.
253 - upload_date: The sequence will be replaced by the upload date in
254 YYYYMMDD format.
255 - title: The sequence will be replaced by the video title.
256 - ext: The sequence will be replaced by the appropriate extension
257 (like flv or mp4).
258 - epoch: The sequence will be replaced by the Unix epoch when creating
259 the file.
260 - autonumber: The sequence will be replaced by a five-digit number
261 that will be increased with each download, starting at zero.
262 - playlist: The name or the id of the playlist that contains the
263 video.
264 - playlist_index: The index of the video in the playlist, a five-digit
265 number.
266
267 The current default template is %(title)s-%(id)s.%(ext)s.
268
269 In some cases, you don't want special characters such as 中, spaces, or
270 &, such as when transferring the downloaded filename to a Windows system
271 or the filename through an 8bit-unsafe channel. In these cases, add the
272 --restrict-filenames flag to get a shorter title:
273
274 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
275 youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters
276 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
277 youtube-dl_test_video_.mp4 # A simple file name
278
279 VIDEO SELECTION
280 ===============
281
282 Videos can be filtered by their upload date using the options --date,
283 --datebefore or --dateafter, they accept dates in two formats:
284
285 - Absolute dates: Dates in the format YYYYMMDD.
286 - Relative dates: Dates in the format
287 (now|today)[+-][0-9](day|week|month|year)(s)?
288
289 Examples:
290
291 $ # Download only the videos uploaded in the last 6 months $ youtube-dl
292 --dateafter now-6months $ # Download only the videos uploaded on January
293 1, 1970 $ youtube-dl --date 19700101 $ # will only download the videos
294 uploaded in the 200x decade $ youtube-dl --dateafter 20000101
295 --datebefore 20091231
296
297 FAQ
298 ===
299
300 Can you please put the -b option back?
301
302 Most people asking this question are not aware that youtube-dl now
303 defaults to downloading the highest available quality as reported by
304 YouTube, which will be 1080p or 720p in some cases, so you no longer
305 need the -b option. For some specific videos, maybe YouTube does not
306 report them to be available in a specific high quality format you're
307 interested in. In that case, simply request it with the -f option and
308 youtube-dl will try to download it.
309
310 I get HTTP error 402 when trying to download a video. What's this?
311
312 Apparently YouTube requires you to pass a CAPTCHA test if you download
313 too much. We're considering to provide a way to let you solve the
314 CAPTCHA, but at the moment, your best course of action is pointing a
315 webbrowser to the youtube URL, solving the CAPTCHA, and restart
316 youtube-dl.
317
318 I have downloaded a video but how can I play it?
319
320 Once the video is fully downloaded, use any video player, such as vlc or
321 mplayer.
322
323 The links provided by youtube-dl -g are not working anymore
324
325 The URLs youtube-dl outputs require the downloader to have the correct
326 cookies. Use the --cookies option to write the required cookies into a
327 file, and advise your downloader to read cookies from that file. Some
328 sites also require a common user agent to be used, use --dump-user-agent
329 to see the one in use by youtube-dl.
330
331 ERROR: no fmt_url_map or conn information found in video info
332
333 youtube has switched to a new video info format in July 2011 which is
334 not supported by old versions of youtube-dl. You can update youtube-dl
335 with sudo youtube-dl --update.
336
337 ERROR: unable to download video
338
339 youtube requires an additional signature since September 2012 which is
340 not supported by old versions of youtube-dl. You can update youtube-dl
341 with sudo youtube-dl --update.
342
343 SyntaxError: Non-ASCII character
344
345 The error
346
347 File "youtube-dl", line 2
348 SyntaxError: Non-ASCII character '\x93' ...
349
350 means you're using an outdated version of Python. Please update to
351 Python 2.6 or 2.7.
352
353 What is this binary file? Where has the code gone?
354
355 Since June 2012 (#342) youtube-dl is packed as an executable zipfile,
356 simply unzip it (might need renaming to youtube-dl.zip first on some
357 systems) or clone the git repository, as laid out above. If you modify
358 the code, you can run it by executing the __main__.py file. To recompile
359 the executable, run make youtube-dl.
360
361 The exe throws a Runtime error from Visual C++
362
363 To run the exe you need to install first the Microsoft Visual C++ 2008
364 Redistributable Package.
365
366 COPYRIGHT
367 =========
368
369 youtube-dl is released into the public domain by the copyright holders.
370
371 This README file was originally written by Daniel Bolton
372 (https://github.com/dbbolton) and is likewise released into the public
373 domain.
374
375 BUGS
376 ====
377
378 Bugs and suggestions should be reported at:
379 https://github.com/rg3/youtube-dl/issues . Unless you were prompted so
380 or there is another pertinent reason (e.g. GitHub fails to accept the
381 bug report), please do not send bug reports via personal email.
382
383 Please include the full output of the command when run with --verbose.
384 The output (including the first lines) contain important debugging
385 information. Issues without the full output are often not reproducible
386 and therefore do not get solved in short order, if ever.
387
388 For discussions, join us in the irc channel #youtube-dl on freenode.
389
390 When you submit a request, please re-read it once to avoid a couple of
391 mistakes (you can and should use this as a checklist):
392
393 Is the description of the issue itself sufficient?
394
395 We often get issue reports that we cannot really decipher. While in most
396 cases we eventually get the required information after asking back
397 multiple times, this poses an unnecessary drain on our resources. Many
398 contributors, including myself, are also not native speakers, so we may
399 misread some parts.
400
401 So please elaborate on what feature you are requesting, or what bug you
402 want to be fixed. Make sure that it's obvious
403
404 - What the problem is
405 - How it could be fixed
406 - How your proposed solution would look like
407
408 If your report is shorter than two lines, it is almost certainly missing
409 some of these, which makes it hard for us to respond to it. We're often
410 too polite to close the issue outright, but the missing info makes
411 misinterpretation likely. As a commiter myself, I often get frustrated
412 by these issues, since the only possible way for me to move forward on
413 them is to ask for clarification over and over.
414
415 For bug reports, this means that your report should contain the complete
416 output of youtube-dl when called with the -v flag. The error message you
417 get for (most) bugs even says so, but you would not believe how many of
418 our bug reports do not contain this information.
419
420 Site support requests must contain an example URL. An example URL is a
421 URL you might want to download, like
422 http://www.youtube.com/watch?v=BaW_jenozKc . There should be an obvious
423 video present. Except under very special circumstances, the main page of
424 a video service (e.g. http://www.youtube.com/ ) is not an example URL.
425
426 Are you using the latest version?
427
428 Before reporting any issue, type youtube-dl -U. This should report that
429 you're up-to-date. About 20% of the reports we receive are already
430 fixed, but people are using outdated versions. This goes for feature
431 requests as well.
432
433 Is the issue already documented?
434
435 Make sure that someone has not already opened the issue you're trying to
436 open. Search at the top of the window or at
437 https://github.com/rg3/youtube-dl/search?type=Issues . If there is an
438 issue, feel free to write something along the lines of "This affects me
439 as well, with version 2015.01.01. Here is some more information on the
440 issue: ...". While some issues may be old, a new post into them often
441 spurs rapid activity.
442
443 Why are existing options not enough?
444
445 Before requesting a new feature, please have a quick peek at the list of
446 supported options. Many feature requests are for features that actually
447 exist already! Please, absolutely do show off your work in the issue
448 report and detail how the existing similar options do not solve your
449 problem.
450
451 Is there enough context in your bug report?
452
453 People want to solve problems, and often think they do us a favor by
454 breaking down their larger problems (e.g. wanting to skip already
455 downloaded files) to a specific request (e.g. requesting us to look
456 whether the file exists before downloading the info page). However, what
457 often happens is that they break down the problem into two steps: One
458 simple, and one impossible (or extremely complicated one).
459
460 We are then presented with a very complicated request when the original
461 problem could be solved far easier, e.g. by recording the downloaded
462 video IDs in a separate file. To avoid this, you must include the
463 greater context where it is non-obvious. In particular, every feature
464 request that does not consist of adding support for a new site should
465 contain a use case scenario that explains in what situation the missing
466 feature would be useful.
467
468 Does the issue involve one problem, and one problem only?
469
470 Some of our users seem to think there is a limit of issues they can or
471 should open. There is no limit of issues they can or should open. While
472 it may seem appealing to be able to dump all your issues into one
473 ticket, that means that someone who solves one of your issues cannot
474 mark the issue as closed. Typically, reporting a bunch of issues leads
475 to the ticket lingering since nobody wants to attack that behemoth,
476 until someone mercifully splits the issue into multiple ones.
477
478 In particular, every site support request issue should only pertain to
479 services at one site (generally under a common domain, but always using
480 the same backend technology). Do not request support for vimeo user
481 videos, Whitehouse podcasts, and Google Plus pages in the same issue.
482 Also, make sure that you don't post bug reports alongside feature
483 requests. As a rule of thumb, a feature request does not include outputs
484 of youtube-dl that are not immediately related to the feature at hand.
485 Do not post reports of a network error alongside the request for a new
486 video service.
487
488 Is anyone going to need the feature?
489
490 Only post features that you (or an incapicated friend you can personally
491 talk to) require. Do not post features because they seem like a good
492 idea. If they are really useful, they will be requested by someone who
493 requires them.
494
495 Is your question about youtube-dl?
496
497 It may sound strange, but some bug reports we receive are completely
498 unrelated to youtube-dl and relate to a different or even the reporter's
499 own application. Please make sure that you are actually using
500 youtube-dl. If you are using a UI for youtube-dl, report the bug to the
501 maintainer of the actual application providing the UI. On the other
502 hand, if your UI for youtube-dl fails in some way you believe is related
503 to youtube-dl, by all means, go ahead and report the bug.