diff options
Diffstat (limited to 'network/youtube-dl/youtube-dl.1')
| -rw-r--r-- | network/youtube-dl/youtube-dl.1 | 173 |
1 files changed, 89 insertions, 84 deletions
diff --git a/network/youtube-dl/youtube-dl.1 b/network/youtube-dl/youtube-dl.1 index dae0b61e23..353ea4d338 100644 --- a/network/youtube-dl/youtube-dl.1 +++ b/network/youtube-dl/youtube-dl.1 @@ -927,9 +927,10 @@ 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 per extractor basis. +file (http://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 you only: +\f[C]$HOME\f[] and restrict permissions to read/write by only you: .IP .nf \f[C] @@ -938,8 +939,9 @@ chmod\ a\-rwx,u+rw\ $HOME/.netrc \f[] .fi .PP -After that you can add credentials for extractor in the following -format, where \f[I]extractor\f[] is the name of extractor in lowercase: +After that you can add credentials for an extractor in the following +format, where \f[I]extractor\f[] is the name of the extractor in +lowercase: .IP .nf \f[C] @@ -1104,25 +1106,25 @@ belongs to \- \f[C]album_type\f[]: Type of the album \- track belongs to \- \f[C]release_year\f[]: Year (YYYY) when the album was released .PP -Each aforementioned sequence when referenced in output template will be -replaced by the actual value corresponding to the sequence name. +Each aforementioned sequence when referenced in an output template will +be replaced by the actual value corresponding to the sequence name. Note that some of the sequences are not guaranteed to be present since -they depend on the metadata obtained by particular extractor, such -sequences will be replaced with \f[C]NA\f[]. +they depend on the metadata obtained by a particular extractor. +Such sequences will be replaced with \f[C]NA\f[]. .PP -For example for \f[C]\-o\ %(title)s\-%(id)s.%(ext)s\f[] and mp4 video +For example for \f[C]\-o\ %(title)s\-%(id)s.%(ext)s\f[] and an mp4 video with title \f[C]youtube\-dl\ test\ video\f[] and id -\f[C]BaW_jenozKcj\f[] this will result in a +\f[C]BaW_jenozKcj\f[], this will result in a \f[C]youtube\-dl\ test\ video\-BaW_jenozKcj.mp4\f[] file created in the current directory. .PP -Output template can also contain arbitrary hierarchical path, e.g. +Output templates can also contain arbitrary hierarchical path, e.g. \f[C]\-o\ \[aq]%(playlist)s/%(playlist_index)s\ \-\ %(title)s.%(ext)s\[aq]\f[] -that will result in downloading each video in a directory corresponding +which will result in downloading each video in a directory corresponding to this path template. Any missing directory will be automatically created for you. .PP -To specify percent literal in output template use \f[C]%%\f[]. +To use percent literals in an output template use \f[C]%%\f[]. To output to stdout use \f[C]\-o\ \-\f[]. .PP The current default template is \f[C]%(title)s\-%(id)s.%(ext)s\f[]. @@ -1134,7 +1136,7 @@ In these cases, add the \f[C]\-\-restrict\-filenames\f[] flag to get a shorter title: .SS Output template and Windows batch files .PP -If you are using output template inside a Windows batch file then you +If you are using an output template inside a Windows batch file then you must escape plain percent characters (\f[C]%\f[]) by doubling, so that \f[C]\-o\ "%(title)s\-%(id)s.%(ext)s"\f[] should become \f[C]\-o\ "%%(title)s\-%%(id)s.%%(ext)s"\f[]. @@ -1179,7 +1181,7 @@ special options, youtube\-dl will guess it for you by \f[B]default\f[]. .PP But sometimes you may want to download in a different format, for example when you are on a slow or intermittent connection. -The key mechanism for achieving this is so called \f[I]format +The key mechanism for achieving this is so\-called \f[I]format selection\f[] based on which you can explicitly specify desired format, select formats based on some criterion or criteria, setup precedence and much more. @@ -1201,24 +1203,28 @@ Note that these format codes are extractor specific. .PP You can also use a file extension (currently \f[C]3gp\f[], \f[C]aac\f[], \f[C]flv\f[], \f[C]m4a\f[], \f[C]mp3\f[], \f[C]mp4\f[], \f[C]ogg\f[], -\f[C]wav\f[], \f[C]webm\f[] are supported) to download best quality -format of particular file extension served as a single file, e.g. -\f[C]\-f\ webm\f[] will download best quality format with \f[C]webm\f[] -extension served as a single file. -.PP -You can also use special names to select particular edge case format: \- -\f[C]best\f[]: Select best quality format represented by single file -with video and audio \- \f[C]worst\f[]: Select worst quality format -represented by single file with video and audio \- \f[C]bestvideo\f[]: -Select best quality video only format (e.g. -DASH video), may not be available \- \f[C]worstvideo\f[]: Select worst -quality video only format, may not be available \- \f[C]bestaudio\f[]: -Select best quality audio only format, may not be available \- -\f[C]worstaudio\f[]: Select worst quality audio only format, may not be -available -.PP -For example, to download worst quality video only format you can use -\f[C]\-f\ worstvideo\f[]. +\f[C]wav\f[], \f[C]webm\f[] are supported) to download the best quality +format of a particular file extension served as a single file, e.g. +\f[C]\-f\ webm\f[] will download the best quality format with the +\f[C]webm\f[] extension served as a single file. +.PP +You can also use special names to select particular edge case formats: +\- \f[C]best\f[]: Select the best quality format represented by a single +file with video and audio. +\- \f[C]worst\f[]: Select the worst quality format represented by a +single file with video and audio. +\- \f[C]bestvideo\f[]: Select the best quality video\-only format (e.g. +DASH video). +May not be available. +\- \f[C]worstvideo\f[]: Select the worst quality video\-only format. +May not be available. +\- \f[C]bestaudio\f[]: Select the best quality audio only\-format. +May not be available. +\- \f[C]worstaudio\f[]: Select the worst quality audio only\-format. +May not be available. +.PP +For example, to download the worst quality video\-only format you can +use \f[C]\-f\ worstvideo\f[]. .PP If you want to download multiple videos and they don\[aq]t have the same formats available, you can specify the order of preference using @@ -1230,11 +1236,11 @@ otherwise it will download format 17 if it\[aq]s available, otherwise it will download format 18 if it\[aq]s available, otherwise it will complain that no suitable formats are available for download. .PP -If you want to download several formats of the same video use comma as a -separator, e.g. +If you want to download several formats of the same video use a comma as +a separator, e.g. \f[C]\-f\ 22,17,18\f[] will download all these three formats, of course if they are available. -Or more sophisticated example combined with precedence feature +Or a more sophisticated example combined with the precedence feature: \f[C]\-f\ 136/137/mp4/bestvideo,140/m4a/bestaudio\f[]. .PP You can also filter the video formats by putting a condition in @@ -1264,7 +1270,7 @@ The protocol that will be used for the actual download, lower\-case. Note that none of the aforementioned meta fields are guaranteed to be present since this solely depends on the metadata obtained by particular extractor, i.e. -the metadata offered by video hoster. +the metadata offered by the video hoster. .PP Formats for which the value is not known are excluded unless you put a question mark (\f[C]?\f[]) after the operator. @@ -1276,16 +1282,16 @@ KBit/s. You can merge the video and audio of two formats into a single file using \f[C]\-f\ <video\-format>+<audio\-format>\f[] (requires ffmpeg or avconv installed), for example \f[C]\-f\ bestvideo+bestaudio\f[] will -download best video only format, best audio only format and mux them -together with ffmpeg/avconv. +download the best video\-only format, the best audio\-only format and +mux them together with ffmpeg/avconv. .PP Format selectors can also be grouped using parentheses, for example if you want to download the best mp4 and webm formats with a height lower than 480 you can use \f[C]\-f\ \[aq](mp4,webm)[height<480]\[aq]\f[]. .PP -Since the end of April 2015 and version 2015.04.26 youtube\-dl uses -\f[C]\-f\ bestvideo+bestaudio/best\f[] as default format selection (see -#5447 (https://github.com/rg3/youtube-dl/issues/5447), +Since the end of April 2015 and version 2015.04.26, youtube\-dl uses +\f[C]\-f\ bestvideo+bestaudio/best\f[] as the default format selection +(see #5447 (https://github.com/rg3/youtube-dl/issues/5447), #5456 (https://github.com/rg3/youtube-dl/issues/5456)). If ffmpeg or avconv are installed this results in downloading \f[C]bestvideo\f[] and \f[C]bestaudio\f[] separately and muxing them @@ -1809,7 +1815,7 @@ Before we had the issue template, despite our extensive bug reporting instructions (#bugs), about 80% of the issue reports we got were useless, for instance because people used ancient versions hundreds of releases old, because of simple syntactic errors (not in youtube\-dl but -in general shell usage), because the problem was alrady reported +in general shell usage), because the problem was already reported multiple times before, because people did not actually read an error message, even if it said "please install ffmpeg", because people did not mention the URL they were trying to download and many more simple, @@ -1855,7 +1861,7 @@ If you want to create a build of youtube\-dl yourself, you\[aq]ll need .IP \[bu] 2 python .IP \[bu] 2 -make (both GNU make and BSD make are supported) +make (only GNU make is supported) .IP \[bu] 2 pandoc .IP \[bu] 2 @@ -1997,28 +2003,28 @@ This section introduces a guide lines for writing idiomatic, robust and future\-proof extractor code. .PP Extractors are very fragile by nature since they depend on the layout of -the source data provided by 3rd party media hoster out of your control -and this layout tend to change. +the source data provided by 3rd party media hosters out of your control +and this layout tends to change. As an extractor implementer your task is not only to write code that will extract media links and metadata correctly but also to minimize -code dependency on source\[aq]s layout changes and even to make the code -foresee potential future changes and be ready for that. -This is important because it will allow extractor not to break on minor -layout changes thus keeping old youtube\-dl versions working. +dependency on the source\[aq]s layout and even to make the code foresee +potential future changes and be ready for that. +This is important because it will allow the extractor not to break on +minor layout changes thus keeping old youtube\-dl versions working. Even though this breakage issue is easily fixed by emitting a new -version of youtube\-dl with fix incorporated all the previous version -become broken in all repositories and distros\[aq] packages that may not -be so prompt in fetching the update from us. -Needless to say some may never receive an update at all that is possible -for non rolling release distros. +version of youtube\-dl with a fix incorporated, all the previous +versions become broken in all repositories and distros\[aq] packages +that may not be so prompt in fetching the update from us. +Needless to say, some non rolling release distros may never receive an +update at all. .SS Mandatory and optional metafields .PP For extraction to work youtube\-dl relies on metadata your extractor -extracts and provides to youtube\-dl expressed by information +extracts and provides to youtube\-dl expressed by an information dictionary (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/extractor/common.py#L75-L257) or simply \f[I]info dict\f[]. -Only the following meta fields in \f[I]info dict\f[] are considered -mandatory for successful extraction process by youtube\-dl: +Only the following meta fields in the \f[I]info dict\f[] are considered +mandatory for a successful extraction process by youtube\-dl: .IP \[bu] 2 \f[C]id\f[] (media identifier) .IP \[bu] 2 @@ -2030,15 +2036,15 @@ In fact only the last option is technically mandatory (i.e. if you can\[aq]t figure out the download location of the media the extraction does not make any sense). But by convention youtube\-dl also treats \f[C]id\f[] and \f[C]title\f[] -to be mandatory. -Thus aforementioned metafields are the critical data the extraction does -not make any sense without and if any of them fail to be extracted then -extractor is considered completely broken. +as mandatory. +Thus the aforementioned metafields are the critical data that the +extraction does not make any sense without and if any of them fail to be +extracted then the extractor is considered completely broken. .PP Any field (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/extractor/common.py#L149-L257) apart from the aforementioned ones are considered \f[B]optional\f[]. -That means that extraction should be \f[B]tolerate\f[] to situations +That means that extraction should be \f[B]tolerant\f[] to situations when sources for these fields can potentially be unavailable (even if they are always available at the moment) and \f[B]future\-proof\f[] in order not to break the extraction of general purpose mandatory fields. @@ -2065,9 +2071,9 @@ Assume at this point \f[C]meta\f[]\[aq]s layout is: \f[] .fi .PP -Assume you want to extract \f[C]summary\f[] and put into resulting info -dict as \f[C]description\f[]. -Since \f[C]description\f[] is optional metafield you should be ready +Assume you want to extract \f[C]summary\f[] and put it into the +resulting info dict as \f[C]description\f[]. +Since \f[C]description\f[] is an optional metafield you should be ready that this key may be missing from the \f[C]meta\f[] dict, so that you should extract it like: .IP @@ -2086,10 +2092,10 @@ description\ =\ meta[\[aq]summary\[aq]]\ \ #\ incorrect .fi .PP The latter will break extraction process with \f[C]KeyError\f[] if -\f[C]summary\f[] disappears from \f[C]meta\f[] at some time later but -with former approach extraction will just go ahead with -\f[C]description\f[] set to \f[C]None\f[] that is perfectly fine -(remember \f[C]None\f[] is equivalent for absence of data). +\f[C]summary\f[] disappears from \f[C]meta\f[] at some later time but +with the former approach extraction will just go ahead with +\f[C]description\f[] set to \f[C]None\f[] which is perfectly fine +(remember \f[C]None\f[] is equivalent to the absence of data). .PP Similarly, you should pass \f[C]fatal=False\f[] when extracting optional data from a webpage with \f[C]_search_regex\f[], @@ -2119,20 +2125,19 @@ description\ =\ self._search_regex( .PP On failure this code will silently continue the extraction with \f[C]description\f[] set to \f[C]None\f[]. -That is useful for metafields that are known to may or may not be -present. +That is useful for metafields that may or may not be present. .SS Provide fallbacks .PP -When extracting metadata try to provide several scenarios for that. -For example if \f[C]title\f[] is present in several places/sources try +When extracting metadata try to do so from multiple sources. +For example if \f[C]title\f[] is present in several places, try extracting from at least some of them. -This would make it more future\-proof in case some of the sources became +This makes it more future\-proof in case some of the sources become unavailable. .SS Example .PP -Say \f[C]meta\f[] from previous example has a \f[C]title\f[] and you are -about to extract it. -Since \f[C]title\f[] is mandatory meta field you should end up with +Say \f[C]meta\f[] from the previous example has a \f[C]title\f[] and you +are about to extract it. +Since \f[C]title\f[] is a mandatory meta field you should end up with something like: .IP .nf @@ -2142,7 +2147,7 @@ title\ =\ meta[\[aq]title\[aq]] .fi .PP If \f[C]title\f[] disappeares from \f[C]meta\f[] in future due to some -changes on hoster\[aq]s side the extraction would fail since +changes on the hoster\[aq]s side the extraction would fail since \f[C]title\f[] is mandatory. That\[aq]s expected. .PP @@ -2190,7 +2195,7 @@ title\ =\ self._search_regex( \f[] .fi .PP -Note how you tolerate potential changes in \f[C]style\f[] +Note how you tolerate potential changes in the \f[C]style\f[] attribute\[aq]s value or switch from using double quotes to single for \f[C]class\f[] attribute: .PP @@ -2279,7 +2284,7 @@ with\ youtube_dl.YoutubeDL(ydl_opts)\ as\ ydl: .PP Bugs and suggestions should be reported at: <https://github.com/rg3/youtube-dl/issues>. -Unless you were prompted so or there is another pertinent reason (e.g. +Unless you were prompted to or there is another pertinent reason (e.g. GitHub fails to accept the bug report), please do not send bug reports via personal email. For discussions, join us in the IRC channel @@ -2309,7 +2314,7 @@ $\ youtube\-dl\ \-v\ <your\ command\ line> \f[] .fi .PP -\f[B]Do not post screenshots of verbose log only plain text is +\f[B]Do not post screenshots of verbose logs; only plain text is acceptable.\f[] .PP The output (including the first lines) contains important debugging @@ -2446,8 +2451,8 @@ requires them. .SS Is your question about youtube\-dl? .PP It may sound strange, but some bug reports we receive are completely -unrelated to youtube\-dl and relate to a different or even the -reporter\[aq]s own application. +unrelated to youtube\-dl and relate to a different, or even the +reporter\[aq]s own, application. Please make sure that you are actually using youtube\-dl. If you are using a UI for youtube\-dl, report the bug to the maintainer of the actual application providing the UI. |