]> Raphaƫl G. Git Repositories - youtubedl/blob - README.txt
3ba6f53d508a59e82b0046557c3b08f7374068eb
[youtubedl] / README.txt
1 youtube-dl - download videos from youtube.com or other video platforms
2
3 SYNOPSIS
4 ========
5
6 youtube-dl OPTIONS URL [URL...]
7
8 INSTALLATION
9 ============
10
11 To install it right away for all UNIX users (Linux, OS X, etc.), type:
12
13 sudo curl https://yt-dl.org/latest/youtube-dl -o /usr/local/bin/youtube-dl
14 sudo chmod a+x /usr/local/bin/youtube-dl
15
16 If you do not have curl, you can alternatively use a recent wget:
17
18 sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
19 sudo chmod a+x /usr/local/bin/youtube-dl
20
21 Windows users can download a .exe file and place it in their home
22 directory or any other location on their PATH.
23
24 OS X users can install youtube-dl with Homebrew.
25
26 brew install youtube-dl
27
28 You can also use pip:
29
30 sudo pip install youtube-dl
31
32 Alternatively, refer to the developer instructions below for how to
33 check out and work with the git repository. For further options,
34 including PGP signatures, see
35 https://rg3.github.io/youtube-dl/download.html .
36
37 DESCRIPTION
38 ===========
39
40 youtube-dl is a small command-line program to download videos from
41 YouTube.com and a few more sites. It requires the Python interpreter,
42 version 2.6, 2.7, or 3.3+, and it is not platform specific. It should
43 work on your Unix box, on Windows or on Mac OS X. It is released to the
44 public domain, which means you can modify it, redistribute it or use it
45 however you like.
46
47 OPTIONS
48 =======
49
50 -h, --help print this help text and exit
51 --version print program version and exit
52 -U, --update update this program to latest version. Make
53 sure that you have sufficient permissions
54 (run with sudo if needed)
55 -i, --ignore-errors continue on download errors, for example to
56 skip unavailable videos in a playlist
57 --abort-on-error Abort downloading of further videos (in the
58 playlist or the command line) if an error
59 occurs
60 --dump-user-agent display the current browser identification
61 --list-extractors List all supported extractors and the URLs
62 they would handle
63 --extractor-descriptions Output descriptions of all supported
64 extractors
65 --proxy URL Use the specified HTTP/HTTPS proxy. Pass in
66 an empty string (--proxy "") for direct
67 connection
68 --socket-timeout None Time to wait before giving up, in seconds
69 --default-search PREFIX Use this prefix for unqualified URLs. For
70 example "gvsearch2:" downloads two videos
71 from google videos for youtube-dl "large
72 apple". Use the value "auto" to let
73 youtube-dl guess ("auto_warning" to emit a
74 warning when guessing). "error" just throws
75 an error. The default value "fixup_error"
76 repairs broken URLs, but emits an error if
77 this is not possible instead of searching.
78 --ignore-config Do not read configuration files. When given
79 in the global configuration file /etc
80 /youtube-dl.conf: do not read the user
81 configuration in ~/.config/youtube-dl.conf
82 (%APPDATA%/youtube-dl/config.txt on
83 Windows)
84 --flat-playlist Do not extract the videos of a playlist,
85 only list them.
86
87 Video Selection:
88 ----------------
89
90 --playlist-start NUMBER playlist video to start at (default is 1)
91 --playlist-end NUMBER playlist video to end at (default is last)
92 --match-title REGEX download only matching titles (regex or
93 caseless sub-string)
94 --reject-title REGEX skip download for matching titles (regex or
95 caseless sub-string)
96 --max-downloads NUMBER Abort after downloading NUMBER files
97 --min-filesize SIZE Do not download any videos smaller than
98 SIZE (e.g. 50k or 44.6m)
99 --max-filesize SIZE Do not download any videos larger than SIZE
100 (e.g. 50k or 44.6m)
101 --date DATE download only videos uploaded in this date
102 --datebefore DATE download only videos uploaded on or before
103 this date (i.e. inclusive)
104 --dateafter DATE download only videos uploaded on or after
105 this date (i.e. inclusive)
106 --min-views COUNT Do not download any videos with less than
107 COUNT views
108 --max-views COUNT Do not download any videos with more than
109 COUNT views
110 --no-playlist download only the currently playing video
111 --age-limit YEARS download only videos suitable for the given
112 age
113 --download-archive FILE Download only videos not listed in the
114 archive file. Record the IDs of all
115 downloaded videos in it.
116 --include-ads Download advertisements as well
117 (experimental)
118
119 Download Options:
120 -----------------
121
122 -r, --rate-limit LIMIT maximum download rate in bytes per second
123 (e.g. 50K or 4.2M)
124 -R, --retries RETRIES number of retries (default is 10)
125 --buffer-size SIZE size of download buffer (e.g. 1024 or 16K)
126 (default is 1024)
127 --no-resize-buffer do not automatically adjust the buffer
128 size. By default, the buffer size is
129 automatically resized from an initial value
130 of SIZE.
131
132 Filesystem Options:
133 -------------------
134
135 -a, --batch-file FILE file containing URLs to download ('-' for
136 stdin)
137 --id use only video ID in file name
138 -A, --auto-number number downloaded files starting from 00000
139 -o, --output TEMPLATE output filename template. Use %(title)s to
140 get the title, %(uploader)s for the
141 uploader name, %(uploader_id)s for the
142 uploader nickname if different,
143 %(autonumber)s to get an automatically
144 incremented number, %(ext)s for the
145 filename extension, %(format)s for the
146 format description (like "22 - 1280x720" or
147 "HD"), %(format_id)s for the unique id of
148 the format (like Youtube's itags: "137"),
149 %(upload_date)s for the upload date
150 (YYYYMMDD), %(extractor)s for the provider
151 (youtube, metacafe, etc), %(id)s for the
152 video id, %(playlist_title)s,
153 %(playlist_id)s, or %(playlist)s (=title if
154 present, ID otherwise) for the playlist the
155 video is in, %(playlist_index)s for the
156 position in the playlist. %(height)s and
157 %(width)s for the width and height of the
158 video format. %(resolution)s for a textual
159 description of the resolution of the video
160 format. %% for a literal percent. Use - to
161 output to stdout. Can also be used to
162 download to a different directory, for
163 example with -o '/my/downloads/%(uploader)s
164 /%(title)s-%(id)s.%(ext)s' .
165 --autonumber-size NUMBER Specifies the number of digits in
166 %(autonumber)s when it is present in output
167 filename template or --auto-number option
168 is given
169 --restrict-filenames Restrict filenames to only ASCII
170 characters, and avoid "&" and spaces in
171 filenames
172 -t, --title [deprecated] use title in file name
173 (default)
174 -l, --literal [deprecated] alias of --title
175 -w, --no-overwrites do not overwrite files
176 -c, --continue force resume of partially downloaded files.
177 By default, youtube-dl will resume
178 downloads if possible.
179 --no-continue do not resume partially downloaded files
180 (restart from beginning)
181 --no-part do not use .part files - write directly
182 into output file
183 --no-mtime do not use the Last-modified header to set
184 the file modification time
185 --write-description write video description to a .description
186 file
187 --write-info-json write video metadata to a .info.json file
188 --write-annotations write video annotations to a .annotation
189 file
190 --write-thumbnail write thumbnail image to disk
191 --load-info FILE json file containing the video information
192 (created with the "--write-json" option)
193 --cookies FILE file to read cookies from and dump cookie
194 jar in
195 --cache-dir DIR Location in the filesystem where youtube-dl
196 can store some downloaded information
197 permanently. By default $XDG_CACHE_HOME
198 /youtube-dl or ~/.cache/youtube-dl . At the
199 moment, only YouTube player files (for
200 videos with obfuscated signatures) are
201 cached, but that may change.
202 --no-cache-dir Disable filesystem caching
203 --rm-cache-dir Delete all filesystem cache files
204
205 Verbosity / Simulation Options:
206 -------------------------------
207
208 -q, --quiet activates quiet mode
209 --no-warnings Ignore warnings
210 -s, --simulate do not download the video and do not write
211 anything to disk
212 --skip-download do not download the video
213 -g, --get-url simulate, quiet but print URL
214 -e, --get-title simulate, quiet but print title
215 --get-id simulate, quiet but print id
216 --get-thumbnail simulate, quiet but print thumbnail URL
217 --get-description simulate, quiet but print video description
218 --get-duration simulate, quiet but print video length
219 --get-filename simulate, quiet but print output filename
220 --get-format simulate, quiet but print output format
221 -j, --dump-json simulate, quiet but print JSON information.
222 See --output for a description of available
223 keys.
224 -J, --dump-single-json simulate, quiet but print JSON information
225 for each command-line argument. If the URL
226 refers to a playlist, dump the whole
227 playlist information in a single line.
228 --newline output progress bar as new lines
229 --no-progress do not print progress bar
230 --console-title display progress in console titlebar
231 -v, --verbose print various debugging information
232 --dump-intermediate-pages print downloaded pages to debug problems
233 (very verbose)
234 --write-pages Write downloaded intermediary pages to
235 files in the current directory to debug
236 problems
237 --print-traffic Display sent and read HTTP traffic
238
239 Workarounds:
240 ------------
241
242 --encoding ENCODING Force the specified encoding (experimental)
243 --no-check-certificate Suppress HTTPS certificate validation.
244 --prefer-insecure Use an unencrypted connection to retrieve
245 information about the video. (Currently
246 supported only for YouTube)
247 --user-agent UA specify a custom user agent
248 --referer URL specify a custom referer, use if the video
249 access is restricted to one domain
250 --add-header FIELD:VALUE specify a custom HTTP header and its value,
251 separated by a colon ':'. You can use this
252 option multiple times
253 --bidi-workaround Work around terminals that lack
254 bidirectional text support. Requires bidiv
255 or fribidi executable in PATH
256
257 Video Format Options:
258 ---------------------
259
260 -f, --format FORMAT video format code, specify the order of
261 preference using slashes: -f 22/17/18 . -f
262 mp4 , -f m4a and -f flv are also
263 supported. You can also use the special
264 names "best", "bestvideo", "bestaudio",
265 "worst", "worstvideo" and "worstaudio". By
266 default, youtube-dl will pick the best
267 quality. Use commas to download multiple
268 audio formats, such as -f
269 136/137/mp4/bestvideo,140/m4a/bestaudio.
270 You can merge the video and audio of two
271 formats into a single file using -f <video-
272 format>+<audio-format> (requires ffmpeg or
273 avconv), for example -f
274 bestvideo+bestaudio.
275 --all-formats download all available video formats
276 --prefer-free-formats prefer free video formats unless a specific
277 one is requested
278 --max-quality FORMAT highest quality format to download
279 -F, --list-formats list all available formats
280 --youtube-skip-dash-manifest Do not download the DASH manifest on
281 YouTube videos
282
283 Subtitle Options:
284 -----------------
285
286 --write-sub write subtitle file
287 --write-auto-sub write automatic subtitle file (youtube
288 only)
289 --all-subs downloads all the available subtitles of
290 the video
291 --list-subs lists all available subtitles for the video
292 --sub-format FORMAT subtitle format (default=srt) ([sbv/vtt]
293 youtube only)
294 --sub-lang LANGS languages of the subtitles to download
295 (optional) separated by commas, use IETF
296 language tags like 'en,pt'
297
298 Authentication Options:
299 -----------------------
300
301 -u, --username USERNAME login with this account ID
302 -p, --password PASSWORD account password
303 -2, --twofactor TWOFACTOR two-factor auth code
304 -n, --netrc use .netrc authentication data
305 --video-password PASSWORD video password (vimeo, smotri)
306
307 Post-processing Options:
308 ------------------------
309
310 -x, --extract-audio convert video files to audio-only files
311 (requires ffmpeg or avconv and ffprobe or
312 avprobe)
313 --audio-format FORMAT "best", "aac", "vorbis", "mp3", "m4a",
314 "opus", or "wav"; "best" by default
315 --audio-quality QUALITY ffmpeg/avconv audio quality specification,
316 insert a value between 0 (better) and 9
317 (worse) for VBR or a specific bitrate like
318 128K (default 5)
319 --recode-video FORMAT Encode the video to another format if
320 necessary (currently supported:
321 mp4|flv|ogg|webm|mkv)
322 -k, --keep-video keeps the video file on disk after the
323 post-processing; the video is erased by
324 default
325 --no-post-overwrites do not overwrite post-processed files; the
326 post-processed files are overwritten by
327 default
328 --embed-subs embed subtitles in the video (only for mp4
329 videos)
330 --embed-thumbnail embed thumbnail in the audio as cover art
331 --add-metadata write metadata to the video file
332 --xattrs write metadata to the video file's xattrs
333 (using dublin core and xdg standards)
334 --prefer-avconv Prefer avconv over ffmpeg for running the
335 postprocessors (default)
336 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
337 postprocessors
338 --exec CMD Execute a command on the file after
339 downloading, similar to find's -exec
340 syntax. Example: --exec 'adb push {}
341 /sdcard/Music/ && rm {}'
342
343 CONFIGURATION
344 =============
345
346 You can configure youtube-dl by placing default arguments (such as
347 --extract-audio --no-mtime to always extract the audio and not copy the
348 mtime) into /etc/youtube-dl.conf and/or ~/.config/youtube-dl/config. On
349 Windows, the configuration file locations are
350 %APPDATA%\youtube-dl\config.txt and C:\Users\<Yourname>\youtube-dl.conf.
351
352 OUTPUT TEMPLATE
353 ===============
354
355 The -o option allows users to indicate a template for the output file
356 names. The basic usage is not to set any template arguments when
357 downloading a single file, like in
358 youtube-dl -o funny_video.flv "http://some/video". However, it may
359 contain special sequences that will be replaced when downloading each
360 video. The special sequences have the format %(NAME)s. To clarify, that
361 is a percent symbol followed by a name in parenthesis, followed by a
362 lowercase S. Allowed names are:
363
364 - id: The sequence will be replaced by the video identifier.
365 - url: The sequence will be replaced by the video URL.
366 - uploader: The sequence will be replaced by the nickname of the
367 person who uploaded the video.
368 - upload_date: The sequence will be replaced by the upload date in
369 YYYYMMDD format.
370 - title: The sequence will be replaced by the video title.
371 - ext: The sequence will be replaced by the appropriate extension
372 (like flv or mp4).
373 - epoch: The sequence will be replaced by the Unix epoch when creating
374 the file.
375 - autonumber: The sequence will be replaced by a five-digit number
376 that will be increased with each download, starting at zero.
377 - playlist: The name or the id of the playlist that contains the
378 video.
379 - playlist_index: The index of the video in the playlist, a five-digit
380 number.
381
382 The current default template is %(title)s-%(id)s.%(ext)s.
383
384 In some cases, you don't want special characters such as äø­, spaces, or
385 &, such as when transferring the downloaded filename to a Windows system
386 or the filename through an 8bit-unsafe channel. In these cases, add the
387 --restrict-filenames flag to get a shorter title:
388
389 ``` {.bash}
390 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
391 youtube-dl test video ''_Ƥā†­š•.mp4 # All kinds of weird characters
392 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
393 youtube-dl_test_video_.mp4 # A simple file name
394 ```
395
396 VIDEO SELECTION
397 ===============
398
399 Videos can be filtered by their upload date using the options --date,
400 --datebefore or --dateafter, they accept dates in two formats:
401
402 - Absolute dates: Dates in the format YYYYMMDD.
403 - Relative dates: Dates in the format
404 (now|today)[+-][0-9](day|week|month|year)(s)?
405
406 Examples:
407
408 ``` {.bash}
409 # Download only the videos uploaded in the last 6 months
410 $ youtube-dl --dateafter now-6months
411
412 # Download only the videos uploaded on January 1, 1970
413 $ youtube-dl --date 19700101
414
415 $ # will only download the videos uploaded in the 200x decade
416 $ youtube-dl --dateafter 20000101 --datebefore 20091231
417 ```
418
419 FAQ
420 ===
421
422 How do I update youtube-dl?
423
424 If you've followed our manual installation instructions, you can simply
425 run youtube-dl -U (or, on Linux, sudo youtube-dl -U).
426
427 If you have used pip, a simple sudo pip install -U youtube-dl is
428 sufficient to update.
429
430 If you have installed youtube-dl using a package manager like apt-get or
431 yum, use the standard system update mechanism to update. Note that
432 distribution packages are often outdated. As a rule of thumb, youtube-dl
433 releases at least once a month, and often weekly or even daily. Simply
434 go to http://yt-dl.org/ to find out the current version. Unfortunately,
435 there is nothing we youtube-dl developers can do if your distributions
436 serves a really outdated version. You can (and should) complain to your
437 distribution in their bugtracker or support forum.
438
439 As a last resort, you can also uninstall the version installed by your
440 package manager and follow our manual installation instructions. For
441 that, remove the distribution's package, with a line like
442
443 sudo apt-get remove -y youtube-dl
444
445 Afterwards, simply follow our manual installation instructions:
446
447 sudo wget https://yt-dl.org/latest/youtube-dl -O /usr/local/bin/youtube-dl
448 sudo chmod a+x /usr/local/bin/youtube-dl
449 hash -r
450
451 Again, from then on you'll be able to update with sudo youtube-dl -U.
452
453 I'm getting an error Unable to extract OpenGraph title on YouTube playlists
454
455 YouTube changed their playlist format in March 2014 and later on, so
456 you'll need at least youtube-dl 2014.07.25 to download all YouTube
457 videos.
458
459 If you have installed youtube-dl with a package manager, pip, setup.py
460 or a tarball, please use that to update. Note that Ubuntu packages do
461 not seem to get updated anymore. Since we are not affiliated with
462 Ubuntu, there is little we can do. Feel free to report bugs to the
463 Ubuntu packaging guys - all they have to do is update the package to a
464 somewhat recent version. See above for a way to update.
465
466 Do I always have to pass in --max-quality FORMAT, or -citw?
467
468 By default, youtube-dl intends to have the best options (incidentally,
469 if you have a convincing case that these should be different, please
470 file an issue where you explain that). Therefore, it is unnecessary and
471 sometimes harmful to copy long option strings from webpages. In
472 particular, --max-quality limits the video quality (so if you want the
473 best quality, do NOT pass it in), and the only option out of -citw that
474 is regularly useful is -i.
475
476 Can you please put the -b option back?
477
478 Most people asking this question are not aware that youtube-dl now
479 defaults to downloading the highest available quality as reported by
480 YouTube, which will be 1080p or 720p in some cases, so you no longer
481 need the -b option. For some specific videos, maybe YouTube does not
482 report them to be available in a specific high quality format you're
483 interested in. In that case, simply request it with the -f option and
484 youtube-dl will try to download it.
485
486 I get HTTP error 402 when trying to download a video. What's this?
487
488 Apparently YouTube requires you to pass a CAPTCHA test if you download
489 too much. We're considering to provide a way to let you solve the
490 CAPTCHA, but at the moment, your best course of action is pointing a
491 webbrowser to the youtube URL, solving the CAPTCHA, and restart
492 youtube-dl.
493
494 I have downloaded a video but how can I play it?
495
496 Once the video is fully downloaded, use any video player, such as vlc or
497 mplayer.
498
499 The links provided by youtube-dl -g are not working anymore
500
501 The URLs youtube-dl outputs require the downloader to have the correct
502 cookies. Use the --cookies option to write the required cookies into a
503 file, and advise your downloader to read cookies from that file. Some
504 sites also require a common user agent to be used, use --dump-user-agent
505 to see the one in use by youtube-dl.
506
507 ERROR: no fmt_url_map or conn information found in video info
508
509 youtube has switched to a new video info format in July 2011 which is
510 not supported by old versions of youtube-dl. You can update youtube-dl
511 with sudo youtube-dl --update.
512
513 ERROR: unable to download video
514
515 youtube requires an additional signature since September 2012 which is
516 not supported by old versions of youtube-dl. You can update youtube-dl
517 with sudo youtube-dl --update.
518
519 SyntaxError: Non-ASCII character
520
521 The error
522
523 File "youtube-dl", line 2
524 SyntaxError: Non-ASCII character '\x93' ...
525
526 means you're using an outdated version of Python. Please update to
527 Python 2.6 or 2.7.
528
529 What is this binary file? Where has the code gone?
530
531 Since June 2012 (#342) youtube-dl is packed as an executable zipfile,
532 simply unzip it (might need renaming to youtube-dl.zip first on some
533 systems) or clone the git repository, as laid out above. If you modify
534 the code, you can run it by executing the __main__.py file. To recompile
535 the executable, run make youtube-dl.
536
537 The exe throws a Runtime error from Visual C++
538
539 To run the exe you need to install first the Microsoft Visual C++ 2008
540 Redistributable Package.
541
542 DEVELOPER INSTRUCTIONS
543 ======================
544
545 Most users do not need to build youtube-dl and can download the builds
546 or get them from their distribution.
547
548 To run youtube-dl as a developer, you don't need to build anything
549 either. Simply execute
550
551 python -m youtube_dl
552
553 To run the test, simply invoke your favorite test runner, or execute a
554 test file directly; any of the following work:
555
556 python -m unittest discover
557 python test/test_download.py
558 nosetests
559
560 If you want to create a build of youtube-dl yourself, you'll need
561
562 - python
563 - make
564 - pandoc
565 - zip
566 - nosetests
567
568 Adding support for a new site
569
570 If you want to add support for a new site, you can follow this quick
571 list (assuming your service is called yourextractor):
572
573 1. Fork this repository
574 2. Check out the source code with
575 git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
576 3. Start a new git branch with
577 cd youtube-dl; git checkout -b yourextractor
578 4. Start with this simple template and save it to
579 youtube_dl/extractor/yourextractor.py:
580
581 ``` {.python}
582 # coding: utf-8
583 from __future__ import unicode_literals
584
585 from .common import InfoExtractor
586
587
588 class YourExtractorIE(InfoExtractor):
589 _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
590 _TEST = {
591 'url': 'http://yourextractor.com/watch/42',
592 'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
593 'info_dict': {
594 'id': '42',
595 'ext': 'mp4',
596 'title': 'Video title goes here',
597 'thumbnail': 're:^https?://.*\.jpg$',
598 # TODO more properties, either as:
599 # * A value
600 # * MD5 checksum; start the string with md5:
601 # * A regular expression; start the string with re:
602 # * Any Python type (for example int or float)
603 }
604 }
605
606 def _real_extract(self, url):
607 video_id = self._match_id(url)
608
609 # TODO more code goes here, for example ...
610 webpage = self._download_webpage(url, video_id)
611 title = self._html_search_regex(r'<h1>(.*?)</h1>', webpage, 'title')
612
613 return {
614 'id': video_id,
615 'title': title,
616 # TODO more properties (see youtube_dl/extractor/common.py)
617 }
618 ```
619
620 5. Add an import in youtube_dl/extractor/__init__.py.
621 6. Run python test/test_download.py TestDownload.test_YourExtractor.
622 This should fail at first, but you can continually re-run it until
623 you're done. If you decide to add more than one test, then rename
624 _TEST to _TESTS and make it into a list of dictionaries. The tests
625 will be then be named TestDownload.test_YourExtractor,
626 TestDownload.test_YourExtractor_1,
627 TestDownload.test_YourExtractor_2, etc.
628 7. Have a look at youtube_dl/common/extractor/common.py for possible
629 helper methods and a detailed description of what your extractor
630 should return. Add tests and code for as many as you want.
631 8. If you can, check the code with pyflakes (a good idea) and pep8
632 (optional, ignore E501).
633 9. When the tests pass, add the new files and commit them and push the
634 result, like this:
635
636 $ git add youtube_dl/extractor/__init__.py
637 $ git add youtube_dl/extractor/yourextractor.py
638 $ git commit -m '[yourextractor] Add new extractor'
639 $ git push origin yourextractor
640
641 10. Finally, create a pull request. We'll then review and merge it.
642
643 In any case, thank you very much for your contributions!
644
645 EMBEDDING YOUTUBE-DL
646 ====================
647
648 youtube-dl makes the best effort to be a good command-line program, and
649 thus should be callable from any programming language. If you encounter
650 any problems parsing its output, feel free to create a report.
651
652 From a Python program, you can embed youtube-dl in a more powerful
653 fashion, like this:
654
655 import youtube_dl
656
657 ydl_opts = {}
658 with youtube_dl.YoutubeDL(ydl_opts) as ydl:
659 ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc'])
660
661 Most likely, you'll want to use various options. For a list of what can
662 be done, have a look at youtube_dl/YoutubeDL.py. For a start, if you
663 want to intercept youtube-dl's output, set a logger object.
664
665 BUGS
666 ====
667
668 Bugs and suggestions should be reported at:
669 https://github.com/rg3/youtube-dl/issues . Unless you were prompted so
670 or there is another pertinent reason (e.g. GitHub fails to accept the
671 bug report), please do not send bug reports via personal email.
672
673 Please include the full output of the command when run with --verbose.
674 The output (including the first lines) contain important debugging
675 information. Issues without the full output are often not reproducible
676 and therefore do not get solved in short order, if ever.
677
678 For discussions, join us in the irc channel #youtube-dl on freenode.
679
680 When you submit a request, please re-read it once to avoid a couple of
681 mistakes (you can and should use this as a checklist):
682
683 Is the description of the issue itself sufficient?
684
685 We often get issue reports that we cannot really decipher. While in most
686 cases we eventually get the required information after asking back
687 multiple times, this poses an unnecessary drain on our resources. Many
688 contributors, including myself, are also not native speakers, so we may
689 misread some parts.
690
691 So please elaborate on what feature you are requesting, or what bug you
692 want to be fixed. Make sure that it's obvious
693
694 - What the problem is
695 - How it could be fixed
696 - How your proposed solution would look like
697
698 If your report is shorter than two lines, it is almost certainly missing
699 some of these, which makes it hard for us to respond to it. We're often
700 too polite to close the issue outright, but the missing info makes
701 misinterpretation likely. As a commiter myself, I often get frustrated
702 by these issues, since the only possible way for me to move forward on
703 them is to ask for clarification over and over.
704
705 For bug reports, this means that your report should contain the complete
706 output of youtube-dl when called with the -v flag. The error message you
707 get for (most) bugs even says so, but you would not believe how many of
708 our bug reports do not contain this information.
709
710 Site support requests must contain an example URL. An example URL is a
711 URL you might want to download, like
712 http://www.youtube.com/watch?v=BaW_jenozKc . There should be an obvious
713 video present. Except under very special circumstances, the main page of
714 a video service (e.g. http://www.youtube.com/ ) is not an example URL.
715
716 Are you using the latest version?
717
718 Before reporting any issue, type youtube-dl -U. This should report that
719 you're up-to-date. About 20% of the reports we receive are already
720 fixed, but people are using outdated versions. This goes for feature
721 requests as well.
722
723 Is the issue already documented?
724
725 Make sure that someone has not already opened the issue you're trying to
726 open. Search at the top of the window or at
727 https://github.com/rg3/youtube-dl/search?type=Issues . If there is an
728 issue, feel free to write something along the lines of "This affects me
729 as well, with version 2015.01.01. Here is some more information on the
730 issue: ...". While some issues may be old, a new post into them often
731 spurs rapid activity.
732
733 Why are existing options not enough?
734
735 Before requesting a new feature, please have a quick peek at the list of
736 supported options. Many feature requests are for features that actually
737 exist already! Please, absolutely do show off your work in the issue
738 report and detail how the existing similar options do not solve your
739 problem.
740
741 Is there enough context in your bug report?
742
743 People want to solve problems, and often think they do us a favor by
744 breaking down their larger problems (e.g. wanting to skip already
745 downloaded files) to a specific request (e.g. requesting us to look
746 whether the file exists before downloading the info page). However, what
747 often happens is that they break down the problem into two steps: One
748 simple, and one impossible (or extremely complicated one).
749
750 We are then presented with a very complicated request when the original
751 problem could be solved far easier, e.g. by recording the downloaded
752 video IDs in a separate file. To avoid this, you must include the
753 greater context where it is non-obvious. In particular, every feature
754 request that does not consist of adding support for a new site should
755 contain a use case scenario that explains in what situation the missing
756 feature would be useful.
757
758 Does the issue involve one problem, and one problem only?
759
760 Some of our users seem to think there is a limit of issues they can or
761 should open. There is no limit of issues they can or should open. While
762 it may seem appealing to be able to dump all your issues into one
763 ticket, that means that someone who solves one of your issues cannot
764 mark the issue as closed. Typically, reporting a bunch of issues leads
765 to the ticket lingering since nobody wants to attack that behemoth,
766 until someone mercifully splits the issue into multiple ones.
767
768 In particular, every site support request issue should only pertain to
769 services at one site (generally under a common domain, but always using
770 the same backend technology). Do not request support for vimeo user
771 videos, Whitehouse podcasts, and Google Plus pages in the same issue.
772 Also, make sure that you don't post bug reports alongside feature
773 requests. As a rule of thumb, a feature request does not include outputs
774 of youtube-dl that are not immediately related to the feature at hand.
775 Do not post reports of a network error alongside the request for a new
776 video service.
777
778 Is anyone going to need the feature?
779
780 Only post features that you (or an incapicated friend you can personally
781 talk to) require. Do not post features because they seem like a good
782 idea. If they are really useful, they will be requested by someone who
783 requires them.
784
785 Is your question about youtube-dl?
786
787 It may sound strange, but some bug reports we receive are completely
788 unrelated to youtube-dl and relate to a different or even the reporter's
789 own application. Please make sure that you are actually using
790 youtube-dl. If you are using a UI for youtube-dl, report the bug to the
791 maintainer of the actual application providing the UI. On the other
792 hand, if your UI for youtube-dl fails in some way you believe is related
793 to youtube-dl, by all means, go ahead and report the bug.
794
795 COPYRIGHT
796 =========
797
798 youtube-dl is released into the public domain by the copyright holders.
799
800 This README file was originally written by Daniel Bolton
801 (https://github.com/dbbolton) and is likewise released into the public
802 domain.
803