1YOUTUBE-DL(1)                                                    YOUTUBE-DL(1)
2
3
4

NAME

6       youtube-dl - download videos from youtube.com or other video platforms
7

SYNOPSIS

9       youtube-dl [OPTIONS] URL [URL...]
10

DESCRIPTION

12       youtube-dl   is   a   command-line  program  to  download  videos  from
13       YouTube.com and a few more sites.  It requires the Python  interpreter,
14       version  2.6, 2.7, or 3.2+, and it is not platform specific.  It should
15       work on your Unix box, on Windows or on macOS.  It is released  to  the
16       public domain, which means you can modify it, redistribute it or use it
17       however you like.
18

OPTIONS

20       -h, --help
21              Print this help text and exit
22
23       --version
24              Print program version and exit
25
26       -U, --update
27              Update this program to latest version.  Make sure that you  have
28              sufficient permissions (run with sudo if needed)
29
30       -i, --ignore-errors
31              Continue  on  download  errors,  for example to skip unavailable
32              videos in a playlist
33
34       --abort-on-error
35              Abort downloading of further videos (in the playlist or the com‐
36              mand line) if an error occurs
37
38       --dump-user-agent
39              Display the current browser identification
40
41       --list-extractors
42              List all supported extractors
43
44       --extractor-descriptions
45              Output descriptions of all supported extractors
46
47       --force-generic-extractor
48              Force extraction to use the generic extractor
49
50       --default-search PREFIX
51              Use  this prefix for unqualified URLs.  For example "gvsearch2:"
52              downloads two videos from google videos  for  youtube-dl  "large
53              apple".   Use  the  value  "auto"  to let youtube-dl guess ("au‐
54              to_warning" to emit a  warning  when  guessing).   "error"  just
55              throws an error.  The default value "fixup_error" repairs broken
56              URLs, but emits an error if this  is  not  possible  instead  of
57              searching.
58
59       --ignore-config
60              Do  not read configuration files.  When given in the global con‐
61              figuration file /etc/youtube-dl.conf: Do not read the user  con‐
62              figuration     in    ~/.config/youtube-    dl/config    (%APPDA‐
63              TA%/youtube-dl/config.txt on Windows)
64
65       --config-location PATH
66              Location of the configuration file; either the path to the  con‐
67              fig or its containing directory.
68
69       --flat-playlist
70              Do not extract the videos of a playlist, only list them.
71
72       --mark-watched
73              Mark videos watched (YouTube only)
74
75       --no-mark-watched
76              Do not mark videos watched (YouTube only)
77
78       --no-color
79              Do not emit color codes in output
80
81   Network Options:
82       --proxy URL
83              Use  the  specified  HTTP/HTTPS/SOCKS  proxy.   To  enable SOCKS
84              proxy,    specify    a    proper    scheme.      For     example
85              socks5://127.0.0.1:1080/.   Pass in an empty string (--proxy "")
86              for direct connection
87
88       --socket-timeout SECONDS
89              Time to wait before giving up, in seconds
90
91       --source-address IP
92              Client-side IP address to bind to
93
94       -4, --force-ipv4
95              Make all connections via IPv4
96
97       -6, --force-ipv6
98              Make all connections via IPv6
99
100   Geo Restriction:
101       --geo-verification-proxy URL
102              Use this proxy to verify the IP address for some  geo-restricted
103              sites.   The default proxy specified by --proxy (or none, if the
104              option is not present) is used for the actual downloading.
105
106       --geo-bypass
107              Bypass geographic restriction via  faking  X-Forwarded-For  HTTP
108              header
109
110       --no-geo-bypass
111              Do  not bypass geographic restriction via faking X-Forwarded-For
112              HTTP header
113
114       --geo-bypass-country CODE
115              Force bypass geographic  restriction  with  explicitly  provided
116              two-letter ISO 3166-2 country code
117
118       --geo-bypass-ip-block IP_BLOCK
119              Force  bypass geographic restriction with explicitly provided IP
120              block in CIDR notation
121
122   Video Selection:
123       --playlist-start NUMBER
124              Playlist video to start at (default is 1)
125
126       --playlist-end NUMBER
127              Playlist video to end at (default is last)
128
129       --playlist-items ITEM_SPEC
130              Playlist video items to download.  Specify indices of the videos
131              in  the  playlist  separated  by  commas like: "--playlist-items
132              1,2,5,8" if you want to download videos indexed 1, 2,  5,  8  in
133              the   playlist.    You   can  specify  range:  "--playlist-items
134              1-3,7,10-13", it will download the videos at index 1, 2,  3,  7,
135              10, 11, 12 and 13.
136
137       --match-title REGEX
138              Download only matching titles (regex or caseless sub-string)
139
140       --reject-title REGEX
141              Skip download for matching titles (regex or caseless sub-string)
142
143       --max-downloads NUMBER
144              Abort after downloading NUMBER files
145
146       --min-filesize SIZE
147              Do  not  download  any  videos  smaller  than SIZE (e.g.  50k or
148              44.6m)
149
150       --max-filesize SIZE
151              Do not download any videos larger than SIZE (e.g.  50k or 44.6m)
152
153       --date DATE
154              Download only videos uploaded in this date
155
156       --datebefore DATE
157              Download only videos uploaded on or before this date (i.e.   in‐
158              clusive)
159
160       --dateafter DATE
161              Download  only  videos uploaded on or after this date (i.e.  in‐
162              clusive)
163
164       --min-views COUNT
165              Do not download any videos with less than COUNT views
166
167       --max-views COUNT
168              Do not download any videos with more than COUNT views
169
170       --match-filter FILTER
171              Generic video filter.  Specify any key  (see  the  "OUTPUT  TEM‐
172              PLATE"  for  a  list  of  available keys) to match if the key is
173              present, !key to check if the key is not present, key  >  NUMBER
174              (like "comment_count > 12", also works with >=, <, <=, !=, =) to
175              compare against a number, key  =  'LITERAL'  (like  "uploader  =
176              'Mike  Smith'",  also  works  with !=) to match against a string
177              literal and & to require multiple matches.  Values which are not
178              known  are excluded unless you put a question mark (?) after the
179              operator.  For example, to only  match  videos  that  have  been
180              liked  more  than  100 times and disliked less than 50 times (or
181              the dislike functionality is not available  at  the  given  ser‐
182              vice),  but  who  also  have  a  description, use --match-filter
183              "like_count > 100 & dislike_count <?  50 & description" .
184
185       --no-playlist
186              Download only the video, if the URL refers  to  a  video  and  a
187              playlist.
188
189       --yes-playlist
190              Download  the  playlist,  if  the  URL  refers  to a video and a
191              playlist.
192
193       --age-limit YEARS
194              Download only videos suitable for the given age
195
196       --download-archive FILE
197              Download only videos not listed in the archive file.  Record the
198              IDs of all downloaded videos in it.
199
200       --include-ads
201              Download advertisements as well (experimental)
202
203   Download Options:
204       -r, --limit-rate RATE
205              Maximum download rate in bytes per second (e.g.  50K or 4.2M)
206
207       -R, --retries RETRIES
208              Number of retries (default is 10), or "infinite".
209
210       --fragment-retries RETRIES
211              Number  of retries for a fragment (default is 10), or "infinite"
212              (DASH, hlsnative and ISM)
213
214       --skip-unavailable-fragments
215              Skip unavailable fragments (DASH, hlsnative and ISM)
216
217       --abort-on-unavailable-fragment
218              Abort downloading when some fragment is not available
219
220       --keep-fragments
221              Keep downloaded fragments on disk after downloading is finished;
222              fragments are erased by default
223
224       --buffer-size SIZE
225              Size of download buffer (e.g.  1024 or 16K) (default is 1024)
226
227       --no-resize-buffer
228              Do  not  automatically  adjust the buffer size.  By default, the
229              buffer size is automatically resized from an  initial  value  of
230              SIZE.
231
232       --http-chunk-size SIZE
233              Size of a chunk for chunk-based HTTP downloading (e.g.  10485760
234              or 10M) (default is disabled).   May  be  useful  for  bypassing
235              bandwidth throttling imposed by a webserver (experimental)
236
237       --playlist-reverse
238              Download playlist videos in reverse order
239
240       --playlist-random
241              Download playlist videos in random order
242
243       --xattr-set-filesize
244              Set file xattribute ytdl.filesize with expected file size
245
246       --hls-prefer-native
247              Use the native HLS downloader instead of ffmpeg
248
249       --hls-prefer-ffmpeg
250              Use ffmpeg instead of the native HLS downloader
251
252       --hls-use-mpegts
253              Use  the  mpegts  container for HLS videos, allowing to play the
254              video while downloading (some players may not be  able  to  play
255              it)
256
257       --external-downloader COMMAND
258              Use  the  specified  external  downloader.   Currently  supports
259              aria2c,avconv,axel,curl,ffmpeg,httpie,wget
260
261       --external-downloader-args ARGS
262              Give these arguments to the external downloader
263
264   Filesystem Options:
265       -a, --batch-file FILE
266              File containing URLs to download ('-' for stdin),  one  URL  per
267              line.   Lines  starting  with  '#', ';' or ']' are considered as
268              comments and ignored.
269
270       --id   Use only video ID in file name
271
272       -o, --output TEMPLATE
273              Output filename template, see the "OUTPUT TEMPLATE" for all  the
274              info
275
276       --autonumber-start NUMBER
277              Specify the start value for %(autonumber)s (default is 1)
278
279       --restrict-filenames
280              Restrict  filenames  to only ASCII characters, and avoid "&" and
281              spaces in filenames
282
283       -w, --no-overwrites
284              Do not overwrite files
285
286       -c, --continue
287              Force  resume  of  partially  downloaded  files.   By   default,
288              youtube-dl will resume downloads if possible.
289
290       --no-continue
291              Do  not  resume  partially downloaded files (restart from begin‐
292              ning)
293
294       --no-part
295              Do not use .part files - write directly into output file
296
297       --no-mtime
298              Do not use the Last-modified header to set the file modification
299              time
300
301       --write-description
302              Write video description to a .description file
303
304       --write-info-json
305              Write video metadata to a .info.json file
306
307       --write-annotations
308              Write video annotations to a .annotations.xml file
309
310       --load-info-json FILE
311              JSON  file  containing  the  video information (created with the
312              "--write-info-json" option)
313
314       --cookies FILE
315              File to read cookies from and dump cookie jar in
316
317       --cache-dir DIR
318              Location in the filesystem where youtube-dl can store some down‐
319              loaded       information      permanently.       By      default
320              $XDG_CACHE_HOME/youtube-dl or ~/.cache/youtube-dl .  At the  mo‐
321              ment, only YouTube player files (for videos with obfuscated sig‐
322              natures) are cached, but that may change.
323
324       --no-cache-dir
325              Disable filesystem caching
326
327       --rm-cache-dir
328              Delete all filesystem cache files
329
330   Thumbnail images:
331       --write-thumbnail
332              Write thumbnail image to disk
333
334       --write-all-thumbnails
335              Write all thumbnail image formats to disk
336
337       --list-thumbnails
338              Simulate and list all available thumbnail formats
339
340   Verbosity / Simulation Options:
341       -q, --quiet
342              Activate quiet mode
343
344       --no-warnings
345              Ignore warnings
346
347       -s, --simulate
348              Do not download the video and do not write anything to disk
349
350       --skip-download
351              Do not download the video
352
353       -g, --get-url
354              Simulate, quiet but print URL
355
356       -e, --get-title
357              Simulate, quiet but print title
358
359       --get-id
360              Simulate, quiet but print id
361
362       --get-thumbnail
363              Simulate, quiet but print thumbnail URL
364
365       --get-description
366              Simulate, quiet but print video description
367
368       --get-duration
369              Simulate, quiet but print video length
370
371       --get-filename
372              Simulate, quiet but print output filename
373
374       --get-format
375              Simulate, quiet but print output format
376
377       -j, --dump-json
378              Simulate, quiet but print JSON  information.   See  the  "OUTPUT
379              TEMPLATE" for a description of available keys.
380
381       -J, --dump-single-json
382              Simulate, quiet but print JSON information for each command-line
383              argument.  If the URL refers  to  a  playlist,  dump  the  whole
384              playlist information in a single line.
385
386       --print-json
387              Be quiet and print the video information as JSON (video is still
388              being downloaded).
389
390       --newline
391              Output progress bar as new lines
392
393       --no-progress
394              Do not print progress bar
395
396       --console-title
397              Display progress in console titlebar
398
399       -v, --verbose
400              Print various debugging information
401
402       --dump-pages
403              Print downloaded pages encoded using base64  to  debug  problems
404              (very verbose)
405
406       --write-pages
407              Write  downloaded intermediary pages to files in the current di‐
408              rectory to debug problems
409
410       --print-traffic
411              Display sent and read HTTP traffic
412
413       -C, --call-home
414              Contact the youtube-dl server for debugging
415
416       --no-call-home
417              Do NOT contact the youtube-dl server for debugging
418
419   Workarounds:
420       --encoding ENCODING
421              Force the specified encoding (experimental)
422
423       --no-check-certificate
424              Suppress HTTPS certificate validation
425
426       --prefer-insecure
427              Use an unencrypted connection to retrieve information about  the
428              video.  (Currently supported only for YouTube)
429
430       --user-agent UA
431              Specify a custom user agent
432
433       --referer URL
434              Specify  a custom referer, use if the video access is restricted
435              to one domain
436
437       --add-header FIELD:VALUE
438              Specify a custom HTTP header and its value, separated by a colon
439              ':'.  You can use this option multiple times
440
441       --bidi-workaround
442              Work around terminals that lack bidirectional text support.  Re‐
443              quires bidiv or fribidi executable in PATH
444
445       --sleep-interval SECONDS
446              Number of seconds to sleep before each download when used  alone
447              or  a  lower  bound  of a range for randomized sleep before each
448              download (minimum possible number of seconds to sleep) when used
449              along with --max-sleep-interval.
450
451       --max-sleep-interval SECONDS
452              Upper bound of a range for randomized sleep before each download
453              (maximum possible number of seconds to  sleep).   Must  only  be
454              used along with --min-sleep-interval.
455
456   Video Format Options:
457       -f, --format FORMAT
458              Video format code, see the "FORMAT SELECTION" for all the info
459
460       --all-formats
461              Download all available video formats
462
463       --prefer-free-formats
464              Prefer free video formats unless a specific one is requested
465
466       -F, --list-formats
467              List all available formats of requested videos
468
469       --youtube-skip-dash-manifest
470              Do  not  download the DASH manifests and related data on YouTube
471              videos
472
473       --merge-output-format FORMAT
474              If a merge is required (e.g.   bestvideo+bestaudio),  output  to
475              given  container  format.  One of mkv, mp4, ogg, webm, flv.  Ig‐
476              nored if no merge is required
477
478   Subtitle Options:
479       --write-sub
480              Write subtitle file
481
482       --write-auto-sub
483              Write automatically generated subtitle file (YouTube only)
484
485       --all-subs
486              Download all the available subtitles of the video
487
488       --list-subs
489              List all available subtitles for the video
490
491       --sub-format FORMAT
492              Subtitle format, accepts formats preference, for example:  "srt"
493              or "ass/srt/best"
494
495       --sub-lang LANGS
496              Languages  of  the subtitles to download (optional) separated by
497              commas, use --list- subs for available language tags
498
499   Authentication Options:
500       -u, --username USERNAME
501              Login with this account ID
502
503       -p, --password PASSWORD
504              Account password.  If this option is left out,  youtube-dl  will
505              ask interactively.
506
507       -2, --twofactor TWOFACTOR
508              Two-factor authentication code
509
510       -n, --netrc
511              Use .netrc authentication data
512
513       --video-password PASSWORD
514              Video password (vimeo, smotri, youku)
515
516   Adobe Pass Options:
517       --ap-mso MSO
518              Adobe  Pass  multiple-system  operator (TV provider) identifier,
519              use --ap-list-mso for a list of available MSOs
520
521       --ap-username USERNAME
522              Multiple-system operator account login
523
524       --ap-password PASSWORD
525              Multiple-system operator account password.  If  this  option  is
526              left out, youtube-dl will ask interactively.
527
528       --ap-list-mso
529              List all supported multiple-system operators
530
531   Post-processing Options:
532       -x, --extract-audio
533              Convert  video files to audio-only files (requires ffmpeg or av‐
534              conv and ffprobe or avprobe)
535
536       --audio-format FORMAT
537              Specify audio  format:  "best",  "aac",  "flac",  "mp3",  "m4a",
538              "opus", "vorbis", or "wav"; "best" by default; No effect without
539              -x
540
541       --audio-quality QUALITY
542              Specify ffmpeg/avconv audio quality, insert a  value  between  0
543              (better)  and  9 (worse) for VBR or a specific bitrate like 128K
544              (default 5)
545
546       --recode-video FORMAT
547              Encode the video to another format if necessary (currently  sup‐
548              ported: mp4|flv|ogg|webm|mkv|avi)
549
550       --postprocessor-args ARGS
551              Give these arguments to the postprocessor
552
553       -k, --keep-video
554              Keep  the  video  file  on  disk after the post- processing; the
555              video is erased by default
556
557       --no-post-overwrites
558              Do not overwrite post-processed files; the post-processed  files
559              are overwritten by default
560
561       --embed-subs
562              Embed subtitles in the video (only for mp4, webm and mkv videos)
563
564       --embed-thumbnail
565              Embed thumbnail in the audio as cover art
566
567       --add-metadata
568              Write metadata to the video file
569
570       --metadata-from-title FORMAT
571              Parse  additional  metadata  like  song  title / artist from the
572              video title.  The format syntax is the same as --output.   Regu‐
573              lar  expression with named capture groups may also be used.  The
574              parsed parameters replace existing values.   Example:  --metada‐
575              ta-from-  title  "%(artist)s  -  %(title)s" matches a title like
576              "Coldplay - Paradise".  Example  (regex):  --metadata-from-title
577              "(?P.+?) - (?P
578              .+)"
579
580       --xattrs
581              Write metadata to the video file's xattrs (using dublin core and
582              xdg standards)
583
584       --fixup POLICY
585              Automatically correct known faults of the file.   One  of  never
586              (do  nothing),  warn  (only emit a warning), detect_or_warn (the
587              default; fix file if we can, warn otherwise)
588
589       --prefer-avconv
590              Prefer avconv over ffmpeg for running the postprocessors
591
592       --prefer-ffmpeg
593              Prefer ffmpeg over avconv for running  the  postprocessors  (de‐
594              fault)
595
596       --ffmpeg-location PATH
597              Location of the ffmpeg/avconv binary; either the path to the bi‐
598              nary or its containing directory.
599
600       --exec CMD
601              Execute a command on the  file  after  downloading,  similar  to
602              find's  -exec  syntax.  Example: --exec 'adb push {} /sdcard/Mu‐
603              sic/ && rm {}'
604
605       --convert-subs FORMAT
606              Convert the subtitles  to  other  format  (currently  supported:
607              srt|ass|vtt|lrc)
608

