Initiate new release.

[youtubedl] / README.txt

diff --git a/README.txt b/README.txt
index 6ba6d68caf747152f10a67810815e53ab85b3b2e..974ea6e1eb242fd7964ba9edbac9f958a141071c 100644 (file)
--- a/README.txt
+++ b/README.txt
@@ -481,9 +481,9 @@ Post-processing Options:
                                      either the path to the binary or its
                                      containing directory.
     --exec CMD                       Execute a command on the file after
                                      either the path to the binary or its
                                      containing directory.
     --exec CMD                       Execute a command on the file after

-                                     downloading, similar to find's -exec
-                                     syntax. Example: --exec 'adb push {}
-                                     /sdcard/Music/ && rm {}'
+                                     downloading and post-processing, similar to
+                                     find's -exec syntax. Example: --exec 'adb
+                                     push {} /sdcard/Music/ && rm {}'

     --convert-subs FORMAT            Convert the subtitles to other format
                                      (currently supported: srt|ass|vtt|lrc)
 
     --convert-subs FORMAT            Convert the subtitles to other format
                                      (currently supported: srt|ass|vtt|lrc)
 


@@ -779,15 +779,20 @@ of a particular file extension served as a single file, e.g. -f webm
 will download the best quality format with the webm extension served as
 a single file.
 
 will download the best quality format with the webm extension served as
 a single file.
 

-You can also use special names to select particular edge case formats: -
-best: Select the best quality format represented by a single file with
-video and audio. - worst: Select the worst quality format represented by
-a single file with video and audio. - bestvideo: Select the best quality
-video-only format (e.g. DASH video). May not be available. - worstvideo:
-Select the worst quality video-only format. May not be available. -
-bestaudio: Select the best quality audio only-format. May not be
-available. - worstaudio: Select the worst quality audio only-format. May
-not be available.
+You can also use special names to select particular edge case formats:
+
+-   best: Select the best quality format represented by a single file
+    with video and audio.
+-   worst: Select the worst quality format represented by a single file
+    with video and audio.
+-   bestvideo: Select the best quality video-only format (e.g. DASH
+    video). May not be available.
+-   worstvideo: Select the worst quality video-only format. May not be
+    available.
+-   bestaudio: Select the best quality audio only-format. May not be
+    available.
+-   worstaudio: Select the worst quality audio only-format. May not be
+    available.

 
 For example, to download the worst quality video-only format you can use
 -f worstvideo.
 
 For example, to download the worst quality video-only format you can use
 -f worstvideo.


@@ -810,20 +815,31 @@ You can also filter the video formats by putting a condition in
 brackets, as in -f "best[height=720]" (or -f "[filesize>10M]").
 
 The following numeric meta fields can be used with comparisons <, <=, >,
 brackets, as in -f "best[height=720]" (or -f "[filesize>10M]").
 
 The following numeric meta fields can be used with comparisons <, <=, >,

->=, = (equals), != (not equals): - filesize: The number of bytes, if
-known in advance - width: Width of the video, if known - height: Height
-of the video, if known - tbr: Average bitrate of audio and video in
-KBit/s - abr: Average audio bitrate in KBit/s - vbr: Average video
-bitrate in KBit/s - asr: Audio sampling rate in Hertz - fps: Frame rate
-
-Also filtering work for comparisons = (equals), != (not equals), ^=
-(begins with), $= (ends with), *= (contains) and following string meta
-fields: - ext: File extension - acodec: Name of the audio codec in use -
-vcodec: Name of the video codec in use - container: Name of the
-container format - protocol: The protocol that will be used for the
-actual download, lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m,
-ism, http_dash_segments, m3u8, or m3u8_native) - format_id: A short
-description of the format
+>=, = (equals), != (not equals):
+
+-   filesize: The number of bytes, if known in advance
+-   width: Width of the video, if known
+-   height: Height of the video, if known
+-   tbr: Average bitrate of audio and video in KBit/s
+-   abr: Average audio bitrate in KBit/s
+-   vbr: Average video bitrate in KBit/s
+-   asr: Audio sampling rate in Hertz
+-   fps: Frame rate
+
+Also filtering work for comparisons = (equals), ^= (starts with), $=
+(ends with), *= (contains) and following string meta fields:
+
+-   ext: File extension
+-   acodec: Name of the audio codec in use
+-   vcodec: Name of the video codec in use
+-   container: Name of the container format
+-   protocol: The protocol that will be used for the actual download,
+    lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, ism,
+    http_dash_segments, m3u8, or m3u8_native)
+-   format_id: A short description of the format
+
+Any string comparison may be prefixed with negation ! in order to
+produce an opposite comparison, e.g. !*= (does not contain).

 
 Note that none of the aforementioned meta fields are guaranteed to be
 present since this solely depends on the metadata obtained by particular
 
 Note that none of the aforementioned meta fields are guaranteed to be
 present since this solely depends on the metadata obtained by particular


@@ -876,7 +892,7 @@ single.
     # Download best mp4 format available or any other best if no mp4 available
     $ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
 
     # Download best mp4 format available or any other best if no mp4 available
     $ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
 

-    # Download best format available but not better that 480p
+    # Download best format available but no better than 480p

     $ youtube-dl -f 'bestvideo[height<=480]+bestaudio/best[height<=480]'
 
     # Download best video only format but no bigger than 50 MB
     $ youtube-dl -f 'bestvideo[height<=480]+bestaudio/best[height<=480]'
 
     # Download best video only format but no bigger than 50 MB


