Update upstream source from tag 'upstream/2018.11.07'

[youtubedl] / youtube-dl.1

diff --git a/youtube-dl.1 b/youtube-dl.1
index 976505407a134122a37a351da616e66708bcecaf..8ce66300d1bb2e15beb87c2bc173c7cd3fd78d93 100644 (file)
--- a/youtube-dl.1
+++ b/youtube-dl.1
@@ -116,7 +116,7 @@ Do not emit color codes in output
 .TP
 .B \-\-proxy \f[I]URL\f[]
 Use the specified HTTP/HTTPS/SOCKS proxy.
-To enable experimental SOCKS proxy, specify a proper scheme.
+To enable SOCKS proxy, specify a proper scheme.
 For example socks5://127.0.0.1:1080/.
 Pass in an empty string (\-\-proxy "") for direct connection
 .RS
@@ -145,26 +145,31 @@ Make all connections via IPv6
 .TP
 .B \-\-geo\-verification\-proxy \f[I]URL\f[]
 Use this proxy to verify the IP address for some geo\-restricted sites.
-The default proxy specified by \-\-proxy (or none, if the options is not
+The default proxy specified by \-\-proxy (or none, if the option is not
 present) is used for the actual downloading.
 .RS
 .RE
 .TP
 .B \-\-geo\-bypass
 Bypass geographic restriction via faking X\-Forwarded\-For HTTP header
-(experimental)
 .RS
 .RE
 .TP
 .B \-\-no\-geo\-bypass
 Do not bypass geographic restriction via faking X\-Forwarded\-For HTTP
-header (experimental)
+header
 .RS
 .RE
 .TP
 .B \-\-geo\-bypass\-country \f[I]CODE\f[]
 Force bypass geographic restriction with explicitly provided two\-letter
-ISO 3166\-2 country code (experimental)
+ISO 3166\-2 country code
+.RS
+.RE
+.TP
+.B \-\-geo\-bypass\-ip\-block \f[I]IP_BLOCK\f[]
+Force bypass geographic restriction with explicitly provided IP block in
+CIDR notation
 .RS
 .RE
 .SS Video Selection:
@@ -353,7 +358,7 @@ Download playlist videos in random order
 .RE
 .TP
 .B \-\-xattr\-set\-filesize
-Set file xattribute ytdl.filesize with expected file size (experimental)
+Set file xattribute ytdl.filesize with expected file size
 .RS
 .RE
 .TP
@@ -885,12 +890,12 @@ One of never (do nothing), warn (only emit a warning), detect_or_warn
 .RE
 .TP
 .B \-\-prefer\-avconv
-Prefer avconv over ffmpeg for running the postprocessors (default)
+Prefer avconv over ffmpeg for running the postprocessors
 .RS
 .RE
 .TP
 .B \-\-prefer\-ffmpeg
-Prefer ffmpeg over avconv for running the postprocessors
+Prefer ffmpeg over avconv for running the postprocessors (default)
 .RS
 .RE
 .TP
@@ -916,7 +921,7 @@ srt|ass|vtt|lrc)
 .PP
 You can configure youtube\-dl by placing any supported command line
 option to a configuration file.
-On Linux and OS X, the system wide configuration file is located at
+On Linux and macOS, the system wide configuration file is located at
 \f[C]/etc/youtube\-dl.conf\f[] and the user wide configuration file at
 \f[C]~/.config/youtube\-dl/config\f[].
 On Windows, the user wide configuration file locations are
@@ -1059,6 +1064,11 @@ became available
 .IP \[bu] 2
 \f[C]uploader_id\f[] (string): Nickname or id of the video uploader
 .IP \[bu] 2
+\f[C]channel\f[] (string): Full name of the channel the video is
+uploaded on
+.IP \[bu] 2
+\f[C]channel_id\f[] (string): Id of the channel
+.IP \[bu] 2
 \f[C]location\f[] (string): Physical location where the video was filmed
 .IP \[bu] 2
 \f[C]duration\f[] (numeric): Length of the video in seconds
@@ -1748,8 +1758,8 @@ In order to extract cookies from browser use any conforming browser
 extension for exporting cookies.
 For example,
 cookies.txt (https://chrome.google.com/webstore/detail/cookiestxt/njabckikapfpffapmjgojcnbfjonfjfg)
-(for Chrome) or Export
-Cookies (https://addons.mozilla.org/en-US/firefox/addon/export-cookies/)
+(for Chrome) or
+cookies.txt (https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/)
 (for Firefox).
 .PP
 Note that the cookies file must be in Mozilla/Netscape format and the
@@ -2323,9 +2333,36 @@ title\ =\ self._search_regex(
 .fi
 .SS Use safe conversion functions
 .PP
-Wrap all extracted numeric data into safe functions from \f[C]utils\f[]:
+Wrap all extracted numeric data into safe functions from
+\f[C]youtube_dl/utils.py\f[] (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/utils.py):
 \f[C]int_or_none\f[], \f[C]float_or_none\f[].
 Use them for string to number conversions as well.
+.PP
+Use \f[C]url_or_none\f[] for safe URL processing.
+.PP
+Use \f[C]try_get\f[] for safe metadata extraction from parsed JSON.
+.PP
+Explore
+\f[C]youtube_dl/utils.py\f[] (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/utils.py)
+for more useful convenience functions.
+.SS More examples
+.SS Safely extract optional description from parsed JSON
+.IP
+.nf
+\f[C]
+description\ =\ try_get(response,\ lambda\ x:\ x[\[aq]result\[aq]][\[aq]video\[aq]][0][\[aq]summary\[aq]],\ compat_str)
+\f[]
+.fi
+.SS Safely extract more optional metadata
+.IP
+.nf
+\f[C]
+video\ =\ try_get(response,\ lambda\ x:\ x[\[aq]result\[aq]][\[aq]video\[aq]][0],\ dict)\ or\ {}
+description\ =\ video.get(\[aq]summary\[aq])
+duration\ =\ float_or_none(video.get(\[aq]durationMs\[aq]),\ scale=1000)
+view_count\ =\ int_or_none(video.get(\[aq]views\[aq]))
+\f[]
+.fi
 .SH EMBEDDING YOUTUBE\-DL
 .PP
 youtube\-dl makes the best effort to be a good command\-line program,