From fbbfbfc772124ecbace571709e275496b47cc183 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 21 Feb 2020 00:30:41 +0100 Subject: manpage: reorganize ytdl_hook option descriptions Make it a proper list, instead of a paragraph soup. --- DOCS/man/options.rst | 117 +++++++++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 51 deletions(-) diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 59cab84619..d181279a41 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -810,57 +810,72 @@ Program Behavior If the script can't do anything with an URL, it will do nothing. - The ``try_ytdl_first`` script option accepts a boolean 'yes' or 'no', and if - 'yes' will try parsing the URL with youtube-dl first, instead of the default - where it's only after mpv failed to open it. This mostly depends on whether - most of your URLs need youtube-dl parsing. - - The ``exclude`` script option accepts a ``|``-separated list of URL patterns - which mpv should not use with youtube-dl. The patterns are matched after - the ``http(s)://`` part of the URL. - - ``^`` matches the beginning of the URL, ``$`` matches its end, and you - should use ``%`` before any of the characters ``^$()%|,.[]*+-?`` to match - that character. - - .. admonition:: Examples - - - ``--script-opts=ytdl_hook-exclude='^youtube%.com'`` - will exclude any URL that starts with ``http://youtube.com`` or - ``https://youtube.com``. - - ``--script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$'`` - will exclude any URL that ends with ``.mkv`` or ``.mp4``. - - See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1 - - The ``all_formats`` script option accepts a boolean 'yes' or 'no', - and if 'yes' will attempt to add all formats found reported by youtube-dl - (default: no). Each format is added as a separate track. In addition, they - are delay-loaded, and actually opened only when a track is selected (this - should keep load times as low as without this option). It also adds average - bitrate metadata, if available, which means ``--hls-bitrate`` will decide - which track to select. (HLS used to be the only format whose alternative - quality streams were exposed in a similar way, thus the option name.) The - ``--ytdl-format`` option is essentially ignored. Although this mechanism - makes it possible to switch streams at runtime, it's not suitable for this - purpose for various technical reasons. In general, this option is not - useful, and was only added to show that it's possible. - - The ``skip_muxed`` script option is a boolean (default: yes). It is used - only if ``all_formats`` is set. If set to 'yes', it will skip formats that - have both audio and video streams. Some sites that provide multiple - qualities will do so with separated audio and video streams (which is what - ``all_formats`` is supposed to make use of), still provide formats that - include both audio and video. We assume that they do so for compatibility - reasons, and ``skip_muxed`` filters them out. This will make loading faster, - and potentially avoid wasting bandwidth by using only one stream of a muxed - stream. On the other hand, if muxed streams are present, but the separate - streams lack either video or audio or do not exist at all, then the stream - selection as done by youtube-dl (via ``--ytdl-format``) is used. - - The ``use_manifests`` script option makes mpv use the master manifest URL for - formats like HLS and DASH, if available, allowing for video/audio selection - in runtime. It's disabled ("no") by default for performance reasons. + This accepts a set of options, which can be passed to it with the + ``--script-opts`` option (using ``ytdl_hook-`` as prefix): + + ``try_ytdl_first=`` + + If 'yes' will try parsing the URL with youtube-dl first, instead of the + default where it's only after mpv failed to open it. This mostly depends + on whether most of your URLs need youtube-dl parsing. + + ``exclude=`` + If 'yes' will attempt to add all formats found reported by youtube-dl + (default: no). Each format is added as a separate track. In addition, + they are delay-loaded, and actually opened only when a track is selected + (this should keep load times as low as without this option). It also + adds average bitrate metadata, if available, which means + ``--hls-bitrate`` will decide which track to select. (HLS used to be the + only format whose alternative quality streams were exposed in a similar + way, thus the option name.) + + The ``--ytdl-format`` option is essentially ignored. + + Although this mechanism makes it possible to switch streams at runtime, + it's not suitable for this purpose for various technical reasons. (It's + slow, which can't be really fixed.) In general, this option is not + useful, and was only added to show that it's possible. + + ``skip_muxed=`` + If set to 'yes', and ``all_formats`` is also set to 'yes', this will + skip formats that have both audio and video streams (default: yes). + + Some sites that provide multiple qualities will do so with separated + audio and video streams (which is what ``all_formats`` is supposed to + make use of), still provide formats that include both audio and video. + We assume that they do so for compatibility reasons, and ``skip_muxed`` + filters them out. This will make loading faster, and potentially avoid + wasting bandwidth by using only one stream of a muxed stream. On the + other hand, if muxed streams are present, but the separate streams lack + either video or audio or do not exist at all, then the stream selection + as done by youtube-dl (via ``--ytdl-format``) is used. + + This appears to terribly break with some sites that provide a HLS master + playlist on the lowest level. + + ``use_manifests=`` + Make mpv use the master manifest URL for formats like HLS and DASH, + if available, allowing for video/audio selection in runtime (default: + no). It's disabled ("no") by default for performance reasons. .. admonition:: Why do the option names mix ``_`` and ``-``? -- cgit v1.2.3