CONFIGURATION

610       You  can configure youtube-dl by placing any supported command line op‐
611       tion to a configuration file.  On Linux and macOS, the system wide con‐
612       figuration  file  is  located at /etc/youtube-dl.conf and the user wide
613       configuration file at ~/.config/youtube-dl/config.  On Windows, the us‐
614       er  wide  configuration  file  locations  are %APPDATA%\youtube-dl\con‐
615       fig.txt or C:\Users\<user name>\youtube-dl.conf.  Note that by  default
616       configuration file may not exist so you may need to create it yourself.
617
618       For  example, with the following configuration file youtube-dl will al‐
619       ways extract the audio, not copy the mtime, use a proxy  and  save  all
620       videos under Movies directory in your home directory:
621
622              # Lines starting with # are comments
623
624              # Always extract audio
625              -x
626
627              # Do not copy the mtime
628              --no-mtime
629
630              # Use this proxy
631              --proxy 127.0.0.1:3128
632
633              # Save all videos under Movies directory in your home directory
634              -o ~/Movies/%(title)s.%(ext)s
635
636       Note  that  options in configuration file are just the same options aka
637       switches used in regular command line  calls  thus  there  must  be  no
638       whitespace after - or --, e.g.  -o or --proxy but not - o or -- proxy.
639
640       You  can  use  --ignore-config if you want to disable the configuration
641       file for a particular youtube-dl run.
642
643       You can also use --config-location if you want to use custom configura‐
644       tion file for a particular youtube-dl run.
645
646   Authentication with .netrc file
647       You  may  also  want to configure automatic credentials storage for ex‐
648       tractors that support authentication (by providing login  and  password
649       with  --username  and  --password)  in order not to pass credentials as
650       command line arguments on every youtube-dl execution and prevent track‐
651       ing plain text passwords in the shell command history.  You can achieve
652       this using a .netrc  file  (https://stackoverflow.com/tags/.netrc/info)
653       on  a  per  extractor basis.  For that you will need to create a .netrc
654       file in your $HOME and restrict permissions to read/write by only you:
655
656              touch $HOME/.netrc
657              chmod a-rwx,u+rw $HOME/.netrc
658
659       After that you can add credentials for an extractor  in  the  following
660       format, where extractor is the name of the extractor in lowercase:
661
662              machine <extractor> login <login> password <password>
663
664       For example:
665
666              machine youtube login myaccount@gmail.com password my_youtube_password
667              machine twitch login my_twitch_account_name password my_twitch_password
668
669       To activate authentication with the .netrc file you should pass --netrc
670       to youtube-dl or place it in the configuration file.
671
672       On Windows you may also need to setup the %HOME%  environment  variable
673       manually.  For example:
674
675              set HOME=%USERPROFILE%
676

OUTPUT TEMPLATE

678       The  -o  option allows users to indicate a template for the output file
679       names.
680
681       tl;dr: navigate me to examples.
682
683       The basic usage is not to set any template arguments when downloading a
684       single         file,         like         in         youtube-dl -o fun‐
685       ny_video.flv "https://some/video".  However, it may contain special se‐
686       quences that will be replaced when downloading each video.  The special
687       sequences may be formatted according to python string formatting opera‐
688       tions   (https://docs.python.org/2/library/stdtypes.html#string-format‐
689       ting).  For example, %(NAME)s or %(NAME)05d.  To  clarify,  that  is  a
690       percent  symbol  followed by a name in parentheses, followed by format‐
691       ting operations.  Allowed names along with sequence type are:
692
693       · id (string): Video identifier
694
695       · title (string): Video title
696
697       · url (string): Video URL
698
699       · ext (string): Video filename extension
700
701       · alt_title (string): A secondary title of the video
702
703       · display_id (string): An alternative identifier for the video
704
705       · uploader (string): Full name of the video uploader
706
707       · license (string): License name the video is licensed under
708
709       · creator (string): The creator of the video
710
711       · release_date (string): The date (YYYYMMDD) when  the  video  was  re‐
712         leased
713
714       · timestamp  (numeric):  UNIX  timestamp of the moment the video became
715         available
716
717       · upload_date (string): Video upload date (YYYYMMDD)
718
719       · uploader_id (string): Nickname or id of the video uploader
720
721       · channel (string): Full name of the channel the video is uploaded on
722
723       · channel_id (string): Id of the channel
724
725       · location (string): Physical location where the video was filmed
726
727       · duration (numeric): Length of the video in seconds
728
729       · view_count (numeric): How many users have watched the  video  on  the
730         platform
731
732       · like_count (numeric): Number of positive ratings of the video
733
734       · dislike_count (numeric): Number of negative ratings of the video
735
736       · repost_count (numeric): Number of reposts of the video
737
738       · average_rating  (numeric):  Average  rating  give by users, the scale
739         used depends on the webpage
740
741       · comment_count (numeric): Number of comments on the video
742
743       · age_limit (numeric): Age restriction for the video (years)
744
745       · is_live  (boolean):  Whether  this  video  is  a  live  stream  or  a
746         fixed-length video
747
748       · start_time  (numeric):  Time in seconds where the reproduction should
749         start, as specified in the URL
750
751       · end_time (numeric): Time in seconds  where  the  reproduction  should
752         end, as specified in the URL
753
754       · format (string): A human-readable description of the format
755
756       · format_id (string): Format code specified by --format
757
758       · format_note (string): Additional info about the format
759
760       · width (numeric): Width of the video
761
762       · height (numeric): Height of the video
763
764       · resolution (string): Textual description of width and height
765
766       · tbr (numeric): Average bitrate of audio and video in KBit/s
767
768       · abr (numeric): Average audio bitrate in KBit/s
769
770       · acodec (string): Name of the audio codec in use
771
772       · asr (numeric): Audio sampling rate in Hertz
773
774       · vbr (numeric): Average video bitrate in KBit/s
775
776       · fps (numeric): Frame rate
777
778       · vcodec (string): Name of the video codec in use
779
780       · container (string): Name of the container format
781
782       · filesize (numeric): The number of bytes, if known in advance
783
784       · filesize_approx (numeric): An estimate for the number of bytes
785
786       · protocol  (string):  The  protocol  that  will be used for the actual
787         download
788
789       · extractor (string): Name of the extractor
790
791       · extractor_key (string): Key name of the extractor
792
793       · epoch (numeric): Unix epoch when creating the file
794
795       · autonumber (numeric): Five-digit number that will be  increased  with
796         each download, starting at zero
797
798       · playlist (string): Name or id of the playlist that contains the video
799
800       · playlist_index  (numeric):  Index of the video in the playlist padded
801         with leading zeros according to the total length of the playlist
802
803       · playlist_id (string): Playlist identifier
804
805       · playlist_title (string): Playlist title
806
807       · playlist_uploader (string): Full name of the playlist uploader
808
809       · playlist_uploader_id (string): Nickname or id of the playlist upload‐
810         er
811
812       Available  for  the  video that belongs to some logical chapter or sec‐
813       tion:
814
815       · chapter (string): Name or title of the chapter the video belongs to
816
817       · chapter_number (numeric): Number of the chapter the video belongs to
818
819       · chapter_id (string): Id of the chapter the video belongs to
820
821       Available for the video that is an episode of some series or programme:
822
823       · series (string): Title of the series or programme the  video  episode
824         belongs to
825
826       · season (string): Title of the season the video episode belongs to
827
828       · season_number  (numeric):  Number of the season the video episode be‐
829         longs to
830
831       · season_id (string): Id of the season the video episode belongs to
832
833       · episode (string): Title of the video episode
834
835       · episode_number (numeric): Number of the video episode within a season
836
837       · episode_id (string): Id of the video episode
838
839       Available for the media that is a track or a part of a music album:
840
841       · track (string): Title of the track
842
843       · track_number (numeric): Number of the track within an album or a disc
844
845       · track_id (string): Id of the track
846
847       · artist (string): Artist(s) of the track
848
849       · genre (string): Genre(s) of the track
850
851       · album (string): Title of the album the track belongs to
852
853       · album_type (string): Type of the album
854
855       · album_artist (string): List of all artists appeared on the album
856
857       · disc_number (numeric): Number of the disc or  other  physical  medium
858         the track belongs to
859
860       · release_year (numeric): Year (YYYY) when the album was released
861
862       Each aforementioned sequence when referenced in an output template will
863       be replaced by the actual value corresponding  to  the  sequence  name.
864       Note  that some of the sequences are not guaranteed to be present since
865       they depend on the metadata obtained by a particular  extractor.   Such
866       sequences will be replaced with NA.
867
868       For example for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title
869       youtube-dl test video and  id  BaW_jenozKcj,  this  will  result  in  a
870       youtube-dl test video-BaW_jenozKcj.mp4  file created in the current di‐
871       rectory.
872
873       For numeric sequences you can use numeric related formatting, for exam‐
874       ple,  %(view_count)05d  will  result in a string with view count padded
875       with zeros up to 5 characters, like in 00042.
876
877       Output templates can also contain  arbitrary  hierarchical  path,  e.g.
878       -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' which will re‐
879       sult in downloading each video in a  directory  corresponding  to  this
880       path template.  Any missing directory will be automatically created for
881       you.
882
883       To use percent literals in an output template use  %%.   To  output  to
884       stdout use -o -.
885
886       The current default template is %(title)s-%(id)s.%(ext)s.
887
888       In some cases, you don't want special characters such as 中, spaces, or
889       &, such as when transferring the downloaded filename to a Windows  sys‐
890       tem  or  the  filename through an 8bit-unsafe channel.  In these cases,
891       add the --restrict-filenames flag to get a shorter title:
892
893   Output template and Windows batch files
894       If you are using an output template inside a Windows  batch  file  then
895       you  must  escape  plain  percent  characters  (%) by doubling, so that
896       -o "%(title)s-%(id)s.%(ext)s"      should       become       -o "%%(ti‐
897       tle)s-%%(id)s.%%(ext)s".  However you should not touch %'s that are not
898       plain characters, e.g.  environment variables for expansion should stay
899       intact: -o "C:\%HOMEPATH%\Desktop\%%(title)s.%%(ext)s".
900
901   Output template examples
902       Note  that on Windows you may need to use double quotes instead of sin‐
903       gle.
904
905              $ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc
906              youtube-dl test video ''_ä↭𝕐.mp4    # All kinds of weird characters
907
908              $ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc --restrict-filenames
909              youtube-dl_test_video_.mp4          # A simple file name
910
911              # Download YouTube playlist videos in separate directory indexed by video order in a playlist
912              $ youtube-dl -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re
913
914              # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
915              $ youtube-dl -o '%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/user/TheLinuxFoundation/playlists
916
917              # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
918              $ youtube-dl -u user -p password -o '~/MyVideos/%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s' https://www.udemy.com/java-tutorial/
919
920              # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
921              $ youtube-dl -o "C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" https://videomore.ru/kino_v_detalayah/5_sezon/367617
922
923              # Stream the video being downloaded to stdout
924              $ youtube-dl -o - BaW_jenozKc
925

