]> Raphaƫl G. Git Repositories - youtubedl/blobdiff - youtube-dl.1
Prepare to release
[youtubedl] / youtube-dl.1
index 49818dc4f9ff31eb7ad125cef03b906abb0556e0..9ab22b088eb9f20093113f24114b551de9843ebd 100644 (file)
@@ -242,11 +242,11 @@ Do not download any videos with more than COUNT views
 .TP
 .B \-\-match\-filter \f[I]FILTER\f[]
 Generic video filter.
-Specify any key (see help for \-o for a list of available keys) to match
-if the key is present, !key to check if the key is not present, key >
-NUMBER (like "comment_count > 12", also works with >=, <, <=, !=, =) to
-compare against a number, key = \[aq]LITERAL\[aq] (like "uploader =
-\[aq]Mike Smith\[aq]", also works with !=) to match against a string
+Specify any key (see the "OUTPUT TEMPLATE" for a list of available keys)
+to match if the key is present, !key to check if the key is not present,
+key > NUMBER (like "comment_count > 12", also works with >=, <, <=, !=,
+=) to compare against a number, key = \[aq]LITERAL\[aq] (like "uploader
+\[aq]Mike Smith\[aq]", also works with !=) to match against a string
 literal and & to require multiple matches.
 Values which are not known are excluded unless you put a question mark
 (?) after the operator.
@@ -550,7 +550,7 @@ Simulate, quiet but print output format
 .TP
 .B \-j, \-\-dump\-json
 Simulate, quiet but print JSON information.
-See \-\-output for a description of available keys.
+See the "OUTPUT TEMPLATE" for a description of available keys.
 .RS
 .RE
 .TP
@@ -894,7 +894,8 @@ Example: \-\-exec \[aq]adb push {} /sdcard/Music/ && rm {}\[aq]
 .RE
 .TP
 .B \-\-convert\-subs \f[I]FORMAT\f[]
-Convert the subtitles to other format (currently supported: srt|ass|vtt)
+Convert the subtitles to other format (currently supported:
+srt|ass|vtt|lrc)
 .RS
 .RE
 .SH CONFIGURATION
@@ -952,7 +953,7 @@ pass credentials as command line arguments on every youtube\-dl
 execution and prevent tracking plain text passwords in the shell command
 history.
 You can achieve this using a \f[C]\&.netrc\f[]
-file (http://stackoverflow.com/tags/.netrc/info) on a per extractor
+file (https://stackoverflow.com/tags/.netrc/info) on a per extractor
 basis.
 For that you will need to create a \f[C]\&.netrc\f[] file in your
 \f[C]$HOME\f[] and restrict permissions to read/write by only you:
@@ -989,6 +990,13 @@ file (#configuration).
 .PP
 On Windows you may also need to setup the \f[C]%HOME%\f[] environment
 variable manually.
+For example:
+.IP
+.nf
+\f[C]
+set\ HOME=%USERPROFILE%
+\f[]
+.fi
 .SH OUTPUT TEMPLATE
 .PP
 The \f[C]\-o\f[] option allows users to indicate a template for the
@@ -998,7 +1006,7 @@ output file names.
 .PP
 The basic usage is not to set any template arguments when downloading a
 single file, like in
-\f[C]youtube\-dl\ \-o\ funny_video.flv\ "http://some/video"\f[].
+\f[C]youtube\-dl\ \-o\ funny_video.flv\ "https://some/video"\f[].
 However, it may contain special sequences that will be replaced when
 downloading each video.
 The special sequences may be formatted according to python string
@@ -1114,32 +1122,60 @@ padded with leading zeros according to the total length of the playlist
 \f[C]playlist_title\f[] (string): Playlist title
 .PP
 Available for the video that belongs to some logical chapter or section:
-\- \f[C]chapter\f[] (string): Name or title of the chapter the video
-belongs to \- \f[C]chapter_number\f[] (numeric): Number of the chapter
-the video belongs to \- \f[C]chapter_id\f[] (string): Id of the chapter
-the video belongs to
+.IP \[bu] 2
+\f[C]chapter\f[] (string): Name or title of the chapter the video
+belongs to
+.IP \[bu] 2
+\f[C]chapter_number\f[] (numeric): Number of the chapter the video
+belongs to
+.IP \[bu] 2
+\f[C]chapter_id\f[] (string): Id of the chapter the video belongs to
 .PP
 Available for the video that is an episode of some series or programme:
-\- \f[C]series\f[] (string): Title of the series or programme the video
-episode belongs to \- \f[C]season\f[] (string): Title of the season the
-video episode belongs to \- \f[C]season_number\f[] (numeric): Number of
-the season the video episode belongs to \- \f[C]season_id\f[] (string):
-Id of the season the video episode belongs to \- \f[C]episode\f[]
-(string): Title of the video episode \- \f[C]episode_number\f[]
-(numeric): Number of the video episode within a season \-
+.IP \[bu] 2
+\f[C]series\f[] (string): Title of the series or programme the video
+episode belongs to
+.IP \[bu] 2
+\f[C]season\f[] (string): Title of the season the video episode belongs
+to
+.IP \[bu] 2
+\f[C]season_number\f[] (numeric): Number of the season the video episode
+belongs to
+.IP \[bu] 2
+\f[C]season_id\f[] (string): Id of the season the video episode belongs
+to
+.IP \[bu] 2
+\f[C]episode\f[] (string): Title of the video episode
+.IP \[bu] 2
+\f[C]episode_number\f[] (numeric): Number of the video episode within a
+season
+.IP \[bu] 2
 \f[C]episode_id\f[] (string): Id of the video episode
 .PP
-Available for the media that is a track or a part of a music album: \-
-\f[C]track\f[] (string): Title of the track \- \f[C]track_number\f[]
-(numeric): Number of the track within an album or a disc \-
-\f[C]track_id\f[] (string): Id of the track \- \f[C]artist\f[] (string):
-Artist(s) of the track \- \f[C]genre\f[] (string): Genre(s) of the track
-\- \f[C]album\f[] (string): Title of the album the track belongs to \-
-\f[C]album_type\f[] (string): Type of the album \- \f[C]album_artist\f[]
-(string): List of all artists appeared on the album \-
+Available for the media that is a track or a part of a music album:
+.IP \[bu] 2
+\f[C]track\f[] (string): Title of the track
+.IP \[bu] 2
+\f[C]track_number\f[] (numeric): Number of the track within an album or
+a disc
+.IP \[bu] 2
+\f[C]track_id\f[] (string): Id of the track
+.IP \[bu] 2
+\f[C]artist\f[] (string): Artist(s) of the track
+.IP \[bu] 2
+\f[C]genre\f[] (string): Genre(s) of the track
+.IP \[bu] 2
+\f[C]album\f[] (string): Title of the album the track belongs to
+.IP \[bu] 2
+\f[C]album_type\f[] (string): Type of the album
+.IP \[bu] 2
+\f[C]album_artist\f[] (string): List of all artists appeared on the
+album
+.IP \[bu] 2
 \f[C]disc_number\f[] (numeric): Number of the disc or other physical
-medium the track belongs to \- \f[C]release_year\f[] (numeric): Year
-(YYYY) when the album was released
+medium the track belongs to
+.IP \[bu] 2
+\f[C]release_year\f[] (numeric): Year (YYYY) when the album was released
 .PP
 Each aforementioned sequence when referenced in an output template will
 be replaced by the actual value corresponding to the sequence name.
@@ -1185,7 +1221,8 @@ environment variables for expansion should stay intact:
 \f[C]\-o\ "C:\\%HOMEPATH%\\Desktop\\%%(title)s.%%(ext)s"\f[].
 .SS Output template examples
 .PP
-Note on Windows you may need to use double quotes instead of single.
+Note that on Windows you may need to use double quotes instead of
+single.
 .IP
 .nf
 \f[C]
@@ -1205,7 +1242,7 @@ $\ youtube\-dl\ \-o\ \[aq]%(uploader)s/%(playlist)s/%(playlist_index)s\ \-\ %(ti
 $\ youtube\-dl\ \-u\ user\ \-p\ password\ \-o\ \[aq]~/MyVideos/%(playlist)s/%(chapter_number)s\ \-\ %(chapter)s/%(title)s.%(ext)s\[aq]\ https://www.udemy.com/java\-tutorial/
 
 #\ Download\ entire\ series\ season\ keeping\ each\ series\ and\ each\ season\ in\ separate\ directory\ under\ C:/MyVideos
-$\ youtube\-dl\ \-o\ "C:/MyVideos/%(series)s/%(season_number)s\ \-\ %(season)s/%(episode_number)s\ \-\ %(episode)s.%(ext)s"\ http://videomore.ru/kino_v_detalayah/5_sezon/367617
+$\ 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
 
 #\ Stream\ the\ video\ being\ downloaded\ to\ stdout
 $\ youtube\-dl\ \-o\ \-\ BaW_jenozKc
@@ -1303,9 +1340,9 @@ in use \- \f[C]vcodec\f[]: Name of the video codec in use \-
 \f[C]container\f[]: Name of the container format \- \f[C]protocol\f[]:
 The protocol that will be used for the actual download, lower\-case
 (\f[C]http\f[], \f[C]https\f[], \f[C]rtsp\f[], \f[C]rtmp\f[],
-\f[C]rtmpe\f[], \f[C]mms\f[], \f[C]f4m\f[], \f[C]ism\f[], \f[C]m3u8\f[],
-or \f[C]m3u8_native\f[]) \- \f[C]format_id\f[]: A short description of
-the format
+\f[C]rtmpe\f[], \f[C]mms\f[], \f[C]f4m\f[], \f[C]ism\f[],
+\f[C]http_dash_segments\f[], \f[C]m3u8\f[], or \f[C]m3u8_native\f[]) \-
+\f[C]format_id\f[]: A short description of the format
 .PP
 Note that none of the aforementioned meta fields are guaranteed to be
 present since this solely depends on the metadata obtained by particular
@@ -1360,7 +1397,8 @@ You may want to add it to the configuration file (#configuration) in
 order not to type it every time you run youtube\-dl.
 .SS Format selection examples
 .PP
-Note on Windows you may need to use double quotes instead of single.
+Note that on Windows you may need to use double quotes instead of
+single.
 .IP
 .nf
 \f[C]
@@ -1412,7 +1450,7 @@ $\ youtube\-dl\ \-\-dateafter\ 20000101\ \-\-datebefore\ 20091231
 .SS How do I update youtube\-dl?
 .PP
 If you\[aq]ve followed our manual installation
-instructions (http://rg3.github.io/youtube-dl/download.html), you can
+instructions (https://rg3.github.io/youtube-dl/download.html), you can
 simply run \f[C]youtube\-dl\ \-U\f[] (or, on Linux,
 \f[C]sudo\ youtube\-dl\ \-U\f[]).
 .PP
@@ -1425,7 +1463,7 @@ mechanism to update.
 Note that distribution packages are often outdated.
 As a rule of thumb, youtube\-dl releases at least once a month, and
 often weekly or even daily.
-Simply go to http://yt\-dl.org/ to find out the current version.
+Simply go to https://yt\-dl.org to find out the current version.
 Unfortunately, there is nothing we youtube\-dl developers can do if your
 distribution serves a really outdated version.
 You can (and should) complain to your distribution in their bugtracker
@@ -1442,7 +1480,7 @@ sudo\ apt\-get\ remove\ \-y\ youtube\-dl
 .fi
 .PP
 Afterwards, simply follow our manual installation
-instructions (http://rg3.github.io/youtube-dl/download.html):
+instructions (https://rg3.github.io/youtube-dl/download.html):
 .IP
 .nf
 \f[C]
@@ -1525,12 +1563,13 @@ automatically pick the best option.
 Videos or video formats streamed via RTMP protocol can only be
 downloaded when rtmpdump (https://rtmpdump.mplayerhq.hu/) is installed.
 Downloading MMS and RTSP videos requires either
-mplayer (http://mplayerhq.hu/) or mpv (https://mpv.io/) to be installed.
+mplayer (https://mplayerhq.hu/) or mpv (https://mpv.io/) to be
+installed.
 .SS I have downloaded a video but how can I play it?
 .PP
 Once the video is fully downloaded, use any video player, such as
-mpv (https://mpv.io/), vlc (http://www.videolan.org/) or
-mplayer (http://www.mplayerhq.hu/).
+mpv (https://mpv.io/), vlc (https://www.videolan.org/) or
+mplayer (https://www.mplayerhq.hu/).
 .SS I extracted a video URL with \f[C]\-g\f[], but it does not play on
 another machine / in my web browser.
 .PP
@@ -1663,13 +1702,13 @@ If you want this for all of your downloads, put the option into your
 configuration file (#configuration).
 .SS How do I download a video starting with a \f[C]\-\f[]?
 .PP
-Either prepend \f[C]http://www.youtube.com/watch?v=\f[] or separate the
+Either prepend \f[C]https://www.youtube.com/watch?v=\f[] or separate the
 ID from the options with \f[C]\-\-\f[]:
 .IP
 .nf
 \f[C]
 youtube\-dl\ \-\-\ \-wNyEUrxzFU
-youtube\-dl\ "http://www.youtube.com/watch?v=\-wNyEUrxzFU"
+youtube\-dl\ "https://www.youtube.com/watch?v=\-wNyEUrxzFU"
 \f[]
 .fi
 .SS How do I pass cookies to youtube\-dl?
@@ -1708,12 +1747,12 @@ YouTube, CloudFlare).
 You will first need to tell youtube\-dl to stream media to stdout with
 \f[C]\-o\ \-\f[], and also tell your media player to read from stdin (it
 must be capable of this for streaming) and then pipe former to latter.
-For example, streaming to vlc (http://www.videolan.org/) can be achieved
-with:
+For example, streaming to vlc (https://www.videolan.org/) can be
+achieved with:
 .IP
 .nf
 \f[C]
-youtube\-dl\ \-o\ \-\ "http://www.youtube.com/watch?v=BaW_jenozKcj"\ |\ vlc\ \-
+youtube\-dl\ \-o\ \-\ "https://www.youtube.com/watch?v=BaW_jenozKcj"\ |\ vlc\ \-
 \f[]
 .fi
 .SS How do I download only new videos from a playlist?
@@ -1761,8 +1800,8 @@ improvements of the built\-in downloader and/or ffmpeg.
 .PP
 In particular, the generic extractor (used when your website is not in
 the list of supported sites by
-youtube\-dl (http://rg3.github.io/youtube-dl/supportedsites.html) cannot
-mandate one specific downloader.
+youtube\-dl (https://rg3.github.io/youtube-dl/supportedsites.html)
+cannot mandate one specific downloader.
 .PP
 If you put either \f[C]\-\-hls\-prefer\-native\f[] or
 \f[C]\-\-hls\-prefer\-ffmpeg\f[] into your configuration, a different
@@ -1829,8 +1868,8 @@ Please do not declare your issue as \f[C]important\f[] or
 For one, have a look at the list of supported
 sites (docs/supportedsites.md).
 Note that it can sometimes happen that the site changes its URL scheme
-(say, from http://example.com/video/1234567 to
-http://example.com/v/1234567 ) and youtube\-dl reports an URL of a
+(say, from https://example.com/video/1234567 to
+https://example.com/v/1234567 ) and youtube\-dl reports an URL of a
 service in that list as unsupported.
 In that case, simply report a bug.
 .PP
@@ -1875,7 +1914,7 @@ such as checking that your version of youtube\-dl is current.
 .SH DEVELOPER INSTRUCTIONS
 .PP
 Most users do not need to build youtube\-dl and can download the
-builds (http://rg3.github.io/youtube-dl/download.html) or get them from
+builds (https://rg3.github.io/youtube-dl/download.html) or get them from
 their distribution.
 .PP
 To run youtube\-dl as a developer, you don\[aq]t need to build anything
@@ -1899,6 +1938,9 @@ nosetests
 \f[]
 .fi
 .PP
+See item 6 of new extractor tutorial (#adding-support-for-a-new-site)
+for how to run extractor specific test cases.
+.PP
 If you want to create a build of youtube\-dl yourself, you\[aq]ll need
 .IP \[bu] 2
 python
@@ -1960,7 +2002,7 @@ from\ .common\ import\ InfoExtractor
 class\ YourExtractorIE(InfoExtractor):
 \ \ \ \ _VALID_URL\ =\ r\[aq]https?://(?:www\\.)?yourextractor\\.com/watch/(?P<id>[0\-9]+)\[aq]
 \ \ \ \ _TEST\ =\ {
-\ \ \ \ \ \ \ \ \[aq]url\[aq]:\ \[aq]http://yourextractor.com/watch/42\[aq],
+\ \ \ \ \ \ \ \ \[aq]url\[aq]:\ \[aq]https://yourextractor.com/watch/42\[aq],
 \ \ \ \ \ \ \ \ \[aq]md5\[aq]:\ \[aq]TODO:\ md5\ sum\ of\ the\ first\ 10241\ bytes\ of\ the\ video\ file\ (use\ \-\-test)\[aq],
 \ \ \ \ \ \ \ \ \[aq]info_dict\[aq]:\ {
 \ \ \ \ \ \ \ \ \ \ \ \ \[aq]id\[aq]:\ \[aq]42\[aq],
@@ -2005,6 +2047,8 @@ If you decide to add more than one test, then rename \f[C]_TEST\f[] to
 The tests will then be named \f[C]TestDownload.test_YourExtractor\f[],
 \f[C]TestDownload.test_YourExtractor_1\f[],
 \f[C]TestDownload.test_YourExtractor_2\f[], etc.
+Note that tests with \f[C]only_matching\f[] key in test\[aq]s dict are
+not counted in.
 .IP " 7." 4
 Have a look at
 \f[C]youtube_dl/extractor/common.py\f[] (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/extractor/common.py)
@@ -2016,12 +2060,13 @@ Add tests and code for as many as you want.
 Make sure your code follows youtube\-dl coding
 conventions (#youtube-dl-coding-conventions) and check the code with
 flake8 (https://pypi.python.org/pypi/flake8).
-Also make sure your code works under all Python (http://www.python.org/)
-versions claimed supported by youtube\-dl, namely 2.6, 2.7, and 3.2+.
+Also make sure your code works under all
+Python (https://www.python.org/) versions claimed supported by
+youtube\-dl, namely 2.6, 2.7, and 3.2+.
 .IP " 9." 4
-When the tests pass, add (http://git-scm.com/docs/git-add) the new files
-and commit (http://git-scm.com/docs/git-commit) them and
-push (http://git-scm.com/docs/git-push) the result, like this:
+When the tests pass, add (https://git-scm.com/docs/git-add) the new
+files and commit (https://git-scm.com/docs/git-commit) them and
+push (https://git-scm.com/docs/git-push) the result, like this:
 .RS 4
 .IP
 .nf
@@ -2272,13 +2317,13 @@ import\ youtube_dl
 
 ydl_opts\ =\ {}
 with\ youtube_dl.YoutubeDL(ydl_opts)\ as\ ydl:
-\ \ \ \ ydl.download([\[aq]http://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
+\ \ \ \ ydl.download([\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
 \f[]
 .fi
 .PP
 Most likely, you\[aq]ll want to use various options.
 For a list of options available, have a look at
-\f[C]youtube_dl/YoutubeDL.py\f[] (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/YoutubeDL.py#L129-L279).
+\f[C]youtube_dl/YoutubeDL.py\f[] (https://github.com/rg3/youtube-dl/blob/3e4cedf9e8cd3157df2457df7274d0c842421945/youtube_dl/YoutubeDL.py#L137-L312).
 For a start, if you want to intercept youtube\-dl\[aq]s output, set a
 \f[C]logger\f[] object.
 .PP
@@ -2319,7 +2364,7 @@ ydl_opts\ =\ {
 \ \ \ \ \[aq]progress_hooks\[aq]:\ [my_hook],
 }
 with\ youtube_dl.YoutubeDL(ydl_opts)\ as\ ydl:
-\ \ \ \ ydl.download([\[aq]http://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
+\ \ \ \ ydl.download([\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
 \f[]
 .fi
 .SH BUGS
@@ -2331,7 +2376,7 @@ GitHub fails to accept the bug report), please do not send bug reports
 via personal email.
 For discussions, join us in the IRC channel
 #youtube\-dl (irc://chat.freenode.net/#youtube-dl) on freenode
-(webchat (http://webchat.freenode.net/?randomnick=1&channels=youtube-dl)).
+(webchat (https://webchat.freenode.net/?randomnick=1&channels=youtube-dl)).
 .PP
 \f[B]Please include the full output of youtube\-dl when run with
 \f[C]\-v\f[]\f[], i.e.
@@ -2345,7 +2390,7 @@ It should look similar to this:
 $\ youtube\-dl\ \-v\ <your\ command\ line>
 [debug]\ System\ config:\ []
 [debug]\ User\ config:\ []
-[debug]\ Command\-line\ args:\ [u\[aq]\-v\[aq],\ u\[aq]http://www.youtube.com/watch?v=BaW_jenozKcj\[aq]]
+[debug]\ Command\-line\ args:\ [u\[aq]\-v\[aq],\ u\[aq]https://www.youtube.com/watch?v=BaW_jenozKcj\[aq]]
 [debug]\ Encodings:\ locale\ cp1251,\ fs\ mbcs,\ out\ cp866,\ pref\ cp1251
 [debug]\ youtube\-dl\ version\ 2015.12.06
 [debug]\ Git\ HEAD:\ 135392e
@@ -2410,11 +2455,11 @@ command\-line) or upload the \f[C]\&.dump\f[] files you get when you add
 .PP
 \f[B]Site support requests must contain an example URL\f[].
 An example URL is a URL you might want to download, like
-\f[C]http://www.youtube.com/watch?v=BaW_jenozKc\f[].
+\f[C]https://www.youtube.com/watch?v=BaW_jenozKc\f[].
 There should be an obvious video present.
 Except under very special circumstances, the main page of a video
 service (e.g.
-\f[C]http://www.youtube.com/\f[]) is \f[I]not\f[] an example URL.
+\f[C]https://www.youtube.com/\f[]) is \f[I]not\f[] an example URL.
 .SS Are you using the latest version?
 .PP
 Before reporting any issue, type \f[C]youtube\-dl\ \-U\f[].