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