FORMAT SELECTION

927       By default youtube-dl tries to download  the  best  available  quality,
928       i.e.   if  you want the best quality you don't need to pass any special
929       options, youtube-dl will guess it for you by default.
930
931       But sometimes you may want to download in a different format, for exam‐
932       ple  when you are on a slow or intermittent connection.  The key mecha‐
933       nism for achieving this is so-called format selection  based  on  which
934       you can explicitly specify desired format, select formats based on some
935       criterion or criteria, setup precedence and much more.
936
937       The general syntax for format selection is --format FORMAT  or  shorter
938       -f FORMAT  where  FORMAT  is a selector expression, i.e.  an expression
939       that describes format or formats you would like to download.
940
941       tl;dr: navigate me to examples.
942
943       The simplest case is requesting a specific  format,  for  example  with
944       -f 22  you  can  download the format with format code equal to 22.  You
945       can get the list of available format codes for particular  video  using
946       --list-formats  or -F.  Note that these format codes are extractor spe‐
947       cific.
948
949       You can also use a file extension (currently 3gp, aac, flv,  m4a,  mp3,
950       mp4,  ogg, wav, webm are supported) to download the best quality format
951       of a particular file extension served as a single file,  e.g.   -f webm
952       will download the best quality format with the webm extension served as
953       a single file.
954
955       You can also use special names to select particular edge case formats:
956
957       · best: Select the best quality format represented  by  a  single  file
958         with video and audio.
959
960       · worst:  Select  the worst quality format represented by a single file
961         with video and audio.
962
963       · bestvideo: Select the best  quality  video-only  format  (e.g.   DASH
964         video).  May not be available.
965
966       · worstvideo:  Select  the worst quality video-only format.  May not be
967         available.
968
969       · bestaudio: Select the best quality audio  only-format.   May  not  be
970         available.
971
972       · worstaudio:  Select  the worst quality audio only-format.  May not be
973         available.
974
975       For example, to download the worst quality video-only  format  you  can
976       use -f worstvideo.
977
978       If  you  want  to download multiple videos and they don't have the same
979       formats available, you can specify the order of preference using slash‐
980       es.   Note  that  slash  is left-associative, i.e.  formats on the left
981       hand side are preferred, for example -f 22/17/18 will  download  format
982       22  if  it's  available,  otherwise  it will download format 17 if it's
983       available, otherwise it will download format 18 if it's available, oth‐
984       erwise  it  will  complain  that  no suitable formats are available for
985       download.
986
987       If you want to download several formats of the same video use  a  comma
988       as  a  separator,  e.g.  -f 22,17,18 will download all these three for‐
989       mats, of course if they are available.  Or a more sophisticated example
990       combined          with          the         precedence         feature:
991       -f 136/137/mp4/bestvideo,140/m4a/bestaudio.
992
993       You can also filter the video formats by putting a condition in  brack‐
994       ets, as in -f "best[height=720]" (or -f "[filesize>10M]").
995
996       The  following  numeric meta fields can be used with comparisons <, <=,
997       >, >=, = (equals), != (not equals):
998
999       · filesize: The number of bytes, if known in advance
1000
1001       · width: Width of the video, if known
1002
1003       · height: Height of the video, if known
1004
1005       · tbr: Average bitrate of audio and video in KBit/s
1006
1007       · abr: Average audio bitrate in KBit/s
1008
1009       · vbr: Average video bitrate in KBit/s
1010
1011       · asr: Audio sampling rate in Hertz
1012
1013       · fps: Frame rate
1014
1015       Also filtering work for comparisons = (equals), ^=  (starts  with),  $=
1016       (ends with), *= (contains) and following string meta fields:
1017
1018       · ext: File extension
1019
1020       · acodec: Name of the audio codec in use
1021
1022       · vcodec: Name of the video codec in use
1023
1024       · container: Name of the container format
1025
1026       · protocol:  The  protocol  that  will be used for the actual download,
1027         lower-case  (http,  https,  rtsp,  rtmp,  rtmpe,   mms,   f4m,   ism,
1028         http_dash_segments, m3u8, or m3u8_native)
1029
1030       · format_id: A short description of the format
1031
1032       Any  string comparison may be prefixed with negation ! in order to pro‐
1033       duce an opposite comparison, e.g.  !*= (does not contain).
1034
1035       Note that none of the aforementioned meta fields are guaranteed  to  be
1036       present  since this solely depends on the metadata obtained by particu‐
1037       lar extractor, i.e.  the metadata offered by the video hoster.
1038
1039       Formats for which the value is not known are excluded unless you put  a
1040       question  mark (?) after the operator.  You can combine format filters,
1041       so -f "[height <=? 720][tbr>500]" selects up to 720p videos (or  videos
1042       where the height is not known) with a bitrate of at least 500 KBit/s.
1043
1044       You can merge the video and audio of two formats into a single file us‐
1045       ing -f <video-format>+<audio-format> (requires  ffmpeg  or  avconv  in‐
1046       stalled),  for  example  -f bestvideo+bestaudio  will download the best
1047       video-only format, the best audio-only format  and  mux  them  together
1048       with ffmpeg/avconv.
1049
1050       Format  selectors can also be grouped using parentheses, for example if
1051       you want to download the best mp4 and webm formats with a height  lower
1052       than 480 you can use -f '(mp4,webm)[height<480]'.
1053
1054       Since  the  end  of  April 2015 and version 2015.04.26, youtube-dl uses
1055       -f bestvideo+bestaudio/best as the default format selection (see  #5447
1056       (https://github.com/ytdl-org/youtube-dl/issues/5447),             #5456
1057       (https://github.com/ytdl-org/youtube-dl/issues/5456)).   If  ffmpeg  or
1058       avconv  are installed this results in downloading bestvideo and bestau‐
1059       dio separately and muxing them together into a single file  giving  the
1060       best  overall  quality  available.  Otherwise it falls back to best and
1061       results in downloading the best available quality served  as  a  single
1062       file.   best is also needed for videos that don't come from YouTube be‐
1063       cause they don't provide the audio and video in  two  different  files.
1064       If  you want to only download some DASH formats (for example if you are
1065       not interested in getting videos with a resolution higher than  1080p),
1066       you can add -f bestvideo[height<=?1080]+bestaudio/best to your configu‐
1067       ration file.  Note that if you use youtube-dl to stream to stdout  (and
1068       most likely to pipe it to your media player then), i.e.  you explicitly
1069       specify output template as -o -, youtube-dl still uses  -f best  format
1070       selection in order to start content delivery immediately to your player
1071       and not to wait until bestvideo and bestaudio are downloaded and muxed.
1072
1073       If you want to preserve the old format  selection  behavior  (prior  to
1074       youtube-dl  2015.04.26),  i.e.  you want to download the best available
1075       quality media served as a single file, you  should  explicitly  specify
1076       your  choice with -f best.  You may want to add it to the configuration
1077       file in order not to type it every time you run youtube-dl.
1078
1079   Format selection examples
1080       Note that on Windows you may need to use double quotes instead of  sin‐
1081       gle.
1082
1083              # Download best mp4 format available or any other best if no mp4 available
1084              $ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
1085
1086              # Download best format available but no better than 480p
1087              $ youtube-dl -f 'bestvideo[height<=480]+bestaudio/best[height<=480]'
1088
1089              # Download best video only format but no bigger than 50 MB
1090              $ youtube-dl -f 'best[filesize<50M]'
1091
1092              # Download best format available via direct link over HTTP/HTTPS protocol
1093              $ youtube-dl -f '(bestvideo+bestaudio/best)[protocol^=http]'
1094
1095              # Download the best video format and the best audio format without merging them
1096              $ youtube-dl -f 'bestvideo,bestaudio' -o '%(title)s.f%(format_id)s.%(ext)s'
1097
1098       Note  that  in  the  last example, an output template is recommended as
1099       bestvideo and bestaudio may have the same file name.
1100

VIDEO SELECTION

1102       Videos can be filtered by their upload date using the  options  --date,
1103       --datebefore or --dateafter.  They accept dates in two formats:
1104
1105       · Absolute dates: Dates in the format YYYYMMDD.
1106
1107       · Relative      dates:     Dates     in     the     format     (now|to‐
1108         day)[+-][0-9](day|week|month|year)(s)?
1109
1110       Examples:
1111
1112              # Download only the videos uploaded in the last 6 months
1113              $ youtube-dl --dateafter now-6months
1114
1115              # Download only the videos uploaded on January 1, 1970
1116              $ youtube-dl --date 19700101
1117
1118              $ # Download only the videos uploaded in the 200x decade
1119              $ youtube-dl --dateafter 20000101 --datebefore 20091231
1120

FAQ

1122   How do I update youtube-dl?
1123       If you've followed our manual installation instructions  (https://ytdl-
1124       org.github.io/youtube-dl/download.html),    you    can    simply    run
1125       youtube-dl -U (or, on Linux, sudo youtube-dl -U).
1126
1127       If you have used pip, a simple sudo pip install -U youtube-dl is suffi‐
1128       cient to update.
1129
1130       If  you  have installed youtube-dl using a package manager like apt-get
1131       or yum, use the standard system update mechanism to update.  Note  that
1132       distribution  packages  are  often  outdated.   As  a  rule  of  thumb,
1133       youtube-dl releases at least once a month, and  often  weekly  or  even
1134       daily.  Simply go to https://yt-dl.org to find out the current version.
1135       Unfortunately, there is nothing we youtube-dl developers can do if your
1136       distribution  serves  a  really outdated version.  You can (and should)
1137       complain to your distribution in their bugtracker or support forum.
1138
1139       As a last resort, you can also uninstall the version installed by  your
1140       package  manager  and follow our manual installation instructions.  For
1141       that, remove the distribution's package, with a line like
1142
1143              sudo apt-get remove -y youtube-dl
1144
1145       Afterwards,  simply  follow  our   manual   installation   instructions
1146       (https://ytdl-org.github.io/youtube-dl/download.html):
1147
1148              sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
1149              sudo chmod a+rx /usr/local/bin/youtube-dl
1150              hash -r
1151
1152       Again, from then on you'll be able to update with sudo youtube-dl -U.
1153
1154   youtube-dl is extremely slow to start on Windows
1155       Add a file exclusion for youtube-dl.exe in Windows Defender settings.
1156
1157   I'm getting an error
1158       Unable to extract OpenGraph title on YouTube playlists
1159
1160       YouTube  changed  their  playlist format in March 2014 and later on, so
1161       you'll need at least youtube-dl  2014.07.25  to  download  all  YouTube
1162       videos.
1163
1164       If  you have installed youtube-dl with a package manager, pip, setup.py
1165       or a tarball, please use that to update.  Note that Ubuntu packages  do
1166       not  seem  to  get  updated  anymore.  Since we are not affiliated with
1167       Ubuntu,  there  is  little  we  can  do.   Feel  free  to  report  bugs
1168       (https://bugs.launchpad.net/ubuntu/+source/youtube-dl/+filebug)  to the
1169       Ubuntu   packaging   people   (mailto:ubuntu-motu@lists.ubuntu.com?sub‐
1170       ject=outdated%20version%20of%20youtube-dl) - all they have to do is up‐
1171       date the package to a somewhat recent version.  See above for a way  to
1172       update.
1173
1174   I'm getting an error when trying to use output template:
1175       error: using output template conflicts with using ti‐
1176       tle, video ID or auto number
1177
1178       Make sure you are not using -o with any of these options  -t,  --title,
1179       --id,  -A  or  --auto-number  set in command line or in a configuration
1180       file.  Remove the latter if any.
1181
1182   Do I always have to pass -citw?
1183       By default, youtube-dl intends to have the best options  (incidentally,
1184       if  you  have  a convincing case that these should be different, please
1185       file an issue where you explain that (https://yt-dl.org/bug)).   There‐
1186       fore,  it  is  unnecessary  and  sometimes  harmful to copy long option
1187       strings from webpages.  In particular, the only  option  out  of  -citw
1188       that is regularly useful is -i.
1189
1190   Can you please put the -b option back?
1191       Most  people asking this question are not aware that youtube-dl now de‐
1192       faults to downloading the highest  available  quality  as  reported  by
1193       YouTube,  which  will  be 1080p or 720p in some cases, so you no longer
1194       need the -b option.  For some specific videos, maybe YouTube  does  not
1195       report  them  to  be available in a specific high quality format you're
1196       interested in.  In that case, simply request it with the -f option  and
1197       youtube-dl will try to download it.
1198
1199   I get HTTP error 402 when trying to download a video. What's
1200       this?
1201
1202       Apparently  YouTube requires you to pass a CAPTCHA test if you download
1203       too much.  We're considering to provide a way  to  let  you  solve  the
1204       CAPTCHA (https://github.com/ytdl-org/youtube-dl/issues/154), but at the
1205       moment, your best course of action is pointing a  web  browser  to  the
1206       youtube URL, solving the CAPTCHA, and restart youtube-dl.
1207
1208   Do I need any other programs?
1209       youtube-dl  works  fine on its own on most sites.  However, if you want
1210       to convert video/audio, you'll need avconv (https://libav.org/) or ffm‐
1211       peg  (https://www.ffmpeg.org/).  On some sites - most notably YouTube -
1212       videos can be retrieved in  a  higher  quality  format  without  sound.
1213       youtube-dl  will  detect whether avconv/ffmpeg is present and automati‐
1214       cally pick the best option.
1215
1216       Videos or video formats streamed via RTMP protocol can  only  be  down‐
1217       loaded  when  rtmpdump  (https://rtmpdump.mplayerhq.hu/)  is installed.
1218       Downloading MMS and RTSP videos requires either mplayer (https://mplay
1219       erhq.hu/) or mpv (https://mpv.io/) to be installed.
1220
1221   I have downloaded a video but how can I play it?
1222       Once  the  video is fully downloaded, use any video player, such as mpv
1223       (https://mpv.io/),   vlc   (https://www.videolan.org/)    or    mplayer
1224       (https://www.mplayerhq.hu/).
1225
1226   I extracted a video URL with -g, but it does not play on
1227       another machine / in my web browser.
1228
1229       It depends a lot on the service.  In many cases, requests for the video
1230       (to download/play it) must come from the same IP address and  with  the
1231       same  cookies  and/or  HTTP headers.  Use the --cookies option to write
1232       the required cookies into a file, and advise your  downloader  to  read
1233       cookies from that file.  Some sites also require a common user agent to
1234       be used, use --dump-user-agent to see the one  in  use  by  youtube-dl.
1235       You  can  also  get necessary cookies and HTTP headers from JSON output
1236       obtained with --dump-json.
1237
1238       It may be beneficial to use IPv6; in some cases, the  restrictions  are
1239       only  applied  to  IPv4.  Some services (sometimes only for a subset of
1240       videos) do not restrict the video URL by IP  address,  cookie,  or  us‐
1241       er-agent, but these are the exception rather than the rule.
1242
1243       Please  bear  in  mind  that  some  URL  protocols are not supported by
1244       browsers out of the box, including RTMP.  If you are using -g, your own
1245       downloader must support these as well.
1246
1247       If  you  want  to  play  the  video  on  a  machine that is not running
1248       youtube-dl, you can relay the video content from the machine that  runs
1249       youtube-dl.   You can use -o - to let youtube-dl stream a video to std‐
1250       out, or simply allow the  player  to  download  the  files  written  by
1251       youtube-dl in turn.
1252
1253   ERROR: no fmt_url_map or conn information found in video info
1254       YouTube  has  switched to a new video info format in July 2011 which is
1255       not supported by old versions of youtube-dl.  See above for how to  up‐
1256       date youtube-dl.
1257
1258   ERROR: unable to download video
1259       YouTube  requires an additional signature since September 2012 which is
1260       not supported by old versions of youtube-dl.  See above for how to  up‐
1261       date youtube-dl.
1262
1263   Video URL contains an ampersand and I'm getting some strange
1264       output   [1] 2839   or   'v' is not recognized as an internal or exter‐
1265       nal command
1266
1267       That's actually the output from your shell.  Since ampersand is one  of
1268       the  special  shell characters it's interpreted by the shell preventing
1269       you from passing the whole URL to youtube-dl.  To  disable  your  shell
1270       from  interpreting the ampersands (or any other special characters) you
1271       have to either put the whole URL in quotes or escape them with a  back‐
1272       slash (which approach will work depends on your shell).
1273
1274       For          example          if          your          URL          is
1275       https://www.youtube.com/watch?t=4&v=BaW_jenozKc you should end up  with
1276       following command:
1277
1278       youtube-dl 'https://www.youtube.com/watch?t=4&v=BaW_jenozKc'
1279
1280       or
1281
1282       youtube-dl https://www.youtube.com/watch?t=4\&v=BaW_jenozKc
1283
1284       For Windows you have to use the double quotes:
1285
1286       youtube-dl "https://www.youtube.com/watch?t=4&v=BaW_jenozKc"
1287
1288   ExtractorError: Could not find JS function u'OF'
1289       In February 2015, the new YouTube player contained a character sequence
1290       in a string that was misinterpreted by old versions of youtube-dl.  See
1291       above for how to update youtube-dl.
1292
1293   HTTP Error 429: Too Many Requests or 402: Payment Required
1294       These two error codes indicate that the service is blocking your IP ad‐
1295       dress because of overuse.  Contact the service and ask them to  unblock
1296       your IP address, or - if you have acquired a whitelisted IP address al‐
1297       ready - use the --proxy or --source-address options to  select  another
1298       IP address.
1299
1300   SyntaxError: Non-ASCII character
1301       The error
1302
1303              File "youtube-dl", line 2
1304              SyntaxError: Non-ASCII character '\x93' ...
1305
1306       means  you're  using  an  outdated version of Python.  Please update to
1307       Python 2.6 or 2.7.
1308
1309   What is this binary file? Where has the code gone?
1310       Since  June  2012   (#342   (https://github.com/ytdl-org/youtube-dl/is
1311       sues/342))  youtube-dl is packed as an executable zipfile, simply unzip
1312       it (might need renaming to youtube-dl.zip first  on  some  systems)  or
1313       clone  the  git repository, as laid out above.  If you modify the code,
1314       you can run it by executing the __main__.py file.  To recompile the ex‐
1315       ecutable, run make youtube-dl.
1316
1317   The exe throws an error due to missing MSVCR100.dll
1318       To  run the exe you need to install first the Microsoft Visual C++ 2010
1319       Redistributable  Package  (x86)  (https://www.microsoft.com/en-US/down
1320       load/details.aspx?id=5555).
1321
1322   On Windows, how should I set up ffmpeg and youtube-dl? Where should
1323       I put the exe files?
1324
1325       If you put youtube-dl and ffmpeg in the same directory that you're run‐
1326       ning the command from, it will work, but that's rather cumbersome.
1327
1328       To make a  different  directory  work  -  either  for  ffmpeg,  or  for
1329       youtube-dl,  or for both - simply create the directory (say, C:\bin, or
1330       C:\Users\<User name>\bin), put all the executables directly  in  there,
1331       and   then   set   your   PATH  environment  variable  (https://www.ja
1332       va.com/en/download/help/path.xml) to include that directory.
1333
1334       From then on, after restarting your shell, you will be able  to  access
1335       both youtube-dl and ffmpeg (and youtube-dl will be able to find ffmpeg)
1336       by simply typing youtube-dl or ffmpeg, no matter what directory  you're
1337       in.
1338
1339   How do I put downloads into a specific folder?
1340       Use  the  -o  to  specify an output template, for example -o "/home/us‐
1341       er/videos/%(title)s-%(id)s.%(ext)s".  If you want this for all of  your
1342       downloads, put the option into your configuration file.
1343
1344   How do I download a video starting with a -?
1345       Either prepend https://www.youtube.com/watch?v= or separate the ID from
1346       the options with --:
1347
1348              youtube-dl -- -wNyEUrxzFU
1349              youtube-dl "https://www.youtube.com/watch?v=-wNyEUrxzFU"
1350
1351   How do I pass cookies to youtube-dl?
1352       Use  the  --cookies  option,   for   example   --cookies /path/to/cook‐
1353       ies/file.txt.
1354
1355       In order to extract cookies from browser use any conforming browser ex‐
1356       tension   for   exporting   cookies.     For    example,    cookies.txt
1357       (https://chrome.google.com/webstore/detail/cookiestxt/njabckikapfpffap
1358       mjgojcnbfjonfjfg) (for Chrome)  or  cookies.txt  (https://addons.mozil
1359       la.org/en-US/firefox/addon/cookies-txt/) (for Firefox).
1360
1361       Note  that  the cookies file must be in Mozilla/Netscape format and the
1362       first line of the cookies file must  be  either  # HTTP Cookie File  or
1363       # Netscape HTTP Cookie File.  Make sure you have correct newline format
1364       (https://en.wikipedia.org/wiki/Newline) in the cookies file and convert
1365       newlines  if  necessary  to correspond with your OS, namely CRLF (\r\n)
1366       for Windows and LF (\n) for Unix and Unix-like systems  (Linux,  macOS,
1367       etc.).  HTTP Error 400: Bad Request when using --cookies is a good sign
1368       of invalid newline format.
1369
1370       Passing cookies to youtube-dl is a good way to workaround login when  a
1371       particular  extractor  does  not  implement it explicitly.  Another use
1372       case is working around CAPTCHA  (https://en.wikipedia.org/wiki/CAPTCHA)
1373       some  websites require you to solve in particular cases in order to get
1374       access (e.g.  YouTube, CloudFlare).
1375
1376   How do I stream directly to media player?
1377       You will first need to tell youtube-dl to stream media to  stdout  with
1378       -o -,  and  also  tell your media player to read from stdin (it must be
1379       capable of this for streaming) and then pipe former to latter.  For ex‐
1380       ample,  streaming  to  vlc  (https://www.videolan.org/) can be achieved
1381       with:
1382
1383              youtube-dl -o - "https://www.youtube.com/watch?v=BaW_jenozKcj" | vlc -
1384
1385   How do I download only new videos from a playlist?
1386       Use download-archive feature.  With this feature you  should  initially
1387       download  the  complete playlist with --download-archive /path/to/down‐
1388       load/archive/file.txt that will record identifiers of all the videos in
1389       a  special  file.  Each subsequent run with the same --download-archive
1390       will download only new videos and skip all videos that have been  down‐
1391       loaded before.  Note that only successful downloads are recorded in the
1392       file.
1393
1394       For example, at first,
1395
1396              youtube-dl --download-archive archive.txt "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1397
1398       will download the complete PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re  playlist
1399       and  create a file archive.txt.  Each subsequent run will only download
1400       new videos if any:
1401
1402              youtube-dl --download-archive archive.txt "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1403
1404   Should I add --hls-prefer-native into my config?
1405       When youtube-dl detects an HLS video, it can download  it  either  with
1406       the built-in downloader or ffmpeg.  Since many HLS streams are slightly
1407       invalid and ffmpeg/youtube-dl each handle  some  invalid  cases  better
1408       than the other, there is an option to switch the downloader if needed.
1409
1410       When youtube-dl knows that one particular downloader works better for a
1411       given website, that downloader will be picked.   Otherwise,  youtube-dl
1412       will  pick  the best downloader for general compatibility, which at the
1413       moment happens to be ffmpeg.  This choice may change in future versions
1414       of youtube-dl, with improvements of the built-in downloader and/or ffm‐
1415       peg.
1416
1417       In particular, the generic extractor (used when your website is not  in
1418       the    list   of   supported   sites   by   youtube-dl   (https://ytdl-
1419       org.github.io/youtube-dl/supportedsites.html) cannot mandate  one  spe‐
1420       cific downloader.
1421
1422       If  you put either --hls-prefer-native or --hls-prefer-ffmpeg into your
1423       configuration, a different subset of videos will fail to download  cor‐
1424       rectly.   Instead,  it  is  much  better  to file an issue (https://yt-
1425       dl.org/bug) or a pull request which details why the native or the  ffm‐
1426       peg HLS downloader is a better choice for your use case.
1427
1428   Can you add support for this anime video site, or site which shows
1429       current movies for free?
1430
1431       As  a  matter  of policy (as well as legality), youtube-dl does not in‐
1432       clude support for services that specialize in infringing copyright.  As
1433       a  rule of thumb, if you cannot easily find a video that the service is
1434       quite obviously allowed to distribute (i.e.  that has been uploaded  by
1435       the  creator,  the  creator's distributor, or is published under a free
1436       license), the service is probably unfit for inclusion to youtube-dl.
1437
1438       A note on the service that they don't host the infringing content,  but
1439       just  link  to those who do, is evidence that the service should not be
1440       included into youtube-dl.  The same goes for any  DMCA  note  when  the
1441       whole  front page of the service is filled with videos they are not al‐
1442       lowed to distribute.  A "fair use" note is equally unconvincing if  the
1443       service shows copyright-protected videos in full without authorization.
1444
1445       Support requests for services that do purchase the rights to distribute
1446       their content are perfectly fine though.  If in doubt, you  can  simply
1447       include a source that mentions the legitimate purchase of content.
1448
1449   How can I speed up work on my issue?
1450       (Also  known  as:  Help,  my  important  issue  not  being solved!) The
1451       youtube-dl core developer team is quite small.  While we do our best to
1452       solve  as  many  issues  as  possible,  sometimes that can take quite a
1453       while.  To speed up your issue, here's what you can do:
1454
1455       First of  all,  please  do  report  the  issue  at  our  issue  tracker
1456       (https://yt-dl.org/bugs).   That allows us to coordinate all efforts by
1457       users and developers, and serves as a  unified  point.   Unfortunately,
1458       the  youtube-dl project has grown too large to use personal email as an
1459       effective communication channel.
1460
1461       Please read the bug reporting instructions below.  A lot of  bugs  lack
1462       all  the necessary information.  If you can, offer proxy, VPN, or shell
1463       access to the youtube-dl developers.  If you are able to, test the  is‐
1464       sue from multiple computers in multiple countries to exclude local cen‐
1465       sorship or misconfiguration issues.
1466
1467       If nobody is interested in solving your issue, you are welcome to  take
1468       matters  into  your  own hands and submit a pull request (or coerce/pay
1469       somebody else to do so).
1470
1471       Feel free to bump the issue from time to time by writing a  small  com‐
1472       ment ("Issue is still present in youtube-dl version ...from France, but
1473       fixed from Belgium"), but please not more than once a month.  Please do
1474       not declare your issue as important or urgent.
1475
1476   How can I detect whether a given URL is supported by youtube-dl?
1477       For  one,  have  a look at the list of supported sites (docs/supported‐
1478       sites.md).  Note that it can sometimes happen that the site changes its
1479       URL  scheme (say, from https://example.com/video/1234567 to https://ex
1480       ample.com/v/1234567 ) and youtube-dl reports an URL  of  a  service  in
1481       that list as unsupported.  In that case, simply report a bug.
1482
1483       It is not possible to detect whether a URL is supported or not.  That's
1484       because youtube-dl contains a generic extractor which matches all URLs.
1485       You  may  be tempted to disable, exclude, or remove the generic extrac‐
1486       tor, but the generic extractor not only allows users to extract  videos
1487       from  lots of websites that embed a video from another service, but may
1488       also be used to extract video from a service that it's hosting  itself.
1489       Therefore,  we  neither  recommend nor support disabling, excluding, or
1490       removing the generic extractor.
1491
1492       If you want to find out whether a given URL is supported,  simply  call
1493       youtube-dl  with it.  If you get no videos back, chances are the URL is
1494       either not referring to a video or unsupported.  You can find out which
1495       by  examining  the  output  (if  you  run youtube-dl on the console) or
1496       catching an UnsupportedError exception if you run it from a Python pro‐
1497       gram.
1498

Why do I need to go through that much red tape when filing bugs?

1500       Before  we  had the issue template, despite our extensive bug reporting
1501       instructions, about 80% of the issue reports we got were  useless,  for
1502       instance because people used ancient versions hundreds of releases old,
1503       because of simple syntactic errors (not in youtube-dl  but  in  general
1504       shell  usage),  because the problem was already reported multiple times
1505       before, because people did not actually read an error message, even  if
1506       it said "please install ffmpeg", because people did not mention the URL
1507       they were trying to download and many more simple, easy-to-avoid  prob‐
1508       lems, many of whom were totally unrelated to youtube-dl.
1509
1510       youtube-dl  is  an open-source project manned by too few volunteers, so
1511       we'd rather spend time fixing bugs where we are certain none  of  those
1512       simple  problems  apply, and where we can be reasonably confident to be
1513       able to reproduce the issue without asking the reporter repeatedly.  As
1514       such,  the  output  of youtube-dl -v YOUR_URL_HERE is really all that's
1515       required to file an issue.  The issue template also guides you  through
1516       some  basic  steps  you  can  do, such as checking that your version of
1517       youtube-dl is current.
1518

DEVELOPER INSTRUCTIONS

1520       Most users do not need to build youtube-dl and can download the  builds
1521       (https://ytdl-org.github.io/youtube-dl/download.html)  or get them from
1522       their distribution.
1523
1524       To run youtube-dl as a developer, you don't need to build anything  ei‐
1525       ther.  Simply execute
1526
1527              python -m youtube_dl
1528
1529       To  run the test, simply invoke your favorite test runner, or execute a
1530       test file directly; any of the following work:
1531
1532              python -m unittest discover
1533              python test/test_download.py
1534              nosetests
1535
1536       See item 6 of new extractor tutorial for how to run extractor  specific
1537       test cases.
1538
1539       If you want to create a build of youtube-dl yourself, you'll need
1540
1541       · python
1542
1543       · make (only GNU make is supported)
1544
1545       · pandoc
1546
1547       · zip
1548
1549       · nosetests
1550
1551   Adding support for a new site
1552       If  you want to add support for a new site, first of all make sure this
1553       site is not dedicated to copyright infringement (README.md#can-you-add-
1554       support-for-this-anime-video-site-or-site-which-shows-current-movies-
1555       for-free).  youtube-dl does not support such sites thus  pull  requests
1556       adding support for them will be rejected.
1557
1558       After  you  have ensured this site is distributing its content legally,
1559       you can follow this quick list (assuming your service is called yourex‐
1560       tractor):
1561
1562        1. Fork this repository (https://github.com/ytdl-org/youtube-dl/fork)
1563
1564        2. Check out the source code with:
1565
1566                   git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
1567
1568        3. Start a new git branch with
1569
1570                   cd youtube-dl
1571                   git checkout -b yourextractor
1572
1573        4. Start  with  this simple template and save it to youtube_dl/extrac‐
1574           tor/yourextractor.py:
1575
1576                  # coding: utf-8
1577                  from __future__ import unicode_literals
1578
1579                  from .common import InfoExtractor
1580
1581
1582                  class YourExtractorIE(InfoExtractor):
1583                      _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
1584                      _TEST = {
1585                          'url': 'https://yourextractor.com/watch/42',
1586                          'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
1587                          'info_dict': {
1588                              'id': '42',
1589                              'ext': 'mp4',
1590                              'title': 'Video title goes here',
1591                              'thumbnail': r're:^https?://.*\.jpg$',
1592                              # TODO more properties, either as:
1593                              # * A value
1594                              # * MD5 checksum; start the string with md5:
1595                              # * A regular expression; start the string with re:
1596                              # * Any Python type (for example int or float)
1597                          }
1598                      }
1599
1600                      def _real_extract(self, url):
1601                          video_id = self._match_id(url)
1602                          webpage = self._download_webpage(url, video_id)
1603
1604                          # TODO more code goes here, for example ...
1605                          title = self._html_search_regex(r'<h1>(.+?)</h1>', webpage, 'title')
1606
1607                          return {
1608                              'id': video_id,
1609                              'title': title,
1610                              'description': self._og_search_description(webpage),
1611                              'uploader': self._search_regex(r'<div[^>]+id="uploader"[^>]*>([^<]+)<', webpage, 'uploader', fatal=False),
1612                              # TODO more properties (see youtube_dl/extractor/common.py)
1613                          }
1614
1615        5. Add     an     import     in     youtube_dl/extractor/extractors.py
1616           (https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/ex
1617           tractor/extractors.py).
1618
1619        6. Run   python test/test_download.py TestDownload.test_YourExtractor.
1620           This  should fail at first, but you can continually re-run it until
1621           you're done.  If you decide to add more than one test, then  rename
1622           _TEST to _TESTS and make it into a list of dictionaries.  The tests
1623           will  then  be  named  TestDownload.test_YourExtractor,   TestDown‐
1624           load.test_YourExtractor_1,  TestDownload.test_YourExtractor_2, etc.
1625           Note that tests with only_matching  key  in  test's  dict  are  not
1626           counted in.
1627
1628        7. Have       a       look      at      youtube_dl/extractor/common.py
1629           (https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/ex
1630           tractor/common.py)  for  possible helper methods and a detailed de‐
1631           scription  of  what  your   extractor   should   and   may   return
1632           (https://github.com/ytdl-org/youtube-
1633           dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extrac‐
1634           tor/common.py#L94-L303).   Add  tests  and  code for as many as you
1635           want.
1636
1637        8. Make sure your code follows youtube-dl coding conventions and check
1638           the   code   with   flake8   (http://flake8.pycqa.org/en/latest/in
1639           dex.html#quickstart):
1640
1641                   $ flake8 youtube_dl/extractor/yourextractor.py
1642
1643        9. Make    sure    your    code     works     under     all     Python
1644           (https://www.python.org/) versions claimed supported by youtube-dl,
1645           namely 2.6, 2.7, and 3.2+.
1646
1647       10. When the tests pass, add (https://git-scm.com/docs/git-add) the new
1648           files  and  commit  (https://git-scm.com/docs/git-commit)  them and
1649           push (https://git-scm.com/docs/git-push) the result, like this:
1650
1651                  $ git add youtube_dl/extractor/extractors.py
1652                  $ git add youtube_dl/extractor/yourextractor.py
1653                  $ git commit -m '[yourextractor] Add new extractor'
1654                  $ git push origin yourextractor
1655
1656       11. Finally,  create  a  pull  request   (https://help.github.com/arti
1657           cles/creating-a-pull-request).  We'll then review and merge it.
1658
1659       In any case, thank you very much for your contributions!
1660
1661   youtube-dl coding conventions
1662       This section introduces a guide lines for writing idiomatic, robust and
1663       future-proof extractor code.
1664
1665       Extractors are very fragile by nature since they depend on  the  layout
1666       of the source data provided by 3rd party media hosters out of your con‐
1667       trol and this layout tends to change.  As an extractor implementer your
1668       task  is not only to write code that will extract media links and meta‐
1669       data correctly but also to minimize dependency on the  source's  layout
1670       and even to make the code foresee potential future changes and be ready
1671       for that.  This is important because it will allow the extractor not to
1672       break  on  minor  layout  changes  thus keeping old youtube-dl versions
1673       working.  Even though this breakage issue is easily fixed by emitting a
1674       new  version  of  youtube-dl  with a fix incorporated, all the previous
1675       versions become broken in all repositories and distros'  packages  that
1676       may  not be so prompt in fetching the update from us.  Needless to say,
1677       some non rolling release distros may never receive an update at all.
1678
1679   Mandatory and optional metafields
1680       For extraction to work youtube-dl relies on metadata your extractor ex‐
1681       tracts  and  provides to youtube-dl expressed by an information dictio‐
1682       nary                              (https://github.com/ytdl-org/youtube-
1683       dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extrac‐
1684       tor/common.py#L94-L303) or simply info dict.  Only the  following  meta
1685       fields  in  the info dict are considered mandatory for a successful ex‐
1686       traction process by youtube-dl:
1687
1688       · id (media identifier)
1689
1690       · title (media title)
1691
1692       · url (media download URL) or formats
1693
1694       In fact only the last option is technically  mandatory  (i.e.   if  you
1695       can't figure out the download location of the media the extraction does
1696       not make any sense).  But by convention youtube-dl also treats  id  and
1697       title  as mandatory.  Thus the aforementioned metafields are the criti‐
1698       cal data that the extraction does not make any sense without and if any
1699       of them fail to be extracted then the extractor is considered complete‐
1700       ly broken.
1701
1702       Any             field             (https://github.com/ytdl-org/youtube-
1703       dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extrac‐
1704       tor/common.py#L188-L303) apart from the aforementioned ones are consid‐
1705       ered optional.  That means that extraction should be tolerant to situa‐
1706       tions when sources for these  fields  can  potentially  be  unavailable
1707       (even  if  they are always available at the moment) and future-proof in
1708       order not to break the extraction of general purpose mandatory fields.
1709
1710   Example
1711       Say you have some source dictionary meta that you've  fetched  as  JSON
1712       with HTTP request and it has a key summary:
1713
1714              meta = self._download_json(url, video_id)
1715
1716       Assume at this point meta's layout is:
1717
1718              {
1719                  ...
1720                  "summary": "some fancy summary text",
1721                  ...
1722              }
1723
1724       Assume  you  want to extract summary and put it into the resulting info
1725       dict as description.  Since description is an optional meta  field  you
1726       should  be  ready  that  this key may be missing from the meta dict, so
1727       that you should extract it like:
1728
1729              description = meta.get('summary')  # correct
1730
1731       and not like:
1732
1733              description = meta['summary']  # incorrect
1734
1735       The latter will break extraction process with KeyError if summary  dis‐
1736       appears  from  meta at some later time but with the former approach ex‐
1737       traction will just go ahead with description set to None which is  per‐
1738       fectly fine (remember None is equivalent to the absence of data).
1739
1740       Similarly,  you  should  pass fatal=False when extracting optional data
1741       from a webpage with _search_regex, _html_search_regex or similar  meth‐
1742       ods, for instance:
1743
1744              description = self._search_regex(
1745                  r'<span[^>]+id="title"[^>]*>([^<]+)<',
1746                  webpage, 'description', fatal=False)
1747
1748       With  fatal  set to False if _search_regex fails to extract description
1749       it will emit a warning and continue extraction.
1750
1751       You can also pass default=<some fallback value>, for example:
1752
1753              description = self._search_regex(
1754                  r'<span[^>]+id="title"[^>]*>([^<]+)<',
1755                  webpage, 'description', default=None)
1756
1757       On failure this code will silently continue  the  extraction  with  de‐
1758       scription  set  to None.  That is useful for metafields that may or may
1759       not be present.
1760
1761   Provide fallbacks
1762       When extracting metadata try to do so from multiple sources.  For exam‐
1763       ple if title is present in several places, try extracting from at least
1764       some of them.  This makes it more future-proof  in  case  some  of  the
1765       sources become unavailable.
1766
1767   Example
1768       Say meta from the previous example has a title and you are about to ex‐
1769       tract it.  Since title is a mandatory meta field you should end up with
1770       something like:
1771
1772              title = meta['title']
1773
1774       If  title  disappears  from  meta  in future due to some changes on the
1775       hoster's side the extraction  would  fail  since  title  is  mandatory.
1776       That's expected.
1777
1778       Assume  that  you  have some another source you can extract title from,
1779       for example og:title HTML meta of a webpage.  In this case you can pro‐
1780       vide a fallback scenario:
1781
1782              title = meta.get('title') or self._og_search_title(webpage)
1783
1784       This  code  will try to extract from meta first and if it fails it will
1785       try extracting og:title from a webpage.
1786
1787   Regular expressions
1788   Don't capture groups you don't use
1789       Capturing group must be an indication that it's used somewhere  in  the
1790       code.  Any group that is not used must be non capturing.
1791
1792   Example
1793       Don't  capture  id  attribute name here since you can't use it for any‐
1794       thing anyway.
1795
1796       Correct:
1797
1798              r'(?:id|ID)=(?P<id>\d+)'
1799
1800       Incorrect:
1801
1802              r'(id|ID)=(?P<id>\d+)'
1803
1804   Make regular expressions relaxed and flexible
1805       When using regular expressions try to write  them  fuzzy,  relaxed  and
1806       flexible,  skipping insignificant parts that are more likely to change,
1807       allowing both single and double quotes for quoted values and so on.
1808
1809   Example
1810       Say you need to extract title from the following HTML code:
1811
1812              <span style="position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;" class="title">some fancy title</span>
1813
1814       The code for that task should look similar to:
1815
1816              title = self._search_regex(
1817                  r'<span[^>]+class="title"[^>]*>([^<]+)', webpage, 'title')
1818
1819       Or even better:
1820
1821              title = self._search_regex(
1822                  r'<span[^>]+class=(["\'])title\1[^>]*>(?P<title>[^<]+)',
1823                  webpage, 'title', group='title')
1824
1825       Note how you tolerate potential changes in the style attribute's  value
1826       or switch from using double quotes to single for class attribute:
1827
1828       The code definitely should not look like:
1829
1830              title = self._search_regex(
1831                  r'<span style="position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;" class="title">(.*?)</span>',
1832                  webpage, 'title', group='title')
1833
1834   Long lines policy
1835       There  is  a soft limit to keep lines of code under 80 characters long.
1836       This means it should be respected if possible and if it does  not  make
1837       readability and code maintenance worse.
1838
1839       For  example,  you should never split long string literals like URLs or
1840       some other often copied entities over multiple lines to fit this limit:
1841
1842       Correct:
1843
1844              'https://www.youtube.com/watch?v=FqZTN594JQw&list=PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4'
1845
1846       Incorrect:
1847
1848              'https://www.youtube.com/watch?v=FqZTN594JQw&list='
1849              'PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4'
1850
1851   Inline values
1852       Extracting variables is acceptable for reducing  code  duplication  and
1853       improving  readability  of  complex  expressions.   However, you should
1854       avoid extracting variables used only once and moving them  to  opposite
1855       parts of the extractor file, which makes reading the linear flow diffi‐
1856       cult.
1857
1858   Example
1859       Correct:
1860
1861              title = self._html_search_regex(r'<title>([^<]+)</title>', webpage, 'title')
1862
1863       Incorrect:
1864
1865              TITLE_RE = r'<title>([^<]+)</title>'
1866              # ...some lines of code...
1867              title = self._html_search_regex(TITLE_RE, webpage, 'title')
1868
1869   Collapse fallbacks
1870       Multiple fallback values can quickly become unwieldy.  Collapse  multi‐
1871       ple fallback values into a single expression via a list of patterns.
1872
1873   Example
1874       Good:
1875
1876              description = self._html_search_meta(
1877                  ['og:description', 'description', 'twitter:description'],
1878                  webpage, 'description', default=None)
1879
1880       Unwieldy:
1881
1882              description = (
1883                  self._og_search_description(webpage, default=None)
1884                  or self._html_search_meta('description', webpage, default=None)
1885                  or self._html_search_meta('twitter:description', webpage, default=None))
1886
1887       Methods    supporting    list    of    patterns   are:   _search_regex,
1888       _html_search_regex, _og_search_property, _html_search_meta.
1889
1890   Trailing parentheses
1891       Always move trailing parentheses after the last argument.
1892
1893   Example
1894       Correct:
1895
1896                  lambda x: x['ResultSet']['Result'][0]['VideoUrlSet']['VideoUrl'],
1897                  list)
1898
1899       Incorrect:
1900
1901                  lambda x: x['ResultSet']['Result'][0]['VideoUrlSet']['VideoUrl'],
1902                  list,
1903              )
1904
1905   Use convenience conversion and parsing functions
1906       Wrap  all   extracted   numeric   data   into   safe   functions   from
1907       youtube_dl/utils.py   (https://github.com/ytdl-org/youtube-dl/blob/mas
1908       ter/youtube_dl/utils.py): int_or_none,  float_or_none.   Use  them  for
1909       string to number conversions as well.
1910
1911       Use url_or_none for safe URL processing.
1912
1913       Use try_get for safe metadata extraction from parsed JSON.
1914
1915       Use  unified_strdate for uniform upload_date or any YYYYMMDD meta field
1916       extraction,  unified_timestamp  for   uniform   timestamp   extraction,
1917       parse_filesize  for  filesize  extraction,  parse_count  for count meta
1918       fields extraction, parse_resolution, parse_duration  for  duration  ex‐
1919       traction, parse_age_limit for age_limit extraction.
1920
1921       Explore    youtube_dl/utils.py    (https://github.com/ytdl-org/youtube-
1922       dl/blob/master/youtube_dl/utils.py) for more useful  convenience  func‐
1923       tions.
1924
1925   More examples
1926   Safely extract optional description from parsed JSON
1927              description = try_get(response, lambda x: x['result']['video'][0]['summary'], compat_str)
1928
1929   Safely extract more optional metadata
1930              video = try_get(response, lambda x: x['result']['video'][0], dict) or {}
1931              description = video.get('summary')
1932              duration = float_or_none(video.get('durationMs'), scale=1000)
1933              view_count = int_or_none(video.get('views'))
1934

EMBEDDING YOUTUBE-DL

1936       youtube-dl makes the best effort to be a good command-line program, and
1937       thus should be callable from any  programming  language.   If  you  en‐
1938       counter  any  problems parsing its output, feel free to create a report
1939       (https://github.com/ytdl-org/youtube-dl/issues/new).
1940
1941       From a Python program, you can embed  youtube-dl  in  a  more  powerful
1942       fashion, like this:
1943
1944              from __future__ import unicode_literals
1945              import youtube_dl
1946
1947              ydl_opts = {}
1948              with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1949                  ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])
1950
1951       Most likely, you'll want to use various options.  For a list of options
1952       available,     have     a     look      at      youtube_dl/YoutubeDL.py
1953       (https://github.com/ytdl-org/youtube-
1954       dl/blob/3e4cedf9e8cd3157df2457df7274d0c842421945/youtube_dl/YoutubeDL.py#L137-L312).
1955       For a start, if you want to intercept youtube-dl's output, set a logger
1956       object.
1957
1958       Here's a more complete example of a program that  outputs  only  errors
1959       (and  a  short  message  after  the  download  is  finished), and down‐
1960       loads/converts the video to an mp3 file:
1961
1962              from __future__ import unicode_literals
1963              import youtube_dl
1964
1965
1966              class MyLogger(object):
1967                  def debug(self, msg):
1968                      pass
1969
1970                  def warning(self, msg):
1971                      pass
1972
1973                  def error(self, msg):
1974                      print(msg)
1975
1976
1977              def my_hook(d):
1978                  if d['status'] == 'finished':
1979                      print('Done downloading, now converting ...')
1980
1981
1982              ydl_opts = {
1983                  'format': 'bestaudio/best',
1984                  'postprocessors': [{
1985                      'key': 'FFmpegExtractAudio',
1986                      'preferredcodec': 'mp3',
1987                      'preferredquality': '192',
1988                  }],
1989                  'logger': MyLogger(),
1990                  'progress_hooks': [my_hook],
1991              }
1992              with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1993                  ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])
1994

BUGS

1996       Bugs and suggestions should be reported  at:  <https://github.com/ytdl-
1997       org/youtube-dl/issues>.  Unless you were prompted to or there is anoth‐
1998       er pertinent reason (e.g.  GitHub fails  to  accept  the  bug  report),
1999       please  do  not  send bug reports via personal email.  For discussions,
2000       join   us   in   the   IRC   channel   #youtube-dl   (irc://chat.freen‐
2001       ode.net/#youtube-dl)   on   freenode  (webchat  (https://webchat.freen
2002       ode.net/?randomnick=1&channels=youtube-dl)).
2003
2004       Please include the full output of youtube-dl when  run  with  -v,  i.e.
2005       add  -v flag to your command line, copy the whole output and post it in
2006       the issue body wrapped in ``` for better formatting.   It  should  look
2007       similar to this:
2008
2009              $ youtube-dl -v <your command line>
2010              [debug] System config: []
2011              [debug] User config: []
2012              [debug] Command-line args: [u'-v', u'https://www.youtube.com/watch?v=BaW_jenozKcj']
2013              [debug] Encodings: locale cp1251, fs mbcs, out cp866, pref cp1251
2014              [debug] youtube-dl version 2015.12.06
2015              [debug] Git HEAD: 135392e
2016              [debug] Python version 2.6.6 - Windows-2003Server-5.2.3790-SP2
2017              [debug] exe versions: ffmpeg N-75573-g1d0487f, ffprobe N-75573-g1d0487f, rtmpdump 2.4
2018              [debug] Proxy map: {}
2019              ...
2020
2021       Do not post screenshots of verbose logs; only plain text is acceptable.
2022
2023       The output (including the first lines) contains important debugging in‐
2024       formation.  Issues without the full output are often  not  reproducible
2025       and therefore do not get solved in short order, if ever.
2026
2027       Please  re-read  your issue once again to avoid a couple of common mis‐
2028       takes (you can and should use this as a checklist):
2029
2030   Is the description of the issue itself sufficient?
2031       We often get issue reports that we cannot really  decipher.   While  in
2032       most cases we eventually get the required information after asking back
2033       multiple times, this poses an unnecessary drain on our resources.  Many
2034       contributors, including myself, are also not native speakers, so we may
2035       misread some parts.
2036
2037       So please elaborate on what feature you are requesting, or what bug you
2038       want to be fixed.  Make sure that it's obvious
2039
2040       · What the problem is
2041
2042       · How it could be fixed
2043
2044       · How your proposed solution would look like
2045
2046       If  your report is shorter than two lines, it is almost certainly miss‐
2047       ing some of these, which makes it hard for us to respond to it.   We're
2048       often  too  polite  to  close  the issue outright, but the missing info
2049       makes misinterpretation likely.  As a committer  myself,  I  often  get
2050       frustrated  by these issues, since the only possible way for me to move
2051       forward on them is to ask for clarification over and over.
2052
2053       For bug reports, this means that your report should  contain  the  com‐
2054       plete  output  of  youtube-dl  when called with the -v flag.  The error
2055       message you get for (most) bugs even says so, but you would not believe
2056       how many of our bug reports do not contain this information.
2057
2058       If  your  server  has  multiple  IPs  or you suspect censorship, adding
2059       --call-home may be a good idea to get more diagnostics.  If  the  error
2060       is ERROR: Unable to extract ... and you cannot reproduce it from multi‐
2061       ple countries, add --dump-pages (warning:  this  will  yield  a  rather
2062       large  output,  redirect it to the file log.txt by adding >log.txt 2>&1
2063       to your command-line) or upload the .dump files you get  when  you  add
2064       --write-pages somewhere (https://gist.github.com/).
2065
2066       Site support requests must contain an example URL.  An example URL is a
2067       URL      you       might       want       to       download,       like
2068       https://www.youtube.com/watch?v=BaW_jenozKc.   There should be an obvi‐
2069       ous video present.  Except under very special circumstances,  the  main
2070       page  of a video service (e.g.  https://www.youtube.com/) is not an ex‐
2071       ample URL.
2072
2073   Are you using the latest version?
2074       Before reporting any issue, type  youtube-dl -U.   This  should  report
2075       that  you're  up-to-date.   About 20% of the reports we receive are al‐
2076       ready fixed, but people are using outdated  versions.   This  goes  for
2077       feature requests as well.
2078
2079   Is the issue already documented?
2080       Make  sure  that someone has not already opened the issue you're trying
2081       to open.  Search at the top of the window or browse the  GitHub  Issues
2082       (https://github.com/ytdl-org/youtube-dl/search?type=Issues)   of   this
2083       repository.  If there is an issue, feel free to write  something  along
2084       the  lines  of "This affects me as well, with version 2015.01.01.  Here
2085       is some more information on the issue: ...".  While some issues may  be
2086       old, a new post into them often spurs rapid activity.
2087
2088   Why are existing options not enough?
2089       Before  requesting  a new feature, please have a quick peek at the list
2090       of supported options  (https://github.com/ytdl-org/youtube-dl/blob/mas
2091       ter/README.md#options).   Many  feature  requests are for features that
2092       actually exist already!  Please, absolutely do show off  your  work  in
2093       the  issue  report  and  detail how the existing similar options do not
2094       solve your problem.
2095
2096   Is there enough context in your bug report?
2097       People want to solve problems, and often think they do us  a  favor  by
2098       breaking  down  their  larger  problems  (e.g.  wanting to skip already
2099       downloaded files) to a specific request (e.g.  requesting  us  to  look
2100       whether  the  file  exists before downloading the info page).  However,
2101       what often happens is that they break down the problem into two  steps:
2102       One simple, and one impossible (or extremely complicated one).
2103
2104       We are then presented with a very complicated request when the original
2105       problem could be solved far easier, e.g.  by recording  the  downloaded
2106       video  IDs  in  a  separate  file.  To avoid this, you must include the
2107       greater context where it is non-obvious.  In particular, every  feature
2108       request  that  does not consist of adding support for a new site should
2109       contain a use case scenario that explains in what situation the missing
2110       feature would be useful.
2111
2112   Does the issue involve one problem, and one problem only?
2113       Some  of our users seem to think there is a limit of issues they can or
2114       should open.  There is no limit of issues  they  can  or  should  open.
2115       While it may seem appealing to be able to dump all your issues into one
2116       ticket, that means that someone who solves one of  your  issues  cannot
2117       mark the issue as closed.  Typically, reporting a bunch of issues leads
2118       to the ticket lingering since nobody wants to attack that behemoth, un‐
2119       til someone mercifully splits the issue into multiple ones.
2120
2121       In  particular, every site support request issue should only pertain to
2122       services at one site (generally under a common domain, but always using
2123       the  same  backend  technology).  Do not request support for vimeo user
2124       videos, White house podcasts, and Google Plus pages in the same  issue.
2125       Also,  make  sure that you don't post bug reports alongside feature re‐
2126       quests.  As a rule of thumb, a feature request does not include outputs
2127       of  youtube-dl that are not immediately related to the feature at hand.
2128       Do not post reports of a network error alongside the request for a  new
2129       video service.
2130
2131   Is anyone going to need the feature?
2132       Only post features that you (or an incapacitated friend you can person‐
2133       ally talk to) require.  Do not post features because they seem  like  a
2134       good  idea.  If they are really useful, they will be requested by some‐
2135       one who requires them.
2136
2137   Is your question about youtube-dl?
2138       It may sound strange, but some bug reports we  receive  are  completely
2139       unrelated  to  youtube-dl  and  relate  to a different, or even the re‐
2140       porter's own, application.  Please make sure that you are actually  us‐
2141       ing  youtube-dl.   If you are using a UI for youtube-dl, report the bug
2142       to the maintainer of the actual application providing the UI.   On  the
2143       other  hand, if your UI for youtube-dl fails in some way you believe is
2144       related to youtube-dl, by all means, go ahead and report the bug.
2145
2147       youtube-dl is released into the public domain by the copyright holders.
2148
2149       This  README   file   was   originally   written   by   Daniel   Bolton
2150       (https://github.com/dbbolton)  and is likewise released into the public
2151       domain.
2152
2153
2154
2155                                                                 YOUTUBE-DL(1)
Impressum