]> Raphaƫl G. Git Repositories - youtubedl/blobdiff - README.txt
Update upstream source from tag 'upstream/2019.09.28'
[youtubedl] / README.txt
index 6ba6d68caf747152f10a67810815e53ab85b3b2e..045e0b19a873b35e5856240fe3975757288f0625 100644 (file)
@@ -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
@@ -1632,7 +1648,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 +1717,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 +1804,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).