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