network/youtube-dl: Install man page and shell completions.

Signed-off-by: B. Watson <urchlay@slackware.uk>

Signed-off-by: Willy Sudiarto Raharjo <willysr@slackbuilds.org>

3 files changed, 2543 insertions, 12 deletions

diff --git a/network/youtube-dl/doinst.sh b/network/youtube-dl/doinst.sh
deleted file mode 100644
index 5fb28930db0b..000000000000
--- a/network/youtube-dl/doinst.sh
+++ /dev/null
@@ -1,3 +0,0 @@
-if [ -x /usr/bin/update-desktop-database ]; then
-  /usr/bin/update-desktop-database -q usr/share/applications >/dev/null 2>&1
-fi
diff --git a/network/youtube-dl/youtube-dl.1 b/network/youtube-dl/youtube-dl.1
new file mode 100644
index 000000000000..9161f3b727dd
--- /dev/null
+++ b/network/youtube-dl/youtube-dl.1
@@ -0,0 +1,2522 @@
+.\" Automatically generated by Pandoc 3.1.3
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "YOUTUBE-DL" "1" "" "" ""
+.hy
+.SH NAME
+.PP
+youtube-dl - download videos from youtube.com or other video platforms
+.SH SYNOPSIS
+.PP
+\f[B]youtube-dl\f[R] [OPTIONS] URL [URL\&...]
+.SH DESCRIPTION
+.PP
+\f[B]youtube-dl\f[R] is a command-line program to download videos from
+YouTube.com and a few more sites.
+It requires the Python interpreter, version 2.6, 2.7, or 3.2+, and it is
+not platform specific.
+It should work on your Unix box, on Windows or on macOS.
+It is released to the public domain, which means you can modify it,
+redistribute it or use it however you like.
+.SH OPTIONS
+.TP
+-h, \[en]help
+Print this help text and exit
+.TP
+\[en]version
+Print program version and exit
+.TP
+-U, \[en]update
+Update this program to latest version.
+Make sure that you have sufficient permissions (run with sudo if needed)
+.TP
+-i, \[en]ignore-errors
+Continue on download errors, for example to skip unavailable videos in a
+playlist
+.TP
+\[en]abort-on-error
+Abort downloading of further videos (in the playlist or the command
+line) if an error occurs
+.TP
+\[en]dump-user-agent
+Display the current browser identification
+.TP
+\[en]list-extractors
+List all supported extractors
+.TP
+\[en]extractor-descriptions
+Output descriptions of all supported extractors
+.TP
+\[en]force-generic-extractor
+Force extraction to use the generic extractor
+.TP
+\[en]default-search \f[I]PREFIX\f[R]
+Use this prefix for unqualified URLs.
+For example \[lq]gvsearch2:\[rq] downloads two videos from google videos
+for youtube- dl \[lq]large apple\[rq].
+Use the value \[lq]auto\[rq] to let youtube-dl guess
+(\[lq]auto_warning\[rq] to emit a warning when guessing).
+\[lq]error\[rq] just throws an error.
+The default value \[lq]fixup_error\[rq] repairs broken URLs, but emits
+an error if this is not possible instead of searching.
+.TP
+\[en]ignore-config
+Do not read configuration files.
+When given in the global configuration file /etc/youtube-dl.conf: Do not
+read the user configuration in \[ti]/.config/youtube-dl/config
+(%APPDATA%/youtube-dl/config.txt on Windows)
+.TP
+\[en]config-location \f[I]PATH\f[R]
+Location of the configuration file; either the path to the config or its
+containing directory.
+.TP
+\[en]flat-playlist
+Do not extract the videos of a playlist, only list them.
+.TP
+\[en]mark-watched
+Mark videos watched (YouTube only)
+.TP
+\[en]no-mark-watched
+Do not mark videos watched (YouTube only)
+.TP
+\[en]no-color
+Do not emit color codes in output
+.SS Network Options:
+.TP
+\[en]proxy \f[I]URL\f[R]
+Use the specified HTTP/HTTPS/SOCKS proxy.
+To enable SOCKS proxy, specify a proper scheme.
+For example socks5://127.0.0.1:1080/.
+Pass in an empty string (\[en]proxy \[lq]\[lq]) for direct connection
+.TP
+\[en]socket-timeout \f[I]SECONDS\f[R]
+Time to wait before giving up, in seconds
+.TP
+\[en]source-address \f[I]IP\f[R]
+Client-side IP address to bind to
+.TP
+-4, \[en]force-ipv4
+Make all connections via IPv4
+.TP
+-6, \[en]force-ipv6
+Make all connections via IPv6
+.SS Geo Restriction:
+.TP
+\[en]geo-verification-proxy \f[I]URL\f[R]
+Use this proxy to verify the IP address for some geo-restricted sites.
+The default proxy specified by \[en]proxy (or none, if the option is not
+present) is used for the actual downloading.
+.TP
+\[en]geo-bypass
+Bypass geographic restriction via faking X-Forwarded-For HTTP header
+.TP
+\[en]no-geo-bypass
+Do not bypass geographic restriction via faking X-Forwarded-For HTTP
+header
+.TP
+\[en]geo-bypass-country \f[I]CODE\f[R]
+Force bypass geographic restriction with explicitly provided two-letter
+ISO 3166-2 country code
+.TP
+\[en]geo-bypass-ip-block \f[I]IP_BLOCK\f[R]
+Force bypass geographic restriction with explicitly provided IP block in
+CIDR notation
+.SS Video Selection:
+.TP
+\[en]playlist-start \f[I]NUMBER\f[R]
+Playlist video to start at (default is 1)
+.TP
+\[en]playlist-end \f[I]NUMBER\f[R]
+Playlist video to end at (default is last)
+.TP
+\[en]playlist-items \f[I]ITEM_SPEC\f[R]
+Playlist video items to download.
+Specify indices of the videos in the playlist separated by commas like:
+\[lq]\[en] playlist-items 1,2,5,8\[rq] if you want to download videos
+indexed 1, 2, 5, 8 in the playlist.
+You can specify range: \[rq] \[en]playlist-items 1-3,7,10-13\[rq], it
+will download the videos at index 1, 2, 3, 7, 10, 11, 12 and 13.
+.TP
+\[en]match-title \f[I]REGEX\f[R]
+Download only matching titles (regex or caseless sub-string)
+.TP
+\[en]reject-title \f[I]REGEX\f[R]
+Skip download for matching titles (regex or caseless sub-string)
+.TP
+\[en]max-downloads \f[I]NUMBER\f[R]
+Abort after downloading NUMBER files
+.TP
+\[en]min-filesize \f[I]SIZE\f[R]
+Do not download any videos smaller than SIZE (e.g.\ 50k or 44.6m)
+.TP
+\[en]max-filesize \f[I]SIZE\f[R]
+Do not download any videos larger than SIZE (e.g.\ 50k or 44.6m)
+.TP
+\[en]date \f[I]DATE\f[R]
+Download only videos uploaded in this date
+.TP
+\[en]datebefore \f[I]DATE\f[R]
+Download only videos uploaded on or before this date (i.e.\ inclusive)
+.TP
+\[en]dateafter \f[I]DATE\f[R]
+Download only videos uploaded on or after this date (i.e.\ inclusive)
+.TP
+\[en]min-views \f[I]COUNT\f[R]
+Do not download any videos with less than COUNT views
+.TP
+\[en]max-views \f[I]COUNT\f[R]
+Do not download any videos with more than COUNT views
+.TP
+\[en]match-filter \f[I]FILTER\f[R]
+Generic video filter.
+Specify any key (see the \[lq]OUTPUT TEMPLATE\[rq] 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 \[lq]comment_count > 12\[rq], also
+works with >=, <, <=, !=, =) to compare against a number, key =
+`LITERAL' (like \[lq]uploader = `Mike Smith'\[rq], 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.
+For example, to only match videos that have been liked more than 100
+times and disliked less than 50 times (or the dislike functionality is
+not available at the given service), but who also have a description,
+use \[en]match-filter \[lq]like_count > 100 & dislike_count <?
+50 & description\[rq] .
+.TP
+\[en]no-playlist
+Download only the video, if the URL refers to a video and a playlist.
+.TP
+\[en]yes-playlist
+Download the playlist, if the URL refers to a video and a playlist.
+.TP
+\[en]age-limit \f[I]YEARS\f[R]
+Download only videos suitable for the given age
+.TP
+\[en]download-archive \f[I]FILE\f[R]
+Download only videos not listed in the archive file.
+Record the IDs of all downloaded videos in it.
+.TP
+\[en]include-ads
+Download advertisements as well (experimental)
+.SS Download Options:
+.TP
+-r, \[en]limit-rate \f[I]RATE\f[R]
+Maximum download rate in bytes per second (e.g.\ 50K or 4.2M)
+.TP
+-R, \[en]retries \f[I]RETRIES\f[R]
+Number of retries (default is 10), or \[lq]infinite\[rq].
+.TP
+\[en]fragment-retries \f[I]RETRIES\f[R]
+Number of retries for a fragment (default is 10), or \[lq]infinite\[rq]
+(DASH, hlsnative and ISM)
+.TP
+\[en]skip-unavailable-fragments
+Skip unavailable fragments (DASH, hlsnative and ISM)
+.TP
+\[en]abort-on-unavailable-fragment
+Abort downloading when some fragment is not available
+.TP
+\[en]keep-fragments
+Keep downloaded fragments on disk after downloading is finished;
+fragments are erased by default
+.TP
+\[en]buffer-size \f[I]SIZE\f[R]
+Size of download buffer (e.g.\ 1024 or 16K) (default is 1024)
+.TP
+\[en]no-resize-buffer
+Do not automatically adjust the buffer size.
+By default, the buffer size is automatically resized from an initial
+value of SIZE.
+.TP
+\[en]http-chunk-size \f[I]SIZE\f[R]
+Size of a chunk for chunk-based HTTP downloading (e.g.\ 10485760 or 10M)
+(default is disabled).
+May be useful for bypassing bandwidth throttling imposed by a webserver
+(experimental)
+.TP
+\[en]playlist-reverse
+Download playlist videos in reverse order
+.TP
+\[en]playlist-random
+Download playlist videos in random order
+.TP
+\[en]xattr-set-filesize
+Set file xattribute ytdl.filesize with expected file size
+.TP
+\[en]hls-prefer-native
+Use the native HLS downloader instead of ffmpeg
+.TP
+\[en]hls-prefer-ffmpeg
+Use ffmpeg instead of the native HLS downloader
+.TP
+\[en]hls-use-mpegts
+Use the mpegts container for HLS videos, allowing to play the video
+while downloading (some players may not be able to play it)
+.TP
+\[en]external-downloader \f[I]COMMAND\f[R]
+Use the specified external downloader.
+Currently supports aria2c,avconv,axel,c url,ffmpeg,httpie,wget
+.TP
+\[en]external-downloader-args \f[I]ARGS\f[R]
+Give these arguments to the external downloader
+.SS Filesystem Options:
+.TP
+-a, \[en]batch-file \f[I]FILE\f[R]
+File containing URLs to download (`-' for stdin), one URL per line.
+Lines starting with `#', `;' or `]' are considered as comments and
+ignored.
+.TP
+\[en]id
+Use only video ID in file name
+.TP
+-o, \[en]output \f[I]TEMPLATE\f[R]
+Output filename template, see the \[lq]OUTPUT TEMPLATE\[rq] for all the
+info
+.TP
+\[en]output-na-placeholder \f[I]PLACEHOLDER\f[R]
+Placeholder value for unavailable meta fields in output filename
+template (default is \[lq]NA\[rq])
+.TP
+\[en]autonumber-start \f[I]NUMBER\f[R]
+Specify the start value for %(autonumber)s (default is 1)
+.TP
+\[en]restrict-filenames
+Restrict filenames to only ASCII characters, and avoid \[lq]&\[rq] and
+spaces in filenames
+.TP
+-w, \[en]no-overwrites
+Do not overwrite files
+.TP
+-c, \[en]continue
+Force resume of partially downloaded files.
+By default, youtube-dl will resume downloads if possible.
+.TP
+\[en]no-continue
+Do not resume partially downloaded files (restart from beginning)
+.TP
+\[en]no-part
+Do not use .part files - write directly into output file
+.TP
+\[en]no-mtime
+Do not use the Last-modified header to set the file modification time
+.TP
+\[en]write-description
+Write video description to a .description file
+.TP
+\[en]write-info-json
+Write video metadata to a .info.json file
+.TP
+\[en]write-annotations
+Write video annotations to a .annotations.xml file
+.TP
+\[en]load-info-json \f[I]FILE\f[R]
+JSON file containing the video information (created with the
+\[lq]\[en]write- info-json\[rq] option)
+.TP
+\[en]cookies \f[I]FILE\f[R]
+File to read cookies from and dump cookie jar in
+.TP
+\[en]cache-dir \f[I]DIR\f[R]
+Location in the filesystem where youtube-dl can store some downloaded
+information permanently.
+By default $XDG_CACHE_HOME/youtube-dl or \[ti]/.cache/youtube-dl .
+At the moment, only YouTube player files (for videos with obfuscated
+signatures) are cached, but that may change.
+.TP
+\[en]no-cache-dir
+Disable filesystem caching
+.TP
+\[en]rm-cache-dir
+Delete all filesystem cache files
+.SS Thumbnail Options:
+.TP
+\[en]write-thumbnail
+Write thumbnail image to disk
+.TP
+\[en]write-all-thumbnails
+Write all thumbnail image formats to disk
+.TP
+\[en]list-thumbnails
+Simulate and list all available thumbnail formats
+.SS Verbosity / Simulation Options:
+.TP
+-q, \[en]quiet
+Activate quiet mode
+.TP
+\[en]no-warnings
+Ignore warnings
+.TP
+-s, \[en]simulate
+Do not download the video and do not write anything to disk
+.TP
+\[en]skip-download
+Do not download the video
+.TP
+-g, \[en]get-url
+Simulate, quiet but print URL
+.TP
+-e, \[en]get-title
+Simulate, quiet but print title
+.TP
+\[en]get-id
+Simulate, quiet but print id
+.TP
+\[en]get-thumbnail
+Simulate, quiet but print thumbnail URL
+.TP
+\[en]get-description
+Simulate, quiet but print video description
+.TP
+\[en]get-duration
+Simulate, quiet but print video length
+.TP
+\[en]get-filename
+Simulate, quiet but print output filename
+.TP
+\[en]get-format
+Simulate, quiet but print output format
+.TP
+-j, \[en]dump-json
+Simulate, quiet but print JSON information.
+See the \[lq]OUTPUT TEMPLATE\[rq] for a description of available keys.
+.TP
+-J, \[en]dump-single-json
+Simulate, quiet but print JSON information for each command-line
+argument.
+If the URL refers to a playlist, dump the whole playlist information in
+a single line.
+.TP
+\[en]print-json
+Be quiet and print the video information as JSON (video is still being
+downloaded).
+.TP
+\[en]newline
+Output progress bar as new lines
+.TP
+\[en]no-progress
+Do not print progress bar
+.TP
+\[en]console-title
+Display progress in console titlebar
+.TP
+-v, \[en]verbose
+Print various debugging information
+.TP
+\[en]dump-pages
+Print downloaded pages encoded using base64 to debug problems (very
+verbose)
+.TP
+\[en]write-pages
+Write downloaded intermediary pages to files in the current directory to
+debug problems
+.TP
+\[en]print-traffic
+Display sent and read HTTP traffic
+.TP
+-C, \[en]call-home
+Contact the youtube-dl server for debugging
+.TP
+\[en]no-call-home
+Do NOT contact the youtube-dl server for debugging
+.SS Workarounds:
+.TP
+\[en]encoding \f[I]ENCODING\f[R]
+Force the specified encoding (experimental)
+.TP
+\[en]no-check-certificate
+Suppress HTTPS certificate validation
+.TP
+\[en]prefer-insecure
+Use an unencrypted connection to retrieve information about the video.
+(Currently supported only for YouTube)
+.TP
+\[en]user-agent \f[I]UA\f[R]
+Specify a custom user agent
+.TP
+\[en]referer \f[I]URL\f[R]
+Specify a custom referer, use if the video access is restricted to one
+domain
+.TP
+\[en]add-header \f[I]FIELD:VALUE\f[R]
+Specify a custom HTTP header and its value, separated by a colon `:'.
+You can use this option multiple times
+.TP
+\[en]bidi-workaround
+Work around terminals that lack bidirectional text support.
+Requires bidiv or fribidi executable in PATH
+.TP
+\[en]sleep-interval \f[I]SECONDS\f[R]
+Number of seconds to sleep before each download when used alone or a
+lower bound of a range for randomized sleep before each download
+(minimum possible number of seconds to sleep) when used along with
+\[en]max-sleep-interval.
+.TP
+\[en]max-sleep-interval \f[I]SECONDS\f[R]
+Upper bound of a range for randomized sleep before each download
+(maximum possible number of seconds to sleep).
+Must only be used along with \[en]min- sleep-interval.
+.SS Video Format Options:
+.TP
+-f, \[en]format \f[I]FORMAT\f[R]
+Video format code, see the \[lq]FORMAT SELECTION\[rq] for all the info
+.TP
+\[en]all-formats
+Download all available video formats
+.TP
+\[en]prefer-free-formats
+Prefer free video formats unless a specific one is requested
+.TP
+-F, \[en]list-formats
+List all available formats of requested videos
+.TP
+\[en]youtube-skip-dash-manifest
+Do not download the DASH manifests and related data on YouTube videos
+.TP
+\[en]merge-output-format \f[I]FORMAT\f[R]
+If a merge is required (e.g.
+bestvideo+bestaudio), output to given container format.
+One of mkv, mp4, ogg, webm, flv.
+Ignored if no merge is required
+.SS Subtitle Options:
+.TP
+\[en]write-sub
+Write subtitle file
+.TP
+\[en]write-auto-sub
+Write automatically generated subtitle file (YouTube only)
+.TP
+\[en]all-subs
+Download all the available subtitles of the video
+.TP
+\[en]list-subs
+List all available subtitles for the video
+.TP
+\[en]sub-format \f[I]FORMAT\f[R]
+Subtitle format, accepts formats preference, for example: \[lq]srt\[rq]
+or \[lq]ass/srt/best\[rq]
+.TP
+\[en]sub-lang \f[I]LANGS\f[R]
+Languages of the subtitles to download (optional) separated by commas,
+use \[en]list-subs for available language tags
+.SS Authentication Options:
+.TP
+-u, \[en]username \f[I]USERNAME\f[R]
+Login with this account ID
+.TP
+-p, \[en]password \f[I]PASSWORD\f[R]
+Account password.
+If this option is left out, youtube-dl will ask interactively.
+.TP
+-2, \[en]twofactor \f[I]TWOFACTOR\f[R]
+Two-factor authentication code
+.TP
+-n, \[en]netrc
+Use .netrc authentication data
+.TP
+\[en]video-password \f[I]PASSWORD\f[R]
+Video password (vimeo, youku)
+.SS Adobe Pass Options:
+.TP
+\[en]ap-mso \f[I]MSO\f[R]
+Adobe Pass multiple-system operator (TV provider) identifier, use
+\[en]ap-list-mso for a list of available MSOs
+.TP
+\[en]ap-username \f[I]USERNAME\f[R]
+Multiple-system operator account login
+.TP
+\[en]ap-password \f[I]PASSWORD\f[R]
+Multiple-system operator account password.
+If this option is left out, youtube-dl will ask interactively.
+.TP
+\[en]ap-list-mso
+List all supported multiple-system operators
+.SS Post-processing Options:
+.TP
+-x, \[en]extract-audio
+Convert video files to audio-only files (requires ffmpeg/avconv and
+ffprobe/avprobe)
+.TP
+\[en]audio-format \f[I]FORMAT\f[R]
+Specify audio format: \[lq]best\[rq], \[lq]aac\[rq], \[lq]flac\[rq],
+\[lq]mp3\[rq], \[lq]m4a\[rq], \[lq]opus\[rq], \[lq]vorbis\[rq], or
+\[lq]wav\[rq]; \[lq]best\[rq] by default; No effect without -x
+.TP
+\[en]audio-quality \f[I]QUALITY\f[R]
+Specify ffmpeg/avconv audio quality, insert a value between 0 (better)
+and 9 (worse) for VBR or a specific bitrate like 128K (default 5)
+.TP
+\[en]recode-video \f[I]FORMAT\f[R]
+Encode the video to another format if necessary (currently supported:
+mp4|flv|ogg|webm|mkv|avi)
+.TP
+\[en]postprocessor-args \f[I]ARGS\f[R]
+Give these arguments to the postprocessor
+.TP
+-k, \[en]keep-video
+Keep the video file on disk after the post-processing; the video is
+erased by default
+.TP
+\[en]no-post-overwrites
+Do not overwrite post-processed files; the post-processed files are
+overwritten by default
+.TP
+\[en]embed-subs
+Embed subtitles in the video (only for mp4, webm and mkv videos)
+.TP
+\[en]embed-thumbnail
+Embed thumbnail in the audio as cover art
+.TP
+\[en]add-metadata
+Write metadata to the video file
+.TP
+\[en]metadata-from-title \f[I]FORMAT\f[R]
+Parse additional metadata like song title / artist from the video title.
+The format syntax is the same as \[en]output.
+Regular expression with named capture groups may also be used.
+The parsed parameters replace existing values.
+Example: \[en]metadata-from-title \[lq]%(artist)s - %(title)s\[rq]
+matches a title like \[lq]Coldplay - Paradise\[rq].
+Example (regex): \[en]metadata-from-title \[lq](?P.+?)
+- (?P
+.RS
+\&.+)\[rq]
+.RE
+.TP
+\[en]xattrs
+Write metadata to the video file\[cq]s xattrs (using dublin core and xdg
+standards)
+.TP
+\[en]fixup \f[I]POLICY\f[R]
+Automatically correct known faults of the file.
+One of never (do nothing), warn (only emit a warning), detect_or_warn
+(the default; fix file if we can, warn otherwise)
+.TP
+\[en]prefer-avconv
+Prefer avconv over ffmpeg for running the postprocessors
+.TP
+\[en]prefer-ffmpeg
+Prefer ffmpeg over avconv for running the postprocessors (default)
+.TP
+\[en]ffmpeg-location \f[I]PATH\f[R]
+Location of the ffmpeg/avconv binary; either the path to the binary or
+its containing directory.
+.TP
+\[en]exec \f[I]CMD\f[R]
+Execute a command on the file after downloading and post-processing,
+similar to find\[cq]s -exec syntax.
+Example: \[en]exec `adb push {} /sdcard/Music/ && rm {}'
+.TP
+\[en]convert-subs \f[I]FORMAT\f[R]
+Convert the subtitles to other format (currently supported:
+srt|ass|vtt|lrc)
+.SH CONFIGURATION
+.PP
+You can configure youtube-dl by placing any supported command line
+option to a configuration file.
+On Linux and macOS, the system wide configuration file is located at
+\f[V]/etc/youtube-dl.conf\f[R] and the user wide configuration file at
+\f[V]\[ti]/.config/youtube-dl/config\f[R].
+On Windows, the user wide configuration file locations are
+\f[V]%APPDATA%\[rs]youtube-dl\[rs]config.txt\f[R] or
+\f[V]C:\[rs]Users\[rs]<user name>\[rs]youtube-dl.conf\f[R].
+Note that by default configuration file may not exist so you may need to
+create it yourself.
+.PP
+For example, with the following configuration file youtube-dl will
+always extract the audio, not copy the mtime, use a proxy and save all
+videos under \f[V]Movies\f[R] directory in your home directory:
+.IP
+.nf
+\f[C]
+# Lines starting with # are comments
+
+# Always extract audio
+-x
+
+# Do not copy the mtime
+--no-mtime
+
+# Use this proxy
+--proxy 127.0.0.1:3128
+
+# Save all videos under Movies directory in your home directory
+-o \[ti]/Movies/%(title)s.%(ext)s
+\f[R]
+.fi
+.PP
+Note that options in configuration file are just the same options aka
+switches used in regular command line calls thus there \f[B]must be no
+whitespace\f[R] after \f[V]-\f[R] or \f[V]--\f[R], e.g.\ \f[V]-o\f[R] or
+\f[V]--proxy\f[R] but not \f[V]- o\f[R] or \f[V]-- proxy\f[R].
+.PP
+You can use \f[V]--ignore-config\f[R] if you want to disable the
+configuration file for a particular youtube-dl run.
+.PP
+You can also use \f[V]--config-location\f[R] if you want to use custom
+configuration file for a particular youtube-dl run.
+.SS Authentication with \f[V].netrc\f[R] file
+.PP
+You may also want to configure automatic credentials storage for
+extractors that support authentication (by providing login and password
+with \f[V]--username\f[R] and \f[V]--password\f[R]) in order not to 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[V].netrc\f[R]
+file (https://stackoverflow.com/tags/.netrc/info) on a per extractor
+basis.
+For that you will need to create a \f[V].netrc\f[R] file in your
+\f[V]$HOME\f[R] and restrict permissions to read/write by only you:
+.IP
+.nf
+\f[C]
+touch $HOME/.netrc
+chmod a-rwx,u+rw $HOME/.netrc
+\f[R]
+.fi
+.PP
+After that you can add credentials for an extractor in the following
+format, where \f[I]extractor\f[R] is the name of the extractor in
+lowercase:
+.IP
+.nf
+\f[C]
+machine <extractor> login <login> password <password>
+\f[R]
+.fi
+.PP
+For example:
+.IP
+.nf
+\f[C]
+machine youtube login myaccount\[at]gmail.com password my_youtube_password
+machine twitch login my_twitch_account_name password my_twitch_password
+\f[R]
+.fi
+.PP
+To activate authentication with the \f[V].netrc\f[R] file you should
+pass \f[V]--netrc\f[R] to youtube-dl or place it in the configuration
+file.
+.PP
+On Windows you may also need to setup the \f[V]%HOME%\f[R] environment
+variable manually.
+For example:
+.IP
+.nf
+\f[C]
+set HOME=%USERPROFILE%
+\f[R]
+.fi
+.SH OUTPUT TEMPLATE
+.PP
+The \f[V]-o\f[R] option allows users to indicate a template for the
+output file names.
+.PP
+\f[B]tl;dr:\f[R] navigate me to examples.
+.PP
+The basic usage is not to set any template arguments when downloading a
+single file, like in
+\f[V]youtube-dl -o funny_video.flv \[dq]https://some/video\[dq]\f[R].
+However, it may contain special sequences that will be replaced when
+downloading each video.
+The special sequences may be formatted according to python string
+formatting
+operations (https://docs.python.org/2/library/stdtypes.html#string-formatting).
+For example, \f[V]%(NAME)s\f[R] or \f[V]%(NAME)05d\f[R].
+To clarify, that is a percent symbol followed by a name in parentheses,
+followed by formatting operations.
+Allowed names along with sequence type are:
+.IP \[bu] 2
+\f[V]id\f[R] (string): Video identifier
+.IP \[bu] 2
+\f[V]title\f[R] (string): Video title
+.IP \[bu] 2
+\f[V]url\f[R] (string): Video URL
+.IP \[bu] 2
+\f[V]ext\f[R] (string): Video filename extension
+.IP \[bu] 2
+\f[V]alt_title\f[R] (string): A secondary title of the video
+.IP \[bu] 2
+\f[V]display_id\f[R] (string): An alternative identifier for the video
+.IP \[bu] 2
+\f[V]uploader\f[R] (string): Full name of the video uploader
+.IP \[bu] 2
+\f[V]license\f[R] (string): License name the video is licensed under
+.IP \[bu] 2
+\f[V]creator\f[R] (string): The creator of the video
+.IP \[bu] 2
+\f[V]release_date\f[R] (string): The date (YYYYMMDD) when the video was
+released
+.IP \[bu] 2
+\f[V]timestamp\f[R] (numeric): UNIX timestamp of the moment the video
+became available
+.IP \[bu] 2
+\f[V]upload_date\f[R] (string): Video upload date (YYYYMMDD)
+.IP \[bu] 2
+\f[V]uploader_id\f[R] (string): Nickname or id of the video uploader
+.IP \[bu] 2
+\f[V]channel\f[R] (string): Full name of the channel the video is
+uploaded on
+.IP \[bu] 2
+\f[V]channel_id\f[R] (string): Id of the channel
+.IP \[bu] 2
+\f[V]location\f[R] (string): Physical location where the video was
+filmed
+.IP \[bu] 2
+\f[V]duration\f[R] (numeric): Length of the video in seconds
+.IP \[bu] 2
+\f[V]view_count\f[R] (numeric): How many users have watched the video on
+the platform
+.IP \[bu] 2
+\f[V]like_count\f[R] (numeric): Number of positive ratings of the video
+.IP \[bu] 2
+\f[V]dislike_count\f[R] (numeric): Number of negative ratings of the
+video
+.IP \[bu] 2
+\f[V]repost_count\f[R] (numeric): Number of reposts of the video
+.IP \[bu] 2
+\f[V]average_rating\f[R] (numeric): Average rating give by users, the
+scale used depends on the webpage
+.IP \[bu] 2
+\f[V]comment_count\f[R] (numeric): Number of comments on the video
+.IP \[bu] 2
+\f[V]age_limit\f[R] (numeric): Age restriction for the video (years)
+.IP \[bu] 2
+\f[V]is_live\f[R] (boolean): Whether this video is a live stream or a
+fixed-length video
+.IP \[bu] 2
+\f[V]start_time\f[R] (numeric): Time in seconds where the reproduction
+should start, as specified in the URL
+.IP \[bu] 2
+\f[V]end_time\f[R] (numeric): Time in seconds where the reproduction
+should end, as specified in the URL
+.IP \[bu] 2
+\f[V]format\f[R] (string): A human-readable description of the format
+.IP \[bu] 2
+\f[V]format_id\f[R] (string): Format code specified by
+\f[V]--format\f[R]
+.IP \[bu] 2
+\f[V]format_note\f[R] (string): Additional info about the format
+.IP \[bu] 2
+\f[V]width\f[R] (numeric): Width of the video
+.IP \[bu] 2
+\f[V]height\f[R] (numeric): Height of the video
+.IP \[bu] 2
+\f[V]resolution\f[R] (string): Textual description of width and height
+.IP \[bu] 2
+\f[V]tbr\f[R] (numeric): Average bitrate of audio and video in KBit/s
+.IP \[bu] 2
+\f[V]abr\f[R] (numeric): Average audio bitrate in KBit/s
+.IP \[bu] 2
+\f[V]acodec\f[R] (string): Name of the audio codec in use
+.IP \[bu] 2
+\f[V]asr\f[R] (numeric): Audio sampling rate in Hertz
+.IP \[bu] 2
+\f[V]vbr\f[R] (numeric): Average video bitrate in KBit/s
+.IP \[bu] 2
+\f[V]fps\f[R] (numeric): Frame rate
+.IP \[bu] 2
+\f[V]vcodec\f[R] (string): Name of the video codec in use
+.IP \[bu] 2
+\f[V]container\f[R] (string): Name of the container format
+.IP \[bu] 2
+\f[V]filesize\f[R] (numeric): The number of bytes, if known in advance
+.IP \[bu] 2
+\f[V]filesize_approx\f[R] (numeric): An estimate for the number of bytes
+.IP \[bu] 2
+\f[V]protocol\f[R] (string): The protocol that will be used for the
+actual download
+.IP \[bu] 2
+\f[V]extractor\f[R] (string): Name of the extractor
+.IP \[bu] 2
+\f[V]extractor_key\f[R] (string): Key name of the extractor
+.IP \[bu] 2
+\f[V]epoch\f[R] (numeric): Unix epoch when creating the file
+.IP \[bu] 2
+\f[V]autonumber\f[R] (numeric): Number that will be increased with each
+download, starting at \f[V]--autonumber-start\f[R]
+.IP \[bu] 2
+\f[V]playlist\f[R] (string): Name or id of the playlist that contains
+the video
+.IP \[bu] 2
+\f[V]playlist_index\f[R] (numeric): Index of the video in the playlist
+padded with leading zeros according to the total length of the playlist
+.IP \[bu] 2
+\f[V]playlist_id\f[R] (string): Playlist identifier
+.IP \[bu] 2
+\f[V]playlist_title\f[R] (string): Playlist title
+.IP \[bu] 2
+\f[V]playlist_uploader\f[R] (string): Full name of the playlist uploader
+.IP \[bu] 2
+\f[V]playlist_uploader_id\f[R] (string): Nickname or id of the playlist
+uploader
+.PP
+Available for the video that belongs to some logical chapter or section:
+.IP \[bu] 2
+\f[V]chapter\f[R] (string): Name or title of the chapter the video
+belongs to
+.IP \[bu] 2
+\f[V]chapter_number\f[R] (numeric): Number of the chapter the video
+belongs to
+.IP \[bu] 2
+\f[V]chapter_id\f[R] (string): Id of the chapter the video belongs to
+.PP
+Available for the video that is an episode of some series or programme:
+.IP \[bu] 2
+\f[V]series\f[R] (string): Title of the series or programme the video
+episode belongs to
+.IP \[bu] 2
+\f[V]season\f[R] (string): Title of the season the video episode belongs
+to
+.IP \[bu] 2
+\f[V]season_number\f[R] (numeric): Number of the season the video
+episode belongs to
+.IP \[bu] 2
+\f[V]season_id\f[R] (string): Id of the season the video episode belongs
+to
+.IP \[bu] 2
+\f[V]episode\f[R] (string): Title of the video episode
+.IP \[bu] 2
+\f[V]episode_number\f[R] (numeric): Number of the video episode within a
+season
+.IP \[bu] 2
+\f[V]episode_id\f[R] (string): Id of the video episode
+.PP
+Available for the media that is a track or a part of a music album:
+.IP \[bu] 2
+\f[V]track\f[R] (string): Title of the track
+.IP \[bu] 2
+\f[V]track_number\f[R] (numeric): Number of the track within an album or
+a disc
+.IP \[bu] 2
+\f[V]track_id\f[R] (string): Id of the track
+.IP \[bu] 2
+\f[V]artist\f[R] (string): Artist(s) of the track
+.IP \[bu] 2
+\f[V]genre\f[R] (string): Genre(s) of the track
+.IP \[bu] 2
+\f[V]album\f[R] (string): Title of the album the track belongs to
+.IP \[bu] 2
+\f[V]album_type\f[R] (string): Type of the album
+.IP \[bu] 2
+\f[V]album_artist\f[R] (string): List of all artists appeared on the
+album
+.IP \[bu] 2
+\f[V]disc_number\f[R] (numeric): Number of the disc or other physical
+medium the track belongs to
+.IP \[bu] 2
+\f[V]release_year\f[R] (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.
+Note that some of the sequences are not guaranteed to be present since
+they depend on the metadata obtained by a particular extractor.
+Such sequences will be replaced with placeholder value provided with
+\f[V]--output-na-placeholder\f[R] (\f[V]NA\f[R] by default).
+.PP
+For example for \f[V]-o %(title)s-%(id)s.%(ext)s\f[R] and an mp4 video
+with title \f[V]youtube-dl test video\f[R] and id
+\f[V]BaW_jenozKcj\f[R], this will result in a
+\f[V]youtube-dl test video-BaW_jenozKcj.mp4\f[R] file created in the
+current directory.
+.PP
+For numeric sequences you can use numeric related formatting, for
+example, \f[V]%(view_count)05d\f[R] will result in a string with view
+count padded with zeros up to 5 characters, like in \f[V]00042\f[R].
+.PP
+Output templates can also contain arbitrary hierarchical path,
+e.g.\ \f[V]-o \[aq]%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[aq]\f[R]
+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 use percent literals in an output template use \f[V]%%\f[R].
+To output to stdout use \f[V]-o -\f[R].
+.PP
+The current default template is \f[V]%(title)s-%(id)s.%(ext)s\f[R].
+.PP
+In some cases, you don\[cq]t want special characters such as 中, spaces,
+or &, such as when transferring the downloaded filename to a Windows
+system or the filename through an 8bit-unsafe channel.
+In these cases, add the \f[V]--restrict-filenames\f[R] flag to get a
+shorter title.
+.SS Output template and Windows batch files
+.PP
+If you are using an output template inside a Windows batch file then you
+must escape plain percent characters (\f[V]%\f[R]) by doubling, so that
+\f[V]-o \[dq]%(title)s-%(id)s.%(ext)s\[dq]\f[R] should become
+\f[V]-o \[dq]%%(title)s-%%(id)s.%%(ext)s\[dq]\f[R].
+However you should not touch \f[V]%\f[R]\[cq]s that are not plain
+characters, e.g.\ environment variables for expansion should stay
+intact:
+\f[V]-o \[dq]C:\[rs]%HOMEPATH%\[rs]Desktop\[rs]%%(title)s.%%(ext)s\[dq]\f[R].
+.SS Output template examples
+.PP
+Note that on Windows you may need to use double quotes instead of
+single.
+.IP
+.nf
+\f[C]
+$ youtube-dl --get-filename -o \[aq]%(title)s.%(ext)s\[aq] BaW_jenozKc
+youtube-dl test video \[aq]\[aq]_ä↭𝕐.mp4    # All kinds of weird characters
+
+$ youtube-dl --get-filename -o \[aq]%(title)s.%(ext)s\[aq] BaW_jenozKc --restrict-filenames
+youtube-dl_test_video_.mp4          # A simple file name
+
+# Download YouTube playlist videos in separate directory indexed by video order in a playlist
+$ youtube-dl -o \[aq]%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[aq] https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re
+
+# Download all playlists of YouTube channel/user keeping each playlist in separate directory:
+$ youtube-dl -o \[aq]%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s\[aq] https://www.youtube.com/user/TheLinuxFoundation/playlists
+
+# Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
+$ youtube-dl -u user -p password -o \[aq]\[ti]/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 \[dq]C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s\[dq] https://videomore.ru/kino_v_detalayah/5_sezon/367617
+
+# Stream the video being downloaded to stdout
+$ youtube-dl -o - BaW_jenozKc
+\f[R]
+.fi
+.SH FORMAT SELECTION
+.PP
+By default youtube-dl tries to download the best available quality,
+i.e.\ if you want the best quality you \f[B]don\[cq]t need\f[R] to pass
+any special options, youtube-dl will guess it for you by
+\f[B]default\f[R].
+.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
+selection\f[R] based on which you can explicitly specify desired format,
+select formats based on some criterion or criteria, setup precedence and
+much more.
+.PP
+The general syntax for format selection is \f[V]--format FORMAT\f[R] or
+shorter \f[V]-f FORMAT\f[R] where \f[V]FORMAT\f[R] is a \f[I]selector
+expression\f[R], i.e.\ an expression that describes format or formats
+you would like to download.
+.PP
+\f[B]tl;dr:\f[R] navigate me to examples.
+.PP
+The simplest case is requesting a specific format, for example with
+\f[V]-f 22\f[R] you can download the format with format code equal to
+22.
+You can get the list of available format codes for particular video
+using \f[V]--list-formats\f[R] or \f[V]-F\f[R].
+Note that these format codes are extractor specific.
+.PP
+You can also use a file extension (currently \f[V]3gp\f[R],
+\f[V]aac\f[R], \f[V]flv\f[R], \f[V]m4a\f[R], \f[V]mp3\f[R],
+\f[V]mp4\f[R], \f[V]ogg\f[R], \f[V]wav\f[R], \f[V]webm\f[R] are
+supported) to download the best quality format of a particular file
+extension served as a single file, e.g.\ \f[V]-f webm\f[R] will download
+the best quality format with the \f[V]webm\f[R] extension served as a
+single file.
+.PP
+You can also use special names to select particular edge case formats:
+.IP \[bu] 2
+\f[V]best\f[R]: Select the best quality format represented by a single
+file with video and audio.
+.IP \[bu] 2
+\f[V]worst\f[R]: Select the worst quality format represented by a single
+file with video and audio.
+.IP \[bu] 2
+\f[V]bestvideo\f[R]: Select the best quality video-only format
+(e.g.\ DASH video).
+May not be available.
+.IP \[bu] 2
+\f[V]worstvideo\f[R]: Select the worst quality video-only format.
+May not be available.
+.IP \[bu] 2
+\f[V]bestaudio\f[R]: Select the best quality audio only-format.
+May not be available.
+.IP \[bu] 2
+\f[V]worstaudio\f[R]: 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[V]-f worstvideo\f[R].
+.PP
+If you want to download multiple videos and they don\[cq]t have the same
+formats available, you can specify the order of preference using
+slashes.
+Note that slash is left-associative, i.e.\ formats on the left hand side
+are preferred, for example \f[V]-f 22/17/18\f[R] will download format 22
+if it\[cq]s available, otherwise it will download format 17 if it\[cq]s
+available, otherwise it will download format 18 if it\[cq]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 a comma as
+a separator, e.g.\ \f[V]-f 22,17,18\f[R] will download all these three
+formats, of course if they are available.
+Or a more sophisticated example combined with the precedence feature:
+\f[V]-f 136/137/mp4/bestvideo,140/m4a/bestaudio\f[R].
+.PP
+You can also filter the video formats by putting a condition in
+brackets, as in \f[V]-f \[dq]best[height=720]\[dq]\f[R] (or
+\f[V]-f \[dq][filesize>10M]\[dq]\f[R]).
+.PP
+The following numeric meta fields can be used with comparisons
+\f[V]<\f[R], \f[V]<=\f[R], \f[V]>\f[R], \f[V]>=\f[R], \f[V]=\f[R]
+(equals), \f[V]!=\f[R] (not equals):
+.IP \[bu] 2
+\f[V]filesize\f[R]: The number of bytes, if known in advance
+.IP \[bu] 2
+\f[V]width\f[R]: Width of the video, if known
+.IP \[bu] 2
+\f[V]height\f[R]: Height of the video, if known
+.IP \[bu] 2
+\f[V]tbr\f[R]: Average bitrate of audio and video in KBit/s
+.IP \[bu] 2
+\f[V]abr\f[R]: Average audio bitrate in KBit/s
+.IP \[bu] 2
+\f[V]vbr\f[R]: Average video bitrate in KBit/s
+.IP \[bu] 2
+\f[V]asr\f[R]: Audio sampling rate in Hertz
+.IP \[bu] 2
+\f[V]fps\f[R]: Frame rate
+.PP
+Also filtering work for comparisons \f[V]=\f[R] (equals),
+\f[V]\[ha]=\f[R] (starts with), \f[V]$=\f[R] (ends with), \f[V]*=\f[R]
+(contains) and following string meta fields:
+.IP \[bu] 2
+\f[V]ext\f[R]: File extension
+.IP \[bu] 2
+\f[V]acodec\f[R]: Name of the audio codec in use
+.IP \[bu] 2
+\f[V]vcodec\f[R]: Name of the video codec in use
+.IP \[bu] 2
+\f[V]container\f[R]: Name of the container format
+.IP \[bu] 2
+\f[V]protocol\f[R]: The protocol that will be used for the actual
+download, lower-case (\f[V]http\f[R], \f[V]https\f[R], \f[V]rtsp\f[R],
+\f[V]rtmp\f[R], \f[V]rtmpe\f[R], \f[V]mms\f[R], \f[V]f4m\f[R],
+\f[V]ism\f[R], \f[V]http_dash_segments\f[R], \f[V]m3u8\f[R], or
+\f[V]m3u8_native\f[R])
+.IP \[bu] 2
+\f[V]format_id\f[R]: A short description of the format
+.IP \[bu] 2
+\f[V]language\f[R]: Language code
+.PP
+Any string comparison may be prefixed with negation \f[V]!\f[R] in order
+to produce an opposite comparison, e.g.\ \f[V]!*=\f[R] (does not
+contain).
+.PP
+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 the video hoster.
+.PP
+Formats for which the value is not known are excluded unless you put a
+question mark (\f[V]?\f[R]) after the operator.
+You can combine format filters, so
+\f[V]-f \[dq][height <=? 720][tbr>500]\[dq]\f[R] selects up to 720p
+videos (or videos where the height is not known) with a bitrate of at
+least 500 KBit/s.
+.PP
+You can merge the video and audio of two formats into a single file
+using \f[V]-f <video-format>+<audio-format>\f[R] (requires ffmpeg or
+avconv installed), for example \f[V]-f bestvideo+bestaudio\f[R] will
+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[V]-f \[aq](mp4,webm)[height<480]\[aq]\f[R].
+.PP
+Since the end of April 2015 and version 2015.04.26, youtube-dl uses
+\f[V]-f bestvideo+bestaudio/best\f[R] as the default format selection
+(see #5447 (https://github.com/ytdl-org/youtube-dl/issues/5447),
+#5456 (https://github.com/ytdl-org/youtube-dl/issues/5456)).
+If ffmpeg or avconv are installed this results in downloading
+\f[V]bestvideo\f[R] and \f[V]bestaudio\f[R] separately and muxing them
+together into a single file giving the best overall quality available.
+Otherwise it falls back to \f[V]best\f[R] and results in downloading the
+best available quality served as a single file.
+\f[V]best\f[R] is also needed for videos that don\[cq]t come from
+YouTube because they don\[cq]t provide the audio and video in two
+different files.
+If you want to only download some DASH formats (for example if you are
+not interested in getting videos with a resolution higher than 1080p),
+you can add \f[V]-f bestvideo[height<=?1080]+bestaudio/best\f[R] to your
+configuration file.
+Note that if you use youtube-dl to stream to \f[V]stdout\f[R] (and most
+likely to pipe it to your media player then), i.e.\ you explicitly
+specify output template as \f[V]-o -\f[R], youtube-dl still uses
+\f[V]-f best\f[R] format selection in order to start content delivery
+immediately to your player and not to wait until \f[V]bestvideo\f[R] and
+\f[V]bestaudio\f[R] are downloaded and muxed.
+.PP
+If you want to preserve the old format selection behavior (prior to
+youtube-dl 2015.04.26), i.e.\ you want to download the best available
+quality media served as a single file, you should explicitly specify
+your choice with \f[V]-f best\f[R].
+You may want to add it to the configuration file in order not to type it
+every time you run youtube-dl.
+.SS Format selection examples
+.PP
+Note that on Windows you may need to use double quotes instead of
+single.
+.IP
+.nf
+\f[C]
+# Download best mp4 format available or any other best if no mp4 available
+$ youtube-dl -f \[aq]bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best\[aq]
+
+# Download best format available but no better than 480p
+$ youtube-dl -f \[aq]bestvideo[height<=480]+bestaudio/best[height<=480]\[aq]
+
+# Download best video only format but no bigger than 50 MB
+$ youtube-dl -f \[aq]best[filesize<50M]\[aq]
+
+# Download best format available via direct link over HTTP/HTTPS protocol
+$ youtube-dl -f \[aq](bestvideo+bestaudio/best)[protocol\[ha]=http]\[aq]
+
+# Download the best video format and the best audio format without merging them
+$ youtube-dl -f \[aq]bestvideo,bestaudio\[aq] -o \[aq]%(title)s.f%(format_id)s.%(ext)s\[aq]
+\f[R]
+.fi
+.PP
+Note that in the last example, an output template is recommended as
+bestvideo and bestaudio may have the same file name.
+.SH VIDEO SELECTION
+.PP
+Videos can be filtered by their upload date using the options
+\f[V]--date\f[R], \f[V]--datebefore\f[R] or \f[V]--dateafter\f[R].
+They accept dates in two formats:
+.IP \[bu] 2
+Absolute dates: Dates in the format \f[V]YYYYMMDD\f[R].
+.IP \[bu] 2
+Relative dates: Dates in the format
+\f[V](now|today)[+-][0-9](day|week|month|year)(s)?\f[R]
+.PP
+Examples:
+.IP
+.nf
+\f[C]
+# Download only the videos uploaded in the last 6 months
+$ youtube-dl --dateafter now-6months
+
+# Download only the videos uploaded on January 1, 1970
+$ youtube-dl --date 19700101
+
+$ # Download only the videos uploaded in the 200x decade
+$ youtube-dl --dateafter 20000101 --datebefore 20091231
+\f[R]
+.fi
+.SH FAQ
+.SS How do I update youtube-dl?
+.PP
+If you\[cq]ve followed our manual installation
+instructions (https://ytdl-org.github.io/youtube-dl/download.html), you
+can simply run \f[V]youtube-dl -U\f[R] (or, on Linux,
+\f[V]sudo youtube-dl -U\f[R]).
+.PP
+If you have used pip, a simple \f[V]sudo pip install -U youtube-dl\f[R]
+is sufficient to update.
+.PP
+If you have installed youtube-dl using a package manager like
+\f[I]apt-get\f[R] or \f[I]yum\f[R], use the standard system update
+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 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
+or support forum.
+.PP
+As a last resort, you can also uninstall the version installed by your
+package manager and follow our manual installation instructions.
+For that, remove the distribution\[cq]s package, with a line like
+.IP
+.nf
+\f[C]
+sudo apt-get remove -y youtube-dl
+\f[R]
+.fi
+.PP
+Afterwards, simply follow our manual installation
+instructions (https://ytdl-org.github.io/youtube-dl/download.html):
+.IP
+.nf
+\f[C]
+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
+\f[R]
+.fi
+.PP
+Again, from then on you\[cq]ll be able to update with
+\f[V]sudo youtube-dl -U\f[R].
+.SS youtube-dl is extremely slow to start on Windows
+.PP
+Add a file exclusion for \f[V]youtube-dl.exe\f[R] in Windows Defender
+settings.
+.SS I\[cq]m getting an error \f[V]Unable to extract OpenGraph title\f[R] on YouTube playlists
+.PP
+YouTube changed their playlist format in March 2014 and later on, so
+you\[cq]ll need at least youtube-dl 2014.07.25 to download all YouTube
+videos.
+.PP
+If you have installed youtube-dl with a package manager, pip, setup.py
+or a tarball, please use that to update.
+Note that Ubuntu packages do not seem to get updated anymore.
+Since we are not affiliated with Ubuntu, there is little we can do.
+Feel free to report
+bugs (https://bugs.launchpad.net/ubuntu/+source/youtube-dl/+filebug) to
+the Ubuntu packaging
+people (mailto:ubuntu-motu@lists.ubuntu.com?subject=outdated%20version%20of%20youtube-dl)
+- all they have to do is update the package to a somewhat recent
+version.
+See above for a way to update.
+.SS I\[cq]m getting an error when trying to use output template: \f[V]error: using output template conflicts with using title, video ID or auto number\f[R]
+.PP
+Make sure you are not using \f[V]-o\f[R] with any of these options
+\f[V]-t\f[R], \f[V]--title\f[R], \f[V]--id\f[R], \f[V]-A\f[R] or
+\f[V]--auto-number\f[R] set in command line or in a configuration file.
+Remove the latter if any.
+.SS Do I always have to pass \f[V]-citw\f[R]?
+.PP
+By default, youtube-dl intends to have the best options (incidentally,
+if you have a convincing case that these should be different, please
+file an issue where you explain that (https://yt-dl.org/bug)).
+Therefore, it is unnecessary and sometimes harmful to copy long option
+strings from webpages.
+In particular, the only option out of \f[V]-citw\f[R] that is regularly
+useful is \f[V]-i\f[R].
+.SS Can you please put the \f[V]-b\f[R] option back?
+.PP
+Most people asking this question are not aware that youtube-dl now
+defaults to downloading the highest available quality as reported by
+YouTube, which will be 1080p or 720p in some cases, so you no longer
+need the \f[V]-b\f[R] option.
+For some specific videos, maybe YouTube does not report them to be
+available in a specific high quality format you\[cq]re interested in.
+In that case, simply request it with the \f[V]-f\f[R] option and
+youtube-dl will try to download it.
+.SS I get HTTP error 402 when trying to download a video. What\[cq]s this?
+.PP
+Apparently YouTube requires you to pass a CAPTCHA test if you download
+too much.
+We\[cq]re considering to provide a way to let you solve the
+CAPTCHA (https://github.com/ytdl-org/youtube-dl/issues/154), but at the
+moment, your best course of action is pointing a web browser to the
+youtube URL, solving the CAPTCHA, and restart youtube-dl.
+.SS Do I need any other programs?
+.PP
+youtube-dl works fine on its own on most sites.
+However, if you want to convert video/audio, you\[cq]ll need
+avconv (https://libav.org/) or ffmpeg (https://www.ffmpeg.org/).
+On some sites - most notably YouTube - videos can be retrieved in a
+higher quality format without sound.
+youtube-dl will detect whether avconv/ffmpeg is present and
+automatically pick the best option.
+.PP
+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 (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 (https://www.videolan.org/) or
+mplayer (https://www.mplayerhq.hu/).
+.SS I extracted a video URL with \f[V]-g\f[R], but it does not play on another machine / in my web browser.
+.PP
+It depends a lot on the service.
+In many cases, requests for the video (to download/play it) must come
+from the same IP address and with the same cookies and/or HTTP headers.
+Use the \f[V]--cookies\f[R] option to write the required cookies into a
+file, and advise your downloader to read cookies from that file.
+Some sites also require a common user agent to be used, use
+\f[V]--dump-user-agent\f[R] to see the one in use by youtube-dl.
+You can also get necessary cookies and HTTP headers from JSON output
+obtained with \f[V]--dump-json\f[R].
+.PP
+It may be beneficial to use IPv6; in some cases, the restrictions are
+only applied to IPv4.
+Some services (sometimes only for a subset of videos) do not restrict
+the video URL by IP address, cookie, or user-agent, but these are the
+exception rather than the rule.
+.PP
+Please bear in mind that some URL protocols are \f[B]not\f[R] supported
+by browsers out of the box, including RTMP.
+If you are using \f[V]-g\f[R], your own downloader must support these as
+well.
+.PP
+If you want to play the video on a machine that is not running
+youtube-dl, you can relay the video content from the machine that runs
+youtube-dl.
+You can use \f[V]-o -\f[R] to let youtube-dl stream a video to stdout,
+or simply allow the player to download the files written by youtube-dl
+in turn.
+.SS ERROR: no fmt_url_map or conn information found in video info
+.PP
+YouTube has switched to a new video info format in July 2011 which is
+not supported by old versions of youtube-dl.
+See above for how to update youtube-dl.
+.SS ERROR: unable to download video
+.PP
+YouTube requires an additional signature since September 2012 which is
+not supported by old versions of youtube-dl.
+See above for how to update youtube-dl.
+.SS Video URL contains an ampersand and I\[cq]m getting some strange output \f[V][1] 2839\f[R] or \f[V]\[aq]v\[aq] is not recognized as an internal or external command\f[R]
+.PP
+That\[cq]s actually the output from your shell.
+Since ampersand is one of the special shell characters it\[cq]s
+interpreted by the shell preventing you from passing the whole URL to
+youtube-dl.
+To disable your shell from interpreting the ampersands (or any other
+special characters) you have to either put the whole URL in quotes or
+escape them with a backslash (which approach will work depends on your
+shell).
+.PP
+For example if your URL is
+https://www.youtube.com/watch?t=4&v=BaW_jenozKc you should end up with
+following command:
+.PP
+\f[V]youtube-dl \[aq]https://www.youtube.com/watch?t=4&v=BaW_jenozKc\[aq]\f[R]
+.PP
+or
+.PP
+\f[V]youtube-dl https://www.youtube.com/watch?t=4\[rs]&v=BaW_jenozKc\f[R]
+.PP
+For Windows you have to use the double quotes:
+.PP
+\f[V]youtube-dl \[dq]https://www.youtube.com/watch?t=4&v=BaW_jenozKc\[dq]\f[R]
+.SS ExtractorError: Could not find JS function u\[cq]OF\[cq]
+.PP
+In February 2015, the new YouTube player contained a character sequence
+in a string that was misinterpreted by old versions of youtube-dl.
+See above for how to update youtube-dl.
+.SS HTTP Error 429: Too Many Requests or 402: Payment Required
+.PP
+These two error codes indicate that the service is blocking your IP
+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\[cq]ve used for solving CAPTCHA with
+\f[V]--source-address\f[R].
+Also you may need to pass a \f[V]User-Agent\f[R] HTTP header of your
+browser with \f[V]--user-agent\f[R].
+.PP
+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 \f[V]--proxy\f[R] or \f[V]--source-address\f[R] options to
+select another IP address.
+.SS SyntaxError: Non-ASCII character
+.PP
+The error
+.IP
+.nf
+\f[C]
+File \[dq]youtube-dl\[dq], line 2
+SyntaxError: Non-ASCII character \[aq]\[rs]x93\[aq] ...
+\f[R]
+.fi
+.PP
+means you\[cq]re using an outdated version of Python.
+Please update to Python 2.6 or 2.7.
+.SS What is this binary file? Where has the code gone?
+.PP
+Since June 2012
+(#342 (https://github.com/ytdl-org/youtube-dl/issues/342)) youtube-dl is
+packed as an executable zipfile, simply unzip it (might need renaming to
+\f[V]youtube-dl.zip\f[R] first on some systems) or clone the git
+repository, as laid out above.
+If you modify the code, you can run it by executing the
+\f[V]__main__.py\f[R] file.
+To recompile the executable, run \f[V]make youtube-dl\f[R].
+.SS The exe throws an error due to missing \f[V]MSVCR100.dll\f[R]
+.PP
+To run the exe you need to install first the Microsoft Visual C++ 2010
+Service Pack 1 Redistributable Package
+(x86) (https://download.microsoft.com/download/1/6/5/165255E7-1014-4D0A-B094-B6A430A6BFFC/vcredist_x86.exe).
+.SS On Windows, how should I set up ffmpeg and youtube-dl? Where should I put the exe files?
+.PP
+If you put youtube-dl and ffmpeg in the same directory that you\[cq]re
+running the command from, it will work, but that\[cq]s rather
+cumbersome.
+.PP
+To make a different directory work - either for ffmpeg, or for
+youtube-dl, or for both - simply create the directory (say,
+\f[V]C:\[rs]bin\f[R], or
+\f[V]C:\[rs]Users\[rs]<User name>\[rs]bin\f[R]), put all the executables
+directly in there, and then set your PATH environment
+variable (https://www.java.com/en/download/help/path.xml) to include
+that directory.
+.PP
+From then on, after restarting your shell, you will be able to access
+both youtube-dl and ffmpeg (and youtube-dl will be able to find ffmpeg)
+by simply typing \f[V]youtube-dl\f[R] or \f[V]ffmpeg\f[R], no matter
+what directory you\[cq]re in.
+.SS How do I put downloads into a specific folder?
+.PP
+Use the \f[V]-o\f[R] to specify an output template, for example
+\f[V]-o \[dq]/home/user/videos/%(title)s-%(id)s.%(ext)s\[dq]\f[R].
+If you want this for all of your downloads, put the option into your
+configuration file.
+.SS How do I download a video starting with a \f[V]-\f[R]?
+.PP
+Either prepend \f[V]https://www.youtube.com/watch?v=\f[R] or separate
+the ID from the options with \f[V]--\f[R]:
+.IP
+.nf
+\f[C]
+youtube-dl -- -wNyEUrxzFU
+youtube-dl \[dq]https://www.youtube.com/watch?v=-wNyEUrxzFU\[dq]
+\f[R]
+.fi
+.SS How do I pass cookies to youtube-dl?
+.PP
+Use the \f[V]--cookies\f[R] option, for example
+\f[V]--cookies /path/to/cookies/file.txt\f[R].
+.PP
+In order to extract cookies from browser use any conforming browser
+extension for exporting cookies.
+For example, Get cookies.txt
+LOCALLY (https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
+(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
+first line of the cookies file must be either
+\f[V]# HTTP Cookie File\f[R] or \f[V]# Netscape HTTP Cookie File\f[R].
+Make sure you have correct newline
+format (https://en.wikipedia.org/wiki/Newline) in the cookies file and
+convert newlines if necessary to correspond with your OS, namely
+\f[V]CRLF\f[R] (\f[V]\[rs]r\[rs]n\f[R]) for Windows and \f[V]LF\f[R]
+(\f[V]\[rs]n\f[R]) for Unix and Unix-like systems (Linux, macOS, etc.).
+\f[V]HTTP Error 400: Bad Request\f[R] when using \f[V]--cookies\f[R] is
+a good sign of invalid newline format.
+.PP
+Passing cookies to youtube-dl is a good way to workaround login when a
+particular extractor does not implement it explicitly.
+Another use case is working around
+CAPTCHA (https://en.wikipedia.org/wiki/CAPTCHA) some websites require
+you to solve in particular cases in order to get access (e.g.\ YouTube,
+CloudFlare).
+.SS How do I stream directly to media player?
+.PP
+You will first need to tell youtube-dl to stream media to stdout with
+\f[V]-o -\f[R], 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 (https://www.videolan.org/) can be
+achieved with:
+.IP
+.nf
+\f[C]
+youtube-dl -o - \[dq]https://www.youtube.com/watch?v=BaW_jenozKcj\[dq] | vlc -
+\f[R]
+.fi
+.SS How do I download only new videos from a playlist?
+.PP
+Use download-archive feature.
+With this feature you should initially download the complete playlist
+with \f[V]--download-archive /path/to/download/archive/file.txt\f[R]
+that will record identifiers of all the videos in a special file.
+Each subsequent run with the same \f[V]--download-archive\f[R] will
+download only new videos and skip all videos that have been downloaded
+before.
+Note that only successful downloads are recorded in the file.
+.PP
+For example, at first,
+.IP
+.nf
+\f[C]
+youtube-dl --download-archive archive.txt \[dq]https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re\[dq]
+\f[R]
+.fi
+.PP
+will download the complete \f[V]PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re\f[R]
+playlist and create a file \f[V]archive.txt\f[R].
+Each subsequent run will only download new videos if any:
+.IP
+.nf
+\f[C]
+youtube-dl --download-archive archive.txt \[dq]https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re\[dq]
+\f[R]
+.fi
+.SS Should I add \f[V]--hls-prefer-native\f[R] into my config?
+.PP
+When youtube-dl detects an HLS video, it can download it either with the
+built-in downloader or ffmpeg.
+Since many HLS streams are slightly invalid and ffmpeg/youtube-dl each
+handle some invalid cases better than the other, there is an option to
+switch the downloader if needed.
+.PP
+When youtube-dl knows that one particular downloader works better for a
+given website, that downloader will be picked.
+Otherwise, youtube-dl will pick the best downloader for general
+compatibility, which at the moment happens to be ffmpeg.
+This choice may change in future versions of youtube-dl, with
+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 (https://ytdl-org.github.io/youtube-dl/supportedsites.html)
+cannot mandate one specific downloader.
+.PP
+If you put either \f[V]--hls-prefer-native\f[R] or
+\f[V]--hls-prefer-ffmpeg\f[R] into your configuration, a different
+subset of videos will fail to download correctly.
+Instead, it is much better to file an issue (https://yt-dl.org/bug) or a
+pull request which details why the native or the ffmpeg HLS downloader
+is a better choice for your use case.
+.SS Can you add support for this anime video site, or site which shows current movies for free?
+.PP
+As a matter of policy (as well as legality), youtube-dl does not include
+support for services that specialize in infringing copyright.
+As a rule of thumb, if you cannot easily find a video that the service
+is quite obviously allowed to distribute (i.e.\ that has been uploaded
+by the creator, the creator\[cq]s distributor, or is published under a
+free license), the service is probably unfit for inclusion to
+youtube-dl.
+.PP
+A note on the service that they don\[cq]t host the infringing content,
+but just link to those who do, is evidence that the service should
+\f[B]not\f[R] be included into youtube-dl.
+The same goes for any DMCA note when the whole front page of the service
+is filled with videos they are not allowed to distribute.
+A \[lq]fair use\[rq] note is equally unconvincing if the service shows
+copyright-protected videos in full without authorization.
+.PP
+Support requests for services that \f[B]do\f[R] purchase the rights to
+distribute their content are perfectly fine though.
+If in doubt, you can simply include a source that mentions the
+legitimate purchase of content.
+.SS How can I speed up work on my issue?
+.PP
+(Also known as: Help, my important issue not being solved!)
+The youtube-dl core developer team is quite small.
+While we do our best to solve as many issues as possible, sometimes that
+can take quite a while.
+To speed up your issue, here\[cq]s what you can do:
+.PP
+First of all, please do report the issue at our issue
+tracker (https://yt-dl.org/bugs).
+That allows us to coordinate all efforts by users and developers, and
+serves as a unified point.
+Unfortunately, the youtube-dl project has grown too large to use
+personal email as an effective communication channel.
+.PP
+Please read the bug reporting instructions below.
+A lot of bugs lack all the necessary information.
+If you can, offer proxy, VPN, or shell access to the youtube-dl
+developers.
+If you are able to, test the issue from multiple computers in multiple
+countries to exclude local censorship or misconfiguration issues.
+.PP
+If nobody is interested in solving your issue, you are welcome to take
+matters into your own hands and submit a pull request (or coerce/pay
+somebody else to do so).
+.PP
+Feel free to bump the issue from time to time by writing a small comment
+(\[lq]Issue is still present in youtube-dl version \&...from France, but
+fixed from Belgium\[rq]), but please not more than once a month.
+Please do not declare your issue as \f[V]important\f[R] or
+\f[V]urgent\f[R].
+.SS How can I detect whether a given URL is supported by youtube-dl?
+.PP
+For one, have a look at the list of supported sites.
+Note that it can sometimes happen that the site changes its URL scheme
+(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
+It is \f[I]not\f[R] possible to detect whether a URL is supported or
+not.
+That\[cq]s because youtube-dl contains a generic extractor which matches
+\f[B]all\f[R] URLs.
+You may be tempted to disable, exclude, or remove the generic extractor,
+but the generic extractor not only allows users to extract videos from
+lots of websites that embed a video from another service, but may also
+be used to extract video from a service that it\[cq]s hosting itself.
+Therefore, we neither recommend nor support disabling, excluding, or
+removing the generic extractor.
+.PP
+If you want to find out whether a given URL is supported, simply call
+youtube-dl with it.
+If you get no videos back, chances are the URL is either not referring
+to a video or unsupported.
+You can find out which by examining the output (if you run youtube-dl on
+the console) or catching an \f[V]UnsupportedError\f[R] exception if you
+run it from a Python program.
+.SH Why do I need to go through that much red tape when filing bugs?
+.PP
+Before we had the issue template, despite our extensive bug reporting
+instructions, 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 already reported multiple times
+before, because people did not actually read an error message, even if
+it said \[lq]please install ffmpeg\[rq], because people did not mention
+the URL they were trying to download and many more simple, easy-to-avoid
+problems, many of whom were totally unrelated to youtube-dl.
+.PP
+youtube-dl is an open-source project manned by too few volunteers, so
+we\[cq]d rather spend time fixing bugs where we are certain none of
+those simple problems apply, and where we can be reasonably confident to
+be able to reproduce the issue without asking the reporter repeatedly.
+As such, the output of \f[V]youtube-dl -v YOUR_URL_HERE\f[R] is really
+all that\[cq]s required to file an issue.
+The issue template also guides you through some basic steps you can do,
+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 (https://ytdl-org.github.io/youtube-dl/download.html) or get them
+from their distribution.
+.PP
+To run youtube-dl as a developer, you don\[cq]t need to build anything
+either.
+Simply execute
+.IP
+.nf
+\f[C]
+python -m youtube_dl
+\f[R]
+.fi
+.PP
+To run the test, simply invoke your favorite test runner, or execute a
+test file directly; any of the following work:
+.IP
+.nf
+\f[C]
+python -m unittest discover
+python test/test_download.py
+nosetests
+\f[R]
+.fi
+.PP
+See item 6 of new extractor tutorial for how to run extractor specific
+test cases.
+.PP
+If you want to create a build of youtube-dl yourself, you\[cq]ll need
+.IP \[bu] 2
+python
+.IP \[bu] 2
+make (only GNU make is supported)
+.IP \[bu] 2
+pandoc
+.IP \[bu] 2
+zip
+.IP \[bu] 2
+nosetests
+.SS Adding support for a new site
+.PP
+If you want to add support for a new site, first of all \f[B]make
+sure\f[R] this site is \f[B]not dedicated to copyright
+infringement\f[R].
+youtube-dl does \f[B]not support\f[R] such sites thus pull requests
+adding support for them \f[B]will be rejected\f[R].
+.PP
+After you have ensured this site is distributing its content legally,
+you can follow this quick list (assuming your service is called
+\f[V]yourextractor\f[R]):
+.IP " 1." 4
+Fork this repository (https://github.com/ytdl-org/youtube-dl/fork)
+.IP " 2." 4
+Check out the source code with:
+.RS 4
+.IP
+.nf
+\f[C]
+ git clone git\[at]github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
+\f[R]
+.fi
+.RE
+.IP " 3." 4
+Start a new git branch with
+.RS 4
+.IP
+.nf
+\f[C]
+ cd youtube-dl
+ git checkout -b yourextractor
+\f[R]
+.fi
+.RE
+.IP " 4." 4
+Start with this simple template and save it to
+\f[V]youtube_dl/extractor/yourextractor.py\f[R]:
+.RS 4
+.IP
+.nf
+\f[C]
+# coding: utf-8
+from __future__ import unicode_literals
+
+from .common import InfoExtractor
+
+
+class YourExtractorIE(InfoExtractor):
+    _VALID_URL = r\[aq]https?://(?:www\[rs].)?yourextractor\[rs].com/watch/(?P<id>[0-9]+)\[aq]
+    _TEST = {
+        \[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],
+            \[aq]ext\[aq]: \[aq]mp4\[aq],
+            \[aq]title\[aq]: \[aq]Video title goes here\[aq],
+            \[aq]thumbnail\[aq]: r\[aq]re:\[ha]https?://.*\[rs].jpg$\[aq],
+            # TODO more properties, either as:
+            # * A value
+            # * MD5 checksum; start the string with md5:
+            # * A regular expression; start the string with re:
+            # * Any Python type (for example int or float)
+        }
+    }
+
+    def _real_extract(self, url):
+        video_id = self._match_id(url)
+        webpage = self._download_webpage(url, video_id)
+
+        # TODO more code goes here, for example ...
+        title = self._html_search_regex(r\[aq]<h1>(.+?)</h1>\[aq], webpage, \[aq]title\[aq])
+
+        return {
+            \[aq]id\[aq]: video_id,
+            \[aq]title\[aq]: title,
+            \[aq]description\[aq]: self._og_search_description(webpage),
+            \[aq]uploader\[aq]: self._search_regex(r\[aq]<div[\[ha]>]+id=\[dq]uploader\[dq][\[ha]>]*>([\[ha]<]+)<\[aq], webpage, \[aq]uploader\[aq], fatal=False),
+            # TODO more properties (see youtube_dl/extractor/common.py)
+        }
+\f[R]
+.fi
+.RE
+.IP " 5." 4
+Add an import in
+\f[V]youtube_dl/extractor/extractors.py\f[R] (https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/extractors.py).
+.IP " 6." 4
+Run
+\f[V]python test/test_download.py TestDownload.test_YourExtractor\f[R].
+This \f[I]should fail\f[R] at first, but you can continually re-run it
+until you\[cq]re done.
+If you decide to add more than one test (actually, test case) then
+rename \f[V]_TEST\f[R] to \f[V]_TESTS\f[R] and make it into a list of
+dictionaries.
+The tests will then be named \f[V]TestDownload.test_YourExtractor\f[R],
+\f[V]TestDownload.test_YourExtractor_1\f[R],
+\f[V]TestDownload.test_YourExtractor_2\f[R], etc.
+Note:
+.RS 4
+.IP \[bu] 2
+the test names use the extractor class name \f[B]without the trailing
+\f[VB]IE\f[B]\f[R]
+.IP \[bu] 2
+tests with \f[V]only_matching\f[R] key in test\[cq]s dict are not
+counted.
+.RE
+.IP " 7." 4
+Have a look at
+\f[V]youtube_dl/extractor/common.py\f[R] (https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/common.py)
+for possible helper methods and a detailed description of what your
+extractor should and may
+return (https://github.com/ytdl-org/youtube-dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extractor/common.py#L94-L303).
+Add tests and code for as many as you want.
+.IP " 8." 4
+Make sure your code follows youtube-dl coding conventions and check the
+code with
+flake8 (https://flake8.pycqa.org/en/latest/index.html#quickstart):
+.RS 4
+.IP
+.nf
+\f[C]
+ $ flake8 youtube_dl/extractor/yourextractor.py
+\f[R]
+.fi
+.RE
+.IP " 9." 4
+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 "10." 4
+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
+\f[C]
+$ git add youtube_dl/extractor/extractors.py
+$ git add youtube_dl/extractor/yourextractor.py
+$ git commit -m \[aq][yourextractor] Add new extractor\[aq]
+$ git push origin yourextractor
+\f[R]
+.fi
+.RE
+.IP "11." 4
+Finally, create a pull
+request (https://help.github.com/articles/creating-a-pull-request).
+We\[cq]ll then review and merge it.
+.PP
+In any case, thank you very much for your contributions!
+.SS youtube-dl coding conventions
+.PP
+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 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
+dependency on the source\[cq]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 a fix incorporated, all the previous versions
+become broken in all repositories and distros\[cq] 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 an information
+dictionary (https://github.com/ytdl-org/youtube-dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extractor/common.py#L94-L303)
+or simply \f[I]info dict\f[R].
+Only the following meta fields in the \f[I]info dict\f[R] are considered
+mandatory for a successful extraction process by youtube-dl:
+.IP \[bu] 2
+\f[V]id\f[R] (media identifier)
+.IP \[bu] 2
+\f[V]title\f[R] (media title)
+.IP \[bu] 2
+\f[V]url\f[R] (media download URL) or \f[V]formats\f[R]
+.PP
+In fact only the last option is technically mandatory (i.e.\ if you
+can\[cq]t figure out the download location of the media the extraction
+does not make any sense).
+But by convention youtube-dl also treats \f[V]id\f[R] and
+\f[V]title\f[R] 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/ytdl-org/youtube-dl/blob/7f41a598b3fba1bcab2817de64a08941200aa3c8/youtube_dl/extractor/common.py#L188-L303)
+apart from the aforementioned ones are considered \f[B]optional\f[R].
+That means that extraction should be \f[B]tolerant\f[R] 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[R] in
+order not to break the extraction of general purpose mandatory fields.
+.SS Example
+.PP
+Say you have some source dictionary \f[V]meta\f[R] that you\[cq]ve
+fetched as JSON with HTTP request and it has a key \f[V]summary\f[R]:
+.IP
+.nf
+\f[C]
+meta = self._download_json(url, video_id)
+\f[R]
+.fi
+.PP
+Assume at this point \f[V]meta\f[R]\[cq]s layout is:
+.IP
+.nf
+\f[C]
+{
+    ...
+    \[dq]summary\[dq]: \[dq]some fancy summary text\[dq],
+    ...
+}
+\f[R]
+.fi
+.PP
+Assume you want to extract \f[V]summary\f[R] and put it into the
+resulting info dict as \f[V]description\f[R].
+Since \f[V]description\f[R] is an optional meta field you should be
+ready that this key may be missing from the \f[V]meta\f[R] dict, so that
+you should extract it like:
+.IP
+.nf
+\f[C]
+description = meta.get(\[aq]summary\[aq])  # correct
+\f[R]
+.fi
+.PP
+and not like:
+.IP
+.nf
+\f[C]
+description = meta[\[aq]summary\[aq]]  # incorrect
+\f[R]
+.fi
+.PP
+The latter will break extraction process with \f[V]KeyError\f[R] if
+\f[V]summary\f[R] disappears from \f[V]meta\f[R] at some later time but
+with the former approach extraction will just go ahead with
+\f[V]description\f[R] set to \f[V]None\f[R] which is perfectly fine
+(remember \f[V]None\f[R] is equivalent to the absence of data).
+.PP
+Similarly, you should pass \f[V]fatal=False\f[R] when extracting
+optional data from a webpage with \f[V]_search_regex\f[R],
+\f[V]_html_search_regex\f[R] or similar methods, for instance:
+.IP
+.nf
+\f[C]
+description = self._search_regex(
+    r\[aq]<span[\[ha]>]+id=\[dq]title\[dq][\[ha]>]*>([\[ha]<]+)<\[aq],
+    webpage, \[aq]description\[aq], fatal=False)
+\f[R]
+.fi
+.PP
+With \f[V]fatal\f[R] set to \f[V]False\f[R] if \f[V]_search_regex\f[R]
+fails to extract \f[V]description\f[R] it will emit a warning and
+continue extraction.
+.PP
+You can also pass \f[V]default=<some fallback value>\f[R], for example:
+.IP
+.nf
+\f[C]
+description = self._search_regex(
+    r\[aq]<span[\[ha]>]+id=\[dq]title\[dq][\[ha]>]*>([\[ha]<]+)<\[aq],
+    webpage, \[aq]description\[aq], default=None)
+\f[R]
+.fi
+.PP
+On failure this code will silently continue the extraction with
+\f[V]description\f[R] set to \f[V]None\f[R].
+That is useful for metafields that may or may not be present.
+.SS Provide fallbacks
+.PP
+When extracting metadata try to do so from multiple sources.
+For example if \f[V]title\f[R] is present in several places, try
+extracting from at least some of them.
+This makes it more future-proof in case some of the sources become
+unavailable.
+.SS Example
+.PP
+Say \f[V]meta\f[R] from the previous example has a \f[V]title\f[R] and
+you are about to extract it.
+Since \f[V]title\f[R] is a mandatory meta field you should end up with
+something like:
+.IP
+.nf
+\f[C]
+title = meta[\[aq]title\[aq]]
+\f[R]
+.fi
+.PP
+If \f[V]title\f[R] disappears from \f[V]meta\f[R] in future due to some
+changes on the hoster\[cq]s side the extraction would fail since
+\f[V]title\f[R] is mandatory.
+That\[cq]s expected.
+.PP
+Assume that you have some another source you can extract \f[V]title\f[R]
+from, for example \f[V]og:title\f[R] HTML meta of a \f[V]webpage\f[R].
+In this case you can provide a fallback scenario:
+.IP
+.nf
+\f[C]
+title = meta.get(\[aq]title\[aq]) or self._og_search_title(webpage)
+\f[R]
+.fi
+.PP
+This code will try to extract from \f[V]meta\f[R] first and if it fails
+it will try extracting \f[V]og:title\f[R] from a \f[V]webpage\f[R].
+.SS Regular expressions
+.SS Don\[cq]t capture groups you don\[cq]t use
+.PP
+Capturing group must be an indication that it\[cq]s used somewhere in
+the code.
+Any group that is not used must be non capturing.
+.SS Example
+.PP
+Don\[cq]t capture id attribute name here since you can\[cq]t use it for
+anything anyway.
+.PP
+Correct:
+.IP
+.nf
+\f[C]
+r\[aq](?:id|ID)=(?P<id>\[rs]d+)\[aq]
+\f[R]
+.fi
+.PP
+Incorrect:
+.IP
+.nf
+\f[C]
+r\[aq](id|ID)=(?P<id>\[rs]d+)\[aq]
+\f[R]
+.fi
+.SS Make regular expressions relaxed and flexible
+.PP
+When using regular expressions try to write them fuzzy, relaxed and
+flexible, skipping insignificant parts that are more likely to change,
+allowing both single and double quotes for quoted values and so on.
+.SS Example
+.PP
+Say you need to extract \f[V]title\f[R] from the following HTML code:
+.IP
+.nf
+\f[C]
+<span style=\[dq]position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;\[dq] class=\[dq]title\[dq]>some fancy title</span>
+\f[R]
+.fi
+.PP
+The code for that task should look similar to:
+.IP
+.nf
+\f[C]
+title = self._search_regex(
+    r\[aq]<span[\[ha]>]+class=\[dq]title\[dq][\[ha]>]*>([\[ha]<]+)\[aq], webpage, \[aq]title\[aq])
+\f[R]
+.fi
+.PP
+Or even better:
+.IP
+.nf
+\f[C]
+title = self._search_regex(
+    r\[aq]<span[\[ha]>]+class=([\[dq]\[rs]\[aq]])title\[rs]1[\[ha]>]*>(?P<title>[\[ha]<]+)\[aq],
+    webpage, \[aq]title\[aq], group=\[aq]title\[aq])
+\f[R]
+.fi
+.PP
+Note how you tolerate potential changes in the \f[V]style\f[R]
+attribute\[cq]s value or switch from using double quotes to single for
+\f[V]class\f[R] attribute:
+.PP
+The code definitely should not look like:
+.IP
+.nf
+\f[C]
+title = self._search_regex(
+    r\[aq]<span style=\[dq]position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;\[dq] class=\[dq]title\[dq]>(.*?)</span>\[aq],
+    webpage, \[aq]title\[aq], group=\[aq]title\[aq])
+\f[R]
+.fi
+.SS Long lines policy
+.PP
+There is a soft limit to keep lines of code under 80 characters long.
+This means it should be respected if possible and if it does not make
+readability and code maintenance worse.
+.PP
+For example, you should \f[B]never\f[R] split long string literals like
+URLs or some other often copied entities over multiple lines to fit this
+limit:
+.PP
+Correct:
+.IP
+.nf
+\f[C]
+\[aq]https://www.youtube.com/watch?v=FqZTN594JQw&list=PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4\[aq]
+\f[R]
+.fi
+.PP
+Incorrect:
+.IP
+.nf
+\f[C]
+\[aq]https://www.youtube.com/watch?v=FqZTN594JQw&list=\[aq]
+\[aq]PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4\[aq]
+\f[R]
+.fi
+.SS Inline values
+.PP
+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.
+.SS Example
+.PP
+Correct:
+.IP
+.nf
+\f[C]
+title = self._html_search_regex(r\[aq]<title>([\[ha]<]+)</title>\[aq], webpage, \[aq]title\[aq])
+\f[R]
+.fi
+.PP
+Incorrect:
+.IP
+.nf
+\f[C]
+TITLE_RE = r\[aq]<title>([\[ha]<]+)</title>\[aq]
+# ...some lines of code...
+title = self._html_search_regex(TITLE_RE, webpage, \[aq]title\[aq])
+\f[R]
+.fi
+.SS Collapse fallbacks
+.PP
+Multiple fallback values can quickly become unwieldy.
+Collapse multiple fallback values into a single expression via a list of
+patterns.
+.SS Example
+.PP
+Good:
+.IP
+.nf
+\f[C]
+description = self._html_search_meta(
+    [\[aq]og:description\[aq], \[aq]description\[aq], \[aq]twitter:description\[aq]],
+    webpage, \[aq]description\[aq], default=None)
+\f[R]
+.fi
+.PP
+Unwieldy:
+.IP
+.nf
+\f[C]
+description = (
+    self._og_search_description(webpage, default=None)
+    or self._html_search_meta(\[aq]description\[aq], webpage, default=None)
+    or self._html_search_meta(\[aq]twitter:description\[aq], webpage, default=None))
+\f[R]
+.fi
+.PP
+Methods supporting list of patterns are: \f[V]_search_regex\f[R],
+\f[V]_html_search_regex\f[R], \f[V]_og_search_property\f[R],
+\f[V]_html_search_meta\f[R].
+.SS Trailing parentheses
+.PP
+Always move trailing parentheses after the last argument.
+.SS Example
+.PP
+Correct:
+.IP
+.nf
+\f[C]
+    lambda x: x[\[aq]ResultSet\[aq]][\[aq]Result\[aq]][0][\[aq]VideoUrlSet\[aq]][\[aq]VideoUrl\[aq]],
+    list)
+\f[R]
+.fi
+.PP
+Incorrect:
+.IP
+.nf
+\f[C]
+    lambda x: x[\[aq]ResultSet\[aq]][\[aq]Result\[aq]][0][\[aq]VideoUrlSet\[aq]][\[aq]VideoUrl\[aq]],
+    list,
+)
+\f[R]
+.fi
+.SS Use convenience conversion and parsing functions
+.PP
+Wrap all extracted numeric data into safe functions from
+\f[V]youtube_dl/utils.py\f[R] (https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/utils.py):
+\f[V]int_or_none\f[R], \f[V]float_or_none\f[R].
+Use them for string to number conversions as well.
+.PP
+Use \f[V]url_or_none\f[R] for safe URL processing.
+.PP
+Use \f[V]try_get\f[R] for safe metadata extraction from parsed JSON.
+.PP
+Use \f[V]unified_strdate\f[R] for uniform \f[V]upload_date\f[R] or any
+\f[V]YYYYMMDD\f[R] meta field extraction, \f[V]unified_timestamp\f[R]
+for uniform \f[V]timestamp\f[R] extraction, \f[V]parse_filesize\f[R] for
+\f[V]filesize\f[R] extraction, \f[V]parse_count\f[R] for count meta
+fields extraction, \f[V]parse_resolution\f[R], \f[V]parse_duration\f[R]
+for \f[V]duration\f[R] extraction, \f[V]parse_age_limit\f[R] for
+\f[V]age_limit\f[R] extraction.
+.PP
+Explore
+\f[V]youtube_dl/utils.py\f[R] (https://github.com/ytdl-org/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[R]
+.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[R]
+.fi
+.SH EMBEDDING YOUTUBE-DL
+.PP
+youtube-dl makes the best effort to be a good command-line program, and
+thus should be callable from any programming language.
+If you encounter any problems parsing its output, feel free to create a
+report (https://github.com/ytdl-org/youtube-dl/issues/new).
+.PP
+From a Python program, you can embed youtube-dl in a more powerful
+fashion, like this:
+.IP
+.nf
+\f[C]
+from __future__ import unicode_literals
+import youtube_dl
+
+ydl_opts = {}
+with youtube_dl.YoutubeDL(ydl_opts) as ydl:
+    ydl.download([\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
+\f[R]
+.fi
+.PP
+Most likely, you\[cq]ll want to use various options.
+For a list of options available, have a look at
+\f[V]youtube_dl/YoutubeDL.py\f[R] (https://github.com/ytdl-org/youtube-dl/blob/3e4cedf9e8cd3157df2457df7274d0c842421945/youtube_dl/YoutubeDL.py#L137-L312).
+For a start, if you want to intercept youtube-dl\[cq]s output, set a
+\f[V]logger\f[R] object.
+.PP
+Here\[cq]s a more complete example of a program that outputs only errors
+(and a short message after the download is finished), and
+downloads/converts the video to an mp3 file:
+.IP
+.nf
+\f[C]
+from __future__ import unicode_literals
+import youtube_dl
+
+
+class MyLogger(object):
+    def debug(self, msg):
+        pass
+
+    def warning(self, msg):
+        pass
+
+    def error(self, msg):
+        print(msg)
+
+
+def my_hook(d):
+    if d[\[aq]status\[aq]] == \[aq]finished\[aq]:
+        print(\[aq]Done downloading, now converting ...\[aq])
+
+
+ydl_opts = {
+    \[aq]format\[aq]: \[aq]bestaudio/best\[aq],
+    \[aq]postprocessors\[aq]: [{
+        \[aq]key\[aq]: \[aq]FFmpegExtractAudio\[aq],
+        \[aq]preferredcodec\[aq]: \[aq]mp3\[aq],
+        \[aq]preferredquality\[aq]: \[aq]192\[aq],
+    }],
+    \[aq]logger\[aq]: MyLogger(),
+    \[aq]progress_hooks\[aq]: [my_hook],
+}
+with youtube_dl.YoutubeDL(ydl_opts) as ydl:
+    ydl.download([\[aq]https://www.youtube.com/watch?v=BaW_jenozKc\[aq]])
+\f[R]
+.fi
+.SH BUGS
+.PP
+Bugs and suggestions should be reported in the issue tracker:
+<https://github.com/ytdl-org/youtube-dl/issues> (<https://yt-dl.org/bug>
+is an alias for this).
+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 (irc://chat.freenode.net/#youtube-dl) on freenode
+(webchat (https://webchat.freenode.net/?randomnick=1&channels=youtube-dl)).
+.SS Opening a bug report or suggestion
+.PP
+Be sure to follow instructions provided \f[B]below\f[R] and \f[B]in the
+issue tracker\f[R].
+Complete the appropriate issue template fully.
+Consider whether your problem is covered by an existing issue: if so,
+follow the discussion there.
+Avoid commenting on existing duplicate issues as such comments do not
+add to the discussion of the issue and are liable to be treated as spam.
+.PP
+\f[B]Please include the full output of youtube-dl when run with
+\f[VB]-v\f[B]\f[R], i.e.\ \f[B]add\f[R] \f[V]-v\f[R] flag to \f[B]your
+command line\f[R], copy the \f[B]whole\f[R] output and post it in the
+issue body wrapped in \[ga]\[ga]\[ga] for better formatting.
+It should look similar to this:
+.IP
+.nf
+\f[C]
+$ youtube-dl -v <your command line>
+[debug] System config: []
+[debug] User config: []
+[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
+[debug] Python version 2.6.6 - Windows-2003Server-5.2.3790-SP2
+[debug] exe versions: ffmpeg N-75573-g1d0487f, ffprobe N-75573-g1d0487f, rtmpdump 2.4
+[debug] Proxy map: {}
+\&...
+\f[R]
+.fi
+.PP
+\f[B]Do not post screenshots of verbose logs; only plain text is
+acceptable.\f[R]
+.PP
+The output (including the first lines) contains important debugging
+information.
+Issues without the full output are often not reproducible and therefore
+do not get solved in short order, if ever.
+.PP
+Finally please review your issue to avoid various common mistakes (you
+can and should use this as a checklist) listed below.
+.SS Is the description of the issue itself sufficient?
+.PP
+We often get issue reports that are hard to understand.
+To avoid subsequent clarifications, and to assist participants who are
+not native English speakers, please elaborate on what feature you are
+requesting, or what bug you want to be fixed.
+.PP
+Make sure that it\[cq]s obvious
+.IP \[bu] 2
+What the problem is
+.IP \[bu] 2
+How it could be fixed
+.IP \[bu] 2
+How your proposed solution would look
+.PP
+If your report is shorter than two lines, it is almost certainly missing
+some of these, which makes it hard for us to respond to it.
+We\[cq]re often too polite to close the issue outright, but the missing
+info makes misinterpretation likely.
+As a committer myself, I often get frustrated by these issues, since the
+only possible way for me to move forward on them is to ask for
+clarification over and over.
+.PP
+For bug reports, this means that your report should contain the
+\f[I]complete\f[R] output of youtube-dl when called with the
+\f[V]-v\f[R] flag.
+The error message you get for (most) bugs even says so, but you would
+not believe how many of our bug reports do not contain this information.
+.PP
+If your server has multiple IPs or you suspect censorship, adding
+\f[V]--call-home\f[R] may be a good idea to get more diagnostics.
+If the error is \f[V]ERROR: Unable to extract ...\f[R] and you cannot
+reproduce it from multiple countries, add \f[V]--dump-pages\f[R]
+(warning: this will yield a rather large output, redirect it to the file
+\f[V]log.txt\f[R] by adding \f[V]>log.txt 2>&1\f[R] to your
+command-line) or upload the \f[V].dump\f[R] files you get when you add
+\f[V]--write-pages\f[R] somewhere (https://gist.github.com/).
+.PP
+\f[B]Site support requests must contain an example URL\f[R].
+An example URL is a URL you might want to download, like
+\f[V]https://www.youtube.com/watch?v=BaW_jenozKc\f[R].
+There should be an obvious video present.
+Except under very special circumstances, the main page of a video
+service (e.g.\ \f[V]https://www.youtube.com/\f[R]) is \f[I]not\f[R] an
+example URL.
+.SS Is the issue already documented?
+.PP
+Make sure that someone has not already opened the issue you\[cq]re
+trying to open.
+Search at the top of the window or browse the GitHub
+Issues (https://github.com/ytdl-org/youtube-dl/search?type=Issues) of
+this repository.
+Initially, at least, use the search term \f[V]-label:duplicate\f[R] to
+focus on active issues.
+If there is an issue, feel free to write something along the lines of
+\[lq]This affects me as well, with version 2015.01.01.
+Here is some more information on the issue: \&...\[rq].
+While some issues may be old, a new post into them often spurs rapid
+activity.
+.SS Are you using the latest version?
+.PP
+Before reporting any issue, type \f[V]youtube-dl -U\f[R].
+This should report that you\[cq]re up-to-date.
+About 20% of the reports we receive are already fixed, but people are
+using outdated versions.
+This goes for feature requests as well.
+.SS Why are existing options not enough?
+.PP
+Before requesting a new feature, please have a quick peek at the list of
+supported
+options (https://github.com/ytdl-org/youtube-dl/blob/master/README.md#options).
+Many feature requests are for features that actually exist already!
+Please, absolutely do show off your work in the issue report and detail
+how the existing similar options do \f[I]not\f[R] solve your problem.
+.SS Is there enough context in your bug report?
+.PP
+People want to solve problems, and often think they do us a favor by
+breaking down their larger problems (e.g.\ wanting to skip already
+downloaded files) to a specific request (e.g.\ requesting us to look
+whether the file exists before downloading the info page).
+However, what often happens is that they break down the problem into two
+steps: One simple, and one impossible (or extremely complicated one).
+.PP
+We are then presented with a very complicated request when the original
+problem could be solved far easier, e.g.\ by recording the downloaded
+video IDs in a separate file.
+To avoid this, you must include the greater context where it is
+non-obvious.
+In particular, every feature request that does not consist of adding
+support for a new site should contain a use case scenario that explains
+in what situation the missing feature would be useful.
+.SS Does the issue involve one problem, and one problem only?
+.PP
+Some of our users seem to think there is a limit of issues they can or
+should open.
+There is no limit of issues they can or should open.
+While it may seem appealing to be able to dump all your issues into one
+ticket, that means that someone who solves one of your issues cannot
+mark the issue as closed.
+Typically, reporting a bunch of issues leads to the ticket lingering
+since nobody wants to attack that behemoth, until someone mercifully
+splits the issue into multiple ones.
+.PP
+In particular, every site support request issue should only pertain to
+services at one site (generally under a common domain, but always using
+the same backend technology).
+Do not request support for vimeo user videos, White house podcasts, and
+Google Plus pages in the same issue.
+Also, make sure that you don\[cq]t post bug reports alongside feature
+requests.
+As a rule of thumb, a feature request does not include outputs of
+youtube-dl that are not immediately related to the feature at hand.
+Do not post reports of a network error alongside the request for a new
+video service.
+.SS Is anyone going to need the feature?
+.PP
+Only post features that you (or an incapacitated friend you can
+personally talk to) require.
+Do not post features because they seem like a good idea.
+If they are really useful, they will be requested by someone who
+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\[cq]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.
+On the other hand, if your UI for youtube-dl fails in some way you
+believe is related to youtube-dl, by all means, go ahead and report the
+bug.
+.SH COPYRIGHT
+.PP
+youtube-dl is released into the public domain by the copyright holders.
+.PP
+This README file was originally written by Daniel
+Bolton (https://github.com/dbbolton) and is likewise released into the
+public domain.
diff --git a/network/youtube-dl/youtube-dl.SlackBuild b/network/youtube-dl/youtube-dl.SlackBuild
index ef646435d096..24dc489070e0 100644
--- a/network/youtube-dl/youtube-dl.SlackBuild
+++ b/network/youtube-dl/youtube-dl.SlackBuild
@@ -23,6 +23,11 @@
 #  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 #  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+# 20230627 bkw: Modified by SlackBuilds.org, BUILD=2:
+# - include the man page and shell completions in the package.
+# - get rid of empty (and wrong) /usr/doc/youtube_dl/ dir.
+# - get rid of doinst.sh: there is no need for update-desktop-database as
+#   there are no .desktop files in the package.
 
 # Date: 20/06/2023
 # Many Thanks to B. Watson for the tool git2tarxz.sh
@@ -32,7 +37,7 @@ cd $(dirname $0) ; CWD=$(pwd)
 
 PRGNAM=youtube-dl
 VERSION=${VERSION:-2021.12.17+20230618_07af47960}
-BUILD=${BUILD:-1}
+BUILD=${BUILD:-2}
 TAG=${TAG:-_SBo}
 PKGTYPE=${PKGTYPE:-tgz}
 
@@ -44,9 +49,6 @@ if [ -z "$ARCH" ]; then
   esac
 fi
 
-# If the variable PRINT_PACKAGE_NAME is set, then this script will report what
-# the name of the created package would be, and then exit. This information
-# could be useful to other scripts.
 if [ ! -z "${PRINT_PACKAGE_NAME}" ]; then
   echo "$PRGNAM-$VERSION-$ARCH-$BUILD$TAG.$PKGTYPE"
   exit 0
@@ -82,18 +84,29 @@ cd $PRGNAM-$VERSION
 chown -R root:root .
 find -L . \
  \( -perm 777 -o -perm 775 -o -perm 750 -o -perm 711 -o -perm 555 \
-  -o -perm 511 \) -exec chmod 755 {} \; -o \
+  -o -perm 511 \) -exec chmod 755 {} + -o \
  \( -perm 666 -o -perm 664 -o -perm 640 -o -perm 600 -o -perm 444 \
-  -o -perm 440 -o -perm 400 \) -exec chmod 644 {} \;
+  -o -perm 440 -o -perm 400 \) -exec chmod 644 {} +
 
 # setup.py patch
 patch -p1 < $CWD/setup.patch
 
+# 20230627 bkw: building the man page would require pandoc or pandoc-bin.
+# Easier to just include the prebuilt manpage in the SBo repo.
+cat $CWD/$PRGNAM.1 > $PRGNAM.1
+
+# 20230627 bkw: Unusual for a python build, we need this for the man page
+# and shell completions. It also installs the all-in-one youtube-dl
+# 'frozen' binary, which we don't want, but setup.py will overwrite that.
+make install DESTDIR=$PKG PREFIX=/usr MANDIR=/usr/man
+
 python2 setup.py install --root=$PKG
 python3 setup.py install --root=$PKG
 
-find $PKG/usr/man -type f -exec gzip -9 {} \;
-for i in $( find $PKG/usr/man -type l ) ; do ln -s $( readlink $i ).gz $i.gz ; rm $i ; done
+gzip $PKG/usr/man/man*/*
+
+# 20230627 bkw: this empty dir gets created, but we don't need it.
+rmdir $PKG/usr/doc/youtube_dl
 
 mkdir -p $PKG/usr/doc/$PRGNAM-$VERSION
 cp -a README.md LICENSE AUTHORS ChangeLog $PKG/usr/doc/$PRGNAM-$VERSION
@@ -101,7 +114,6 @@ cat $CWD/$PRGNAM.SlackBuild > $PKG/usr/doc/$PRGNAM-$VERSION/$PRGNAM.SlackBuild
 
 mkdir -p $PKG/install
 cat $CWD/slack-desc > $PKG/install/slack-desc
-cat $CWD/doinst.sh > $PKG/install/doinst.sh
 
 cd $PKG
 /sbin/makepkg -l y -c n $OUTPUT/$PRGNAM-$VERSION-$ARCH-$BUILD$TAG.$PKGTYPE