X-Git-Url: https://git.rapsys.eu/youtubedl/blobdiff_plain/abc36f0474141930338eef35e2444365fab932b6..80893415fd8cecb59cb8ffbea17a183d4202f02e:/youtube-dl.1?ds=inline diff --git a/youtube-dl.1 b/youtube-dl.1 index d4c0ab5..9ab22b0 100644 --- a/youtube-dl.1 +++ b/youtube-dl.1 @@ -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. @@ -297,13 +297,13 @@ Number of retries (default is 10), or "infinite". .RE .TP .B \-\-fragment\-retries \f[I]RETRIES\f[] -Number of retries for a fragment (default is 10), or "infinite" (DASH -and hlsnative only) +Number of retries for a fragment (default is 10), or "infinite" (DASH, +hlsnative and ISM) .RS .RE .TP .B \-\-skip\-unavailable\-fragments -Skip unavailable fragments (DASH and hlsnative only) +Skip unavailable fragments (DASH, hlsnative and ISM) .RS .RE .TP @@ -312,6 +312,12 @@ Abort downloading when some fragment is not available .RS .RE .TP +.B \-\-keep\-fragments +Keep downloaded fragments on disk after downloading is finished; +fragments are erased by default +.RS +.RE +.TP .B \-\-buffer\-size \f[I]SIZE\f[] Size of download buffer (e.g. 1024 or 16K) (default is 1024) @@ -544,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 @@ -841,12 +847,14 @@ Write metadata to the video file .TP .B \-\-metadata\-from\-title \f[I]FORMAT\f[] Parse additional metadata like song title / artist from the video title. -The format syntax is the same as \-\-output, the parsed parameters -replace existing values. -Additional templates: %(album)s, %(artist)s. -Example: \-\-metadata\-from\-title "%(artist)s \- %(title)s" matches a -title like "Coldplay \- Paradise" +The format syntax is the same as \-\-output. +Regular expression with named capture groups may also be used. +The parsed parameters replace existing values. +Example: \-\-metadata\-from\- title "%(artist)s \- %(title)s" matches a +title like "Coldplay \- Paradise". +Example (regex): \-\-metadata\-from\-title "(?P.+?) \- (?P .RS +\&.+)" .RE .TP .B \-\-xattrs @@ -886,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 @@ -944,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: @@ -981,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 @@ -990,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 @@ -1106,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. @@ -1177,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] @@ -1197,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 @@ -1295,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 @@ -1352,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] @@ -1404,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 @@ -1417,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 @@ -1434,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] @@ -1517,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 @@ -1655,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? @@ -1700,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? @@ -1753,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 @@ -1821,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 @@ -1867,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 @@ -1891,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 @@ -1952,7 +2002,7 @@ from\ .common\ import\ InfoExtractor class\ YourExtractorIE(InfoExtractor): \ \ \ \ _VALID_URL\ =\ r\[aq]https?://(?:www\\.)?yourextractor\\.com/watch/(?P[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], @@ -1997,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) @@ -2008,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 @@ -2264,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 @@ -2311,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 @@ -2323,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. @@ -2337,7 +2390,7 @@ It should look similar to this: $\ youtube\-dl\ \-v\ [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 @@ -2402,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[].