@@ -944,8 +960,8 @@ that, remove the distribution's package, with a line like
 
 Afterwards, simply follow our manual installation instructions:
 
 
 Afterwards, simply follow our manual installation instructions:
 

-    sudo wget https://yt-dl.org/latest/youtube-dl -O /usr/local/bin/youtube-dl
-    sudo chmod a+x /usr/local/bin/youtube-dl
+    sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
+    sudo chmod a+rx /usr/local/bin/youtube-dl

     hash -r
 
 Again, from then on you'll be able to update with sudo youtube-dl -U.
     hash -r
 
 Again, from then on you'll be able to update with sudo youtube-dl -U.


@@ -1085,10 +1101,19 @@ above for how to update youtube-dl.
 HTTP Error 429: Too Many Requests or 402: Payment Required
 
 These two error codes indicate that the service is blocking your IP
 HTTP Error 429: Too Many Requests or 402: Payment Required
 
 These two error codes indicate that the service is blocking your IP

-address because of overuse. Contact the service and ask them to unblock
-your IP address, or - if you have acquired a whitelisted IP address
-already - use the --proxy or --source-address options to select another
-IP address.
+address because of overuse. Usually this is a soft block meaning that
+you can gain access again after solving CAPTCHA. Just open a browser and
+solve a CAPTCHA the service suggests you and after that pass cookies to
+youtube-dl. Note that if your machine has multiple external IPs then you
+should also pass exactly the same IP you've used for solving CAPTCHA
+with --source-address. Also you may need to pass a User-Agent HTTP
+header of your browser with --user-agent.
+
+If this is not the case (no CAPTCHA suggested to solve by the service)
+then you can contact the service and ask them to unblock your IP
+address, or - if you have acquired a whitelisted IP address already -
+use the --proxy or --source-address options to select another IP
+address.

 
 SyntaxError: Non-ASCII character
 
 
 SyntaxError: Non-ASCII character
 


@@ -1632,7 +1657,66 @@ Incorrect:
     'https://www.youtube.com/watch?v=FqZTN594JQw&list='
     'PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4'
 
     'https://www.youtube.com/watch?v=FqZTN594JQw&list='
     'PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4'
 

-Use safe conversion functions
+Inline values
+
+Extracting variables is acceptable for reducing code duplication and
+improving readability of complex expressions. However, you should avoid
+extracting variables used only once and moving them to opposite parts of
+the extractor file, which makes reading the linear flow difficult.
+
+Example
+
+Correct:
+
+    title = self._html_search_regex(r'<title>([^<]+)</title>', webpage, 'title')
+
+Incorrect:
+
+    TITLE_RE = r'<title>([^<]+)</title>'
+    # ...some lines of code...
+    title = self._html_search_regex(TITLE_RE, webpage, 'title')
+
+Collapse fallbacks
+
+Multiple fallback values can quickly become unwieldy. Collapse multiple
+fallback values into a single expression via a list of patterns.
+
+Example
+
+Good:
+
+    description = self._html_search_meta(
+        ['og:description', 'description', 'twitter:description'],
+        webpage, 'description', default=None)
+
+Unwieldy:
+
+    description = (
+        self._og_search_description(webpage, default=None)
+        or self._html_search_meta('description', webpage, default=None)
+        or self._html_search_meta('twitter:description', webpage, default=None))
+
+Methods supporting list of patterns are: _search_regex,
+_html_search_regex, _og_search_property, _html_search_meta.
+
+Trailing parentheses
+
+Always move trailing parentheses after the last argument.
+
+Example
+
+Correct:
+
+        lambda x: x['ResultSet']['Result'][0]['VideoUrlSet']['VideoUrl'],
+        list)
+
+Incorrect:
+
+        lambda x: x['ResultSet']['Result'][0]['VideoUrlSet']['VideoUrl'],
+        list,
+    )
+
+Use convenience conversion and parsing functions

 
 Wrap all extracted numeric data into safe functions from
 youtube_dl/utils.py: int_or_none, float_or_none. Use them for string to
 
 Wrap all extracted numeric data into safe functions from
 youtube_dl/utils.py: int_or_none, float_or_none. Use them for string to


@@ -1642,6 +1726,12 @@ Use url_or_none for safe URL processing.
 
 Use try_get for safe metadata extraction from parsed JSON.
 
 
 Use try_get for safe metadata extraction from parsed JSON.
 

+Use unified_strdate for uniform upload_date or any YYYYMMDD meta field
+extraction, unified_timestamp for uniform timestamp extraction,
+parse_filesize for filesize extraction, parse_count for count meta
+fields extraction, parse_resolution, parse_duration for duration
+extraction, parse_age_limit for age_limit extraction.
+

 Explore youtube_dl/utils.py for more useful convenience functions.
 
 More examples
 Explore youtube_dl/utils.py for more useful convenience functions.
 
 More examples


@@ -1723,9 +1813,9 @@ BUGS
 
 
 Bugs and suggestions should be reported at:
 
 
 Bugs and suggestions should be reported at:

-https://github.com/rg3/youtube-dl/issues. 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
+https://github.com/ytdl-org/youtube-dl/issues. 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 #youtube-dl on freenode
 (webchat).
 
 discussions, join us in the IRC channel #youtube-dl on freenode
 (webchat).