Adding upstream version 0.38.0.upstream/0.38.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 362 insertions, 309 deletions

diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index e0445d4..9f17345 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -46,7 +46,7 @@ Track Selection
 
     ``--audio`` is an alias for ``--aid``.
 
-    ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback.
+    ``--aid=no`` or ``--audio=no`` disables audio playback.
     (The latter variant does not work with the client API.)
 
     .. note::
@@ -102,7 +102,7 @@ Track Selection
 
     ``--sub`` is an alias for ``--sid``.
 
-    ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding.
+    ``--sid=no`` or ``--sub=no`` disables subtitle decoding.
     (The latter variant does not work with the client API.)
 
 ``--vid=<ID|auto|no>``
@@ -110,7 +110,7 @@ Track Selection
 
     ``--video`` is an alias for ``--vid``.
 
-    ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback.
+    ``--vid=no`` or ``--video=no`` disables video playback.
     (The latter variant does not work with the client API.)
 
     If video is disabled, mpv will try to download the audio only if media is
@@ -135,11 +135,13 @@ Track Selection
     Note that if ``--lavfi-complex`` is set before playback is started, the
     referenced tracks are always selected.
 
-``--subs-with-matching-audio=<yes|no>``
-    When autoselecting a subtitle track, select a full/non-forced one even if the selected
-    audio stream matches your preferred subtitle language (default: yes). If this option is
-    set to ``no``, a non-forced subtitle track that matches the audio language will never be
-    autoselected by mpv regardless of the value of ``--slang`` or ``--subs-fallback``.
+``--subs-with-matching-audio=<yes|forced|no>``
+    When autoselecting a subtitle track, select it even if the selected audio
+    stream matches you preferred subtitle language (default: yes). If this
+    option is set to ``no``, then no subtitle track that matches the audio
+    language will ever be autoselected by mpv regardless of ``--slang`` or
+    ``subs-fallback``. If set to ``forced``, then only forced subtitles
+    will be selected.
 
 ``--subs-match-os-language=<yes|no>``
     When autoselecting a subtitle track, select the track that matches the language of your OS
@@ -445,11 +447,10 @@ Playback Control
     will not enable looping again (the command will show ``(disabled)`` on the
     OSD message if both loop points are set, but ``ab-loop-count`` is 0).
 
-``--ordered-chapters``, ``--no-ordered-chapters``
-    Enabled by default.
-    Disable support for Matroska ordered chapters. mpv will not load or
-    search for video segments from other files, and will also ignore any
-    chapter order specified for the main file.
+``--ordered-chapters=<yes|no>``
+    Enable support for Matroska ordered chapters. mpv will load and
+    search for video segments from other files, and will also respect any
+    chapter order specified for the main file (default: yes).
 
 ``--ordered-chapters-files=<playlist-file>``
     Loads the given file as playlist, and tries to use the files contained in
@@ -853,11 +854,11 @@ Program Behavior
 
         May be dangerous if playing from untrusted media.
 
-``--ytdl``, ``--no-ytdl``
+``--ytdl=<yes|no>``
     Enable the youtube-dl hook-script. It will look at the input URL, and will
     play the video located on the website. This works with many streaming sites,
     not just the one that the script is named after. This requires a recent
-    version of youtube-dl to be installed on the system. (Enabled by default.)
+    version of youtube-dl to be installed on the system (default: yes).
 
     If the script can't do anything with an URL, it will do nothing.
 
@@ -1053,11 +1054,11 @@ Watch Later
     named "watch_later" underneath the local state directory
     (usually ``~/.local/state/mpv/``).
 
-``--no-resume-playback``
-    Do not restore playback position from the ``watch_later`` configuration
-    subdirectory (usually ``~/.config/mpv/watch_later/``).
+``--resume-playback=<yes|no>``
+    Restore playback position from the ``watch_later`` configuration
+    subdirectory, usually ``~/.config/mpv/watch_later/`` (default: yes).
 
-``--resume-playback-check-mtime``
+``--resume-playback-check-mtime=<yes|no>``
     Only restore the playback position from the ``watch_later`` configuration
     subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
     modification time is the same as at the time of saving. This may prevent
@@ -1129,7 +1130,7 @@ Video
 
 ``--untimed``
     Do not sleep when outputting video frames. Useful for benchmarks when used
-    with ``--no-audio.``
+    with ``--audio=no``.
 
 ``--framedrop=<mode>``
     Skip displaying some frames to maintain A/V sync on slow systems, or
@@ -1293,7 +1294,7 @@ Video
                    or ``--vo=libmpv`` (iOS 9.0 and up)
     :videotoolbox-copy: copies video back into system RAM (macOS 10.8 or iOS 9.0 and up)
     :vaapi:     requires ``--vo=gpu``, ``--vo=vaapi`` or ``--vo=dmabuf-wayland`` (Linux only)
-    :vaapi-copy: copies video back into system RAM (Linux with some GPUs only)
+    :vaapi-copy: copies video back into system RAM (Linux with some GPUs or Windows)
     :nvdec:     requires ``--vo=gpu`` (Any platform CUDA is available)
     :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
     :drm:       requires ``--vo=gpu`` (Linux only)
@@ -1313,8 +1314,6 @@ Video
     :mediacodec: requires ``--vo=gpu --gpu-context=android``
                  or ``--vo=mediacodec_embed`` (Android only)
     :mediacodec-copy: copies video back to system RAM (Android only)
-    :mmal:      requires ``--vo=gpu`` (Raspberry Pi only - default if available)
-    :mmal-copy: copies video back to system RAM (Raspberry Pi only)
     :cuda:      requires ``--vo=gpu`` (Any platform CUDA is available)
     :cuda-copy: copies video back to system RAM (Any platform CUDA is available)
     :crystalhd: copies video back to system RAM (Any platform supported by hardware)
@@ -1409,9 +1408,6 @@ Video
         affect this additionally. This can give incorrect results even with
         completely ordinary video sources.
 
-        ``rpi`` always uses the hardware overlay renderer, even with
-        ``--vo=gpu``.
-
         ``mediacodec`` is not safe. It forces RGB conversion (not with ``-copy``)
         and how well it handles non-standard colorspaces is not known.
         In the rare cases where 10-bit is supported the bit depth of the output
@@ -1497,10 +1493,13 @@ Video
     For the Vulkan GPU backend, decoding must always happen on the display
     device, and this option has no effect.
 
-``--vaapi-device=<device file>``
+``--vaapi-device=<device file|adapter name>``
     Choose the DRM device for ``vaapi-copy``. This should be the path to a
     DRM device file. (Default: ``/dev/dri/renderD128``)
 
+    On Windows this takes adapter name as an input. Will pick the default adapter
+    if unset. Alternatives are listed when the name "help" is given.
+
 ``--panscan=<0.0-1.0>``
     Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9
     video to make it fit a 4:3 display without black bands). The range
@@ -1557,7 +1556,7 @@ Video
     also still be scaled in one dimension if the source uses non-square pixels
     (e.g. anamorphic widescreen DVDs).
 
-    This option is disabled if the ``--no-keepaspect`` option is used.
+    This option is disabled if ``--keepaspect=no`` is used.
 
 ``--video-pan-x=<value>``, ``--video-pan-y=<value>``
     Moves the displayed video rectangle by the given value in the X or Y
@@ -1569,7 +1568,7 @@ Video
     ``--video-pan-x=-0.1`` would move the video 192 pixels to the left and
     ``--video-pan-y=-0.1`` would move the video 108 pixels up.
 
-    This option is disabled if the ``--no-keepaspect`` option is used.
+    This option is disabled if ``--keepaspect=no`` is used.
 
 ``--video-rotate=<0-359|no>``
     Rotate the video clockwise, in degrees. If ``no`` is given, the video is
@@ -1597,7 +1596,7 @@ Video
     ``--video-zoom=1`` is twice the size, ``--video-zoom=-2`` is one fourth of
     the size, and so on.
 
-    This option is disabled if the ``--no-keepaspect`` option is used.
+    This option is disabled if ``--keepaspect=no`` is used.
 
 ``--video-scale-x=<value>``, ``--video-scale-y=<value>``
     Multiply the video display size with the given value (default: 1.0). If a
@@ -1605,8 +1604,8 @@ Video
     video will be either cut off, or black bars are added.
 
     This value is multiplied with the value derived from ``--video-zoom`` and
-    the normal video aspect ratio. This option is disabled if the
-    ``--no-keepaspect`` option is used.
+    the normal video aspect ratio. This option is disabled if
+    ``--keepaspect=no`` is used.
 
 ``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>``
     Moves the video rectangle within the black borders, which are usually added
@@ -1618,7 +1617,7 @@ Video
 
     If video and screen aspect match perfectly, these options do nothing.
 
-    This option is disabled if the ``--no-keepaspect`` option is used.
+    This option is disabled if ``--keepaspect=no`` is used.
 
 ``--video-margin-ratio-left=<val>``, ``--video-margin-ratio-right=<val>``, ``--video-margin-ratio-top=<val>``, ``--video-margin-ratio-bottom=<val>``
     Set extra video margins on each border (default: 0). Each value is a ratio
@@ -1633,7 +1632,7 @@ Video
     The margins are applied after 90° video rotation, but before any other video
     transformations.
 
-    This option is disabled if the ``--no-keepaspect`` option is used.
+    This option is disabled if ``--keepaspect=no`` is used.
 
     Subtitles still may use the margins, depending on ``--sub-use-margins`` and
     similar options.
@@ -1644,8 +1643,8 @@ Video
     more generally useful. The behavior of these options may change to fit
     OSC requirements better, too.
 
-``--correct-pts``, ``--no-correct-pts``
-    ``--no-correct-pts`` switches mpv to a mode where video timing is
+``--correct-pts=<yes|no>``
+    ``--correct-pts=no`` switches mpv to a mode where video timing is
     determined using a fixed framerate value (either using the
     ``--container-fps-override`` option, or using file information). Sometimes,
     files with very broken timestamps can be played somewhat well in this mode.
@@ -1657,25 +1656,35 @@ Video
 
     .. note::
 
-        Works in ``--no-correct-pts`` mode only.
+        Works in ``--correct-pts=no`` mode only.
 
-``--deinterlace=<yes|no>``
+``--deinterlace=<yes|no|auto>``
     Enable or disable interlacing (default: no).
     Interlaced video shows ugly comb-like artifacts, which are visible on
-    fast movement. Enabling this typically inserts the yadif video filter in
+    fast movement. Enabling this typically inserts the bwdif video filter in
     order to deinterlace the video, or lets the video output apply deinterlacing
     if supported.
 
-    This behaves exactly like the ``deinterlace`` input property (usually
-    mapped to ``d``).
+    When using ``auto``, mpv will insert a deinterlacing filter if ffmpeg
+    detects that the video frame is interlaced. Be aware that there can be false
+    positives in certain cases, such as when files are encoded as interlaced
+    despite the video not actually being so. This is why ``auto`` is not the
+    default value.
+
+    Keep in mind that using this filter **will** conflict with any manually
+    inserted deinterlacing filters, and that this will make video look worse if
+    it's not actually interlaced.
 
-    Keep in mind that this **will** conflict with manually inserted
-    deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the
-    hardware deinterlace filters will conflict. Also since that version,
-    ``--deinterlace=auto`` was removed, which used to mean that the default
-    interlacing option of possibly inserted video filters was used.)
+``--deinterlace-field-parity=<tff|bff|auto>``
+    Specify the field parity/order when deinterlacing(default: auto)
+    Each frame of an interlaced video is divided into two fields, which are
+    then separately transmitted. Top field represents even lines while bottom
+    field represents odd lines. When deinterlacing the deinterlacer needs to
+    know the correct temporal order of the fields else the video will appear
+    jittery.
 
-    Note that this will make video look worse if it's not actually interlaced.
+    ``auto`` will automatically try to detect the field order of the video,
+    ``tff`` forces top field first while ``bff`` forces bottom field first.
 
 ``--frames=<number>``
     Play/convert only first ``<number>`` video frames, then quit.
@@ -1716,14 +1725,21 @@ Video
 
     By default, this is set to ``h264,vc1,hevc,vp8,vp9,av1``. Note that
     the hardware acceleration special codecs like ``h264_vdpau`` are not
-    relevant anymore, and in fact have been removed from Libav in this form.
+    relevant anymore, and in fact have been removed from FFmpeg in this form.
 
     This is usually only needed with broken GPUs, where a codec is reported
     as supported, but decoding causes more problems than it solves.
 
+    .. note::
+
+        On some broken drivers (e.g. NVIDIA on Linux), probing for codecs which
+        the GPU does not support can unnecessarily slow down video playback
+        initialization. To alleviate this, explicitly specify a list which
+        only includes the codecs supported on the setup.
+
     .. admonition:: Example
 
-        ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video``
+        ``mpv --hwdec=vdpau --hwdec-codecs=h264,mpeg2video``
             Enable vdpau decoding for h264 and mpeg2 only.
 
 ``--vd-lavc-check-hw-profile=<yes|no>``
@@ -1958,7 +1974,7 @@ Audio
     In earlier mpv versions you could use ``--ad`` to force the spdif wrapper.
     This does not work anymore.
 
-    .. admonition:: Warning
+    .. warning::
 
         There is not much reason to use this. HDMI supports uncompressed
         multichannel PCM, and mpv supports lossless DTS-HD decoding via
@@ -1979,13 +1995,13 @@ Audio
     .. admonition:: Examples
 
         ``--ad=mp3float``
-            Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3
+            Prefer the FFmpeg ``mp3float`` decoder over all other MP3
             decoders.
 
         ``--ad=help``
             List all available decoders.
 
-    .. admonition:: Warning
+    .. warning::
 
         Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with
         this option is not possible. Use ``--audio-spdif`` instead.
@@ -1995,7 +2011,19 @@ Audio
     amplification. Negative values can be passed for compatibility, but are
     treated as 0.
 
-    Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
+    Since mpv 0.18.1, this always controls the internal mixer (aka software
+    volume).
+
+``--volume-max=<100.0-1000.0>``
+    Set the maximum amplification level in percent (default: 130). A value of
+    130 will allow you to adjust the volume up to about double the normal level.
+
+``--volume-gain=<db>``
+    Set the volume gain in dB. This is applied on top of other volume and gain
+    settings.
+
+``--volume-gain-max=<0.0-150.0>``, ``--volume-gain-min=<-150.0-0.0>``
+    Set the volume gain range in dB (default: -96 dB min, 12 dB max).
 
 ``--replaygain=<no|track|album>``
     Adjust volume gain according to replaygain values stored in the file
@@ -2008,8 +2036,8 @@ Audio
     (default: 0).
 
 ``--replaygain-clip=<yes|no>``
-    Prevent clipping caused by replaygain by automatically lowering the
-    gain (default). Use ``--replaygain-clip=no`` to disable this.
+    Allow the volume gain to clip (default: no). If this option is not
+    enabled, mpv automatically will prevent clipping by lowering the gain.
 
 ``--replaygain-fallback=<db>``
     Gain in dB to apply if the file has no replay gain tags. This option
@@ -2027,18 +2055,6 @@ Audio
 
     See also: ``--volume``.
 
-``--softvol=<no|yes|auto>``
-    Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether
-    to use the volume controls of the audio output driver or the internal mpv
-    volume filter.
-
-    The current behavior is that softvol is always enabled, i.e. as if this
-    option is set to ``yes``. The other behaviors are not available anymore,
-    although ``auto`` almost matches current behavior in most cases.
-
-    The ``no`` behavior is still partially available through the ``ao-volume``
-    and ``ao-mute`` properties. But there are no options to reset these.
-
 ``--audio-demuxer=<[+]name>``
     Use this audio demuxer type when using ``--audio-file``. Use a '+' before
     the name to force it; this will skip some checks. Give the demuxer name as
@@ -2074,10 +2090,10 @@ Audio
 
     This is a key/value list option. See `List Options`_ for details.
 
-``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd``
+``--ad-spdif-dtshd=<yes|no>``, ``--dtshd=<yes|no>``
     If DTS is passed through, use DTS-HD.
 
-    .. admonition:: Warning
+    .. warning::
 
         This and enabling passthrough via ``--ad`` are deprecated in favor of
         using ``--audio-spdif=dts-hd``.
@@ -2135,7 +2151,7 @@ Audio
     work-around for this on some AOs is to use ``--audio-exclusive=yes`` to
     circumvent the system mixer entirely.
 
-    .. admonition:: Warning
+    .. warning::
 
         Using ``auto`` can cause issues when using audio over HDMI. The OS will
         typically report all channel layouts that _can_ go over HDMI, even if
@@ -2179,8 +2195,8 @@ Audio
 ``--audio-samplerate=<Hz>``
     Select the output sample rate to be used (of course sound cards have
     limits on this). If the sample frequency selected is different from that
-    of the current media, the lavrresample audio filter will be inserted into
-    the audio filter layer to compensate for the difference.
+    of the current media, the internal swresample audio filter will be inserted
+    into the audio filter layer to compensate for the difference.
 
 ``--gapless-audio=<no|yes|weak>``
     Try to play consecutive audio files with no silence or disruption at the
@@ -2217,7 +2233,7 @@ Audio
         then the buffered audio may run out before playback of the new file
         can start.
 
-``--initial-audio-sync``, ``--no-initial-audio-sync``
+``--initial-audio-sync=<yes|no>``
     When starting a video file or after events such as seeking, mpv will by
     default modify the audio stream to make it start from the same timestamp
     as video, by either inserting silence at the start or cutting away the
@@ -2226,11 +2242,7 @@ Audio
     their start timestamps differ, and then video timing is gradually adjusted
     if necessary to reach correct synchronization later.
 
-``--volume-max=<100.0-1000.0>``
-    Set the maximum amplification level in percent (default: 130). A value of
-    130 will allow you to adjust the volume up to about double the normal level.
-
-``--audio-file-auto=<no|exact|fuzzy|all>``, ``--no-audio-file-auto``
+``--audio-file-auto=<no|exact|fuzzy|all>``
     Load additional audio files matching the video filename. The parameter
     specifies how external audio files are matched.
 
@@ -2260,7 +2272,7 @@ Audio
     a larger buffer if it pleases. If the device creates a smaller buffer,
     additional audio is buffered in an additional software buffer.
 
-    Making this larger will make soft-volume and other filters react slower,
+    Making this larger may make soft-volume and other filters react slower,
     introduce additional issues on playback speed change, and block the
     player on audio format changes. A smaller buffer might lead to audio
     dropouts.
@@ -2281,7 +2293,7 @@ Audio
 
     Not all AOs support this.
 
-    .. admonition:: Warning
+    .. warning::
 
         This modifies certain subtle player behavior, like A/V-sync and underrun
         handling. Enabling this option is strongly discouraged.
@@ -2308,8 +2320,18 @@ Subtitles
     Force subtitle demuxer type for ``--sub-file``. Give the demuxer name as
     printed by ``--sub-demuxer=help``.
 
+``--sub-lavc-o=<key>=<value>[,<key>=<value>[,...]]``
+    Pass AVOptions to libavcodec decoder. Note, a patch to make the o=
+    unneeded and pass all unknown options through the AVOption system is
+    welcome. A full list of AVOptions can be found in the FFmpeg manual.
+
+    This is a key/value list option. See `List Options`_ for details.
+
 ``--sub-delay=<sec>``
-    Delays subtitles by ``<sec>`` seconds. Can be negative.
+    Delays primary subtitles by ``<sec>`` seconds. Can be negative.
+
+``--secondary-sub-delay=<sec>``
+    Delays secondary subtitles by ``<sec>`` seconds. Can be negative.
 
 ``--sub-files=<file-list>``, ``--sub-file=<filename>``
     Add a subtitle file to the list of external subtitles.
@@ -2332,8 +2354,8 @@ Subtitles
 ``--secondary-sid=<ID|auto|no>``
     Select a secondary subtitle stream. This is similar to ``--sid``. If a
     secondary subtitle is selected, it will be rendered as toptitle (i.e. on
-    the top of the screen) alongside the normal subtitle, and provides a way
-    to render two subtitles at once.
+    the top of the screen) alongside the normal subtitle by default, and
+    provides a way to render two subtitles at once.
 
     There are some caveats associated with this feature. For example, bitmap
     subtitles will always be rendered in their usual position, so selecting a
@@ -2343,14 +2365,14 @@ Subtitles
     .. note::
 
         Styling and interpretation of any formatting tags is disabled for the
-        secondary subtitle. Internally, the same mechanism as ``--no-sub-ass``
+        secondary subtitle. Internally, the same mechanism as ``--sub-ass=no``
         is used to strip the styling.
 
     .. note::
 
         If the main subtitle stream contains formatting tags which display the
         subtitle at the top of the screen, it will overlap with the secondary
-        subtitle. To prevent this, you could use ``--no-sub-ass`` to disable
+        subtitle. To prevent this, you could use ``--sub-ass=no`` to disable
         styling in the main subtitle stream.
 
 ``--sub-scale=<0-100>``
@@ -2400,7 +2422,7 @@ Subtitles
     some margin between the bottom and the subtitle. Values above 100 move the
     subtitle further down.
 
-    .. admonition:: Warning
+    .. warning::
 
         Text subtitles (as opposed to image subtitles) may be cut off if the
         value of the option is above 100. This is a libass restriction.
@@ -2410,6 +2432,10 @@ Subtitles
 
         Using ``--sub-margin-y`` can achieve this in a better way.
 
+``--secondary-sub-pos=<0-150>``
+    Specify the position of secondary subtitles on the screen. This is similar
+    to ``--sub-pos`` but for secondary subtitles.
+
 ``--sub-speed=<0.1-10.0>``
     Multiply the subtitle event timestamps with the given value. Can be used
     to fix the playback speed for frame-based subtitle formats. Affects text
@@ -2442,7 +2468,7 @@ Subtitles
     :normal:     FreeType autohinter, normal mode
     :native:     font native hinter
 
-    .. admonition:: Warning
+    .. warning::
 
         Enabling hinting can lead to mispositioned text (in situations it's
         supposed to match up video background), or reduce the smoothness
@@ -2489,6 +2515,12 @@ Subtitles
     This also controls some bitmap subtitle overrides, as well as HTML tags in
     formats like SRT, despite the name of the option.
 
+``--secondary-sub-ass-override=<yes|no|force|scale|strip>``
+    Control whether user secondary substyle overrides should be applied. This
+    works exactly like ``--sub-ass-override``.
+
+    Default: strip.
+
 ``--sub-ass-force-margins``
     Enables placing toptitles and subtitles in black borders when they are
     available, if the subtitles are in the ASS format.
@@ -2585,8 +2617,8 @@ Subtitles
     canvas size. Can be useful to test broken subtitles, which often happen
     when the video was trancoded, while attempting to keep the old subtitles.
 
-``--sub-ass``, ``--no-sub-ass``
-    Render ASS subtitles natively (enabled by default).
+``--sub-ass=<yes|no>``
+    Render ASS subtitles natively (default: yes).
 
     .. note::
 
@@ -2595,17 +2627,17 @@ Subtitles
         using ``--sub-ass-override=style`` should give better results
         without breaking subtitles too much.
 
-    If ``--no-sub-ass`` is specified, all tags and style declarations are
+    If ``--sub-ass=no`` is specified, all tags and style declarations are
     stripped and ignored on display. The subtitle renderer uses the font style
     as specified by the ``--sub-`` options instead.
 
     .. note::
 
-        Using ``--no-sub-ass`` may lead to incorrect or completely broken
+        Using ``--sub-ass=no`` may lead to incorrect or completely broken
         rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly
         override the styling of ASS subtitles, but should be avoided in general.
 
-``--sub-auto=<no|exact|fuzzy|all>``, ``--no-sub-auto``
+``--sub-auto=<no|exact|fuzzy|all>``
     Load additional subtitle files matching the video filename. The parameter
     specifies how external subtitle files are matched. ``exact`` is enabled by
     default.
@@ -2721,11 +2753,11 @@ Subtitles
 
     This is a path list option. See `List Options`_ for details.
 
-``--sub-visibility``, ``--no-sub-visibility``
+``--sub-visibility=<yes|no>``
     Can be used to disable display of subtitles, but still select and decode
     them.
 
-``--secondary-sub-visibility``, ``--no-secondary-sub-visibility``
+``--secondary-sub-visibility=<yes|no>``
     Can be used to disable display of secondary subtitles, but still select and
     decode them.
 
@@ -2735,12 +2767,26 @@ Subtitles
     Matroska-style ASS subtitle packets. It should be unique, and libass
     uses it for fast elimination of duplicates. This option disables caching
     of subtitles across seeks, so after a seek libass can't eliminate subtitle
-    packets with the same ReadOrder as earlier packets.
+    packets with the same ReadOrder as earlier packets. Note that enabling this
+    option can result in broken subtitle behavior if you are not actually
+    playing one of the aforementioned broken mkv files.
+
+``--teletext-page=<-1-999>``
+    Select a teletext page number to decode.
 
-``--teletext-page=<1-999>``
     This works for ``dvb_teletext`` subtitle streams, and if FFmpeg has been
     compiled with support for it.
 
+    Values ``1-999`` are for individual pages. Special value ``0`` (default)
+    matches all subtitle pages. Special value ``-1`` matches all pages.
+
+    Note that page ``100`` is the default start page of actual teletext. It is
+    also the former default value of this option.
+
+    See the ``libzvbi-teletext`` section in FFmpeg documentation for details.
+
+    Default: 0
+
 ``--sub-past-video-end``
     After the last frame of video, if this option is enabled, subtitles will
     continue to update based on audio timestamps. Otherwise, the subtitles
@@ -2760,8 +2806,8 @@ Subtitles
     .. note::
 
         The ``--sub-font`` option (and many other style related ``--sub-``
-        options) are ignored when ASS-subtitles are rendered, unless the
-        ``--no-sub-ass`` option is specified.
+        options) are ignored when ASS-subtitles are rendered, unless
+        ``--sub-ass=no`` is specified.
 
         This used to support fontconfig patterns. Starting with libass 0.13.0,
         this stopped working.
@@ -2779,7 +2825,8 @@ Subtitles
     ``--sub-shadow-offset`` to change its size relative to the text.
 
 ``--sub-blur=<0..20.0>``
-    Gaussian blur factor. 0 means no blur applied (default).
+    Gaussian blur factor applied to the sub font border.
+    0 means no blur applied (default).
 
 ``--sub-bold=<yes|no>``
     Format text on bold.
@@ -2846,7 +2893,7 @@ Subtitles
     Control to which corner of the screen text subtitles should be
     aligned to (default: ``center``).
 
-    Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise,
+    Never applied to ASS subtitles, except in ``--sub-ass=no`` mode. Likewise,
     this does not apply to image subtitles.
 
 ``--sub-align-y=<top|center|bottom>``
@@ -2892,8 +2939,12 @@ Subtitles
     This is intended for English, but may in part work for other languages too.
     The intention is that it can be always enabled so may not remove
     all parts added.
-    It removes speaker labels (like MAN:), upper case text in parentheses and
-    any text in brackets.
+
+    It removes speaker labels (like MAN:) and any text enclosed within symbols like
+    parentheses or brackets as specified by the ``--sub-filter-sdh-enclosures`` option.
+    Note that parenthesis (full width parenthesis and the normal variant) are a special
+    case and only upper case text is removed. For more filtering, you can use the
+    ``--sub-filter-sdh-harder`` option.
 
     Default: ``no``.
 
@@ -2904,6 +2955,15 @@ Subtitles
 
     Default: ``no``.
 
+``--sub-filter-sdh-enclosures=<string>``
+    Specify a string of characters that ``--sub-filter-sdh`` will use to potentially
+    remove text. Text that is enclosed within characters specified by this string will
+    be removed. Note that bracket characters with known pairs (such as ``(`` or ``[``)
+    will be mapped internally to their matching right hand character, so you only need
+    to specify left hand characters.
+
+    Default: ``([（``.
+
 ``--sub-filter-regex-...=...``
     Set a list of regular expressions to match on text subtitles, and remove any
     lines that match (default: empty). This is a string list option. See
@@ -3116,17 +3176,17 @@ Window
     This option does not affect the framerate used for ``mf://`` or
     ``--merge-files``. For that, use ``--mf-fps`` instead.
 
-    Setting ``--image-display-duration`` hides the OSC and does not track
-    playback time on the command-line output, and also does not duplicate
-    the image frame when encoding. To force the player into "dumb mode"
-    and actually count out seconds, or to duplicate the image when
-    encoding, you need to use ``--demuxer=lavf --demuxer-lavf-o=loop=1``,
-    and use ``--length`` or ``--frames`` to stop after a particular time.
+    When viewing images, the playback time is not tracked on the command line
+    output, and the image frame is not duplicated when encoding. To force the
+    player into "dumb mode" and actually count out seconds, or to duplicate the
+    image when encoding, you need to use ``--demuxer=lavf
+    --demuxer-lavf-o=loop=1``, and use ``--length`` or ``--frames`` to stop
+    after a particular time.
 
 ``--force-window=<yes|no|immediate>``
     Create a video output window even if there is no video. This can be useful
     when pretending that mpv is a GUI application. Currently, the window
-    always has the size 640x480, and is subject to ``--geometry``,
+    always has the size 960x540, and is subject to ``--geometry``,
     ``--autofit``, and similar options.
 
     .. warning::
@@ -3139,7 +3199,7 @@ Window
         mode can be used to create the window always on program start, but this
         may cause other issues.
 
-``--taskbar-progress``, ``--no-taskbar-progress``
+``--taskbar-progress=<yes|no>``
     (Windows only)
     Enable/disable playback progress rendering in taskbar (Windows 7 and above).
 
@@ -3148,14 +3208,14 @@ Window
 ``--snap-window``
     (Windows only) Snap the player window to screen edges.
 
-``--drag-and-drop=<no|auto|replace|append>``
-    (X11, Wayland and Windows only)
-    Controls the default behavior of drag and drop on platforms that support this.
-    ``auto`` will obey what the underlying os/platform gives mpv. Typically, holding
-    shift during the drag and drop will append the item to the playlist. Otherwise,
-    it will completely replace it. ``replace`` and ``append`` always force replacing
-    and appending to the playlist respectively. ``no`` disables all drag and drop
-    behavior.
+``--drag-and-drop=<no|auto|replace|append|insert-next>``
+    Controls the default behavior of drag and drop on platforms that support
+    this. ``auto`` will obey what the underlying os/platform gives mpv.
+    Typically, holding shift during the drag and drop will append the item to
+    the playlist. Otherwise, it will completely replace it. ``replace``,
+    ``append``, and ``insert-next`` always force replacing, appending to, and
+    inserting next into the playlist respectively. ``no`` disables all drag and
+    drop behavior.
 
 ``--ontop``
     Makes the player window stay on top of other windows.
@@ -3173,10 +3233,13 @@ Window
     :desktop: On top of the Desktop behind windows and Desktop icons.
     :level:   A level as integer.
 
-``--focus-on-open``, ``--no-focus-on-open``
+``--focus-on=<never|open|all>``,
     (macOS only)
-    Focus the video window on creation and makes it the front most window. This
-    is on by default.
+    Focus the video window and make it the front most window on specific events (default: open).
+
+    :never: Never focus the window on open or new file load events.
+    :open:  Focus the window on creation, eg when a vo is initialised.
+    :all:   Focus the window on open and new file load event.
 
 ``--window-corners=<default|donotround|round|roundsmall>``
     (Windows only)
@@ -3187,14 +3250,14 @@ Window
     :round: Round the corners if appropriate
     :roundsmall: Round the corners if appropriate, with a small radius
 
-``--border``, ``--no-border``
+``--border=<yes|no>``
     Play video with window border and decorations. Since this is on by
     default, use ``--no-border`` to disable the standard window decorations.
 
-``--title-bar``, ``--no-title-bar``
-    (Windows only)
+``--title-bar=<yes|no>``
+    (Windows and X11 only)
     Play video with the window title bar. Since this is on by default,
-    use --no-title-bar to hide the title bar. The --no-border option takes
+    use ``--title-bar=no`` to hide the title bar. The ``--border`` option takes
     precedence.
 
 ``--on-all-workspaces``
@@ -3234,6 +3297,11 @@ Window
 
         This option does not work properly with all window managers.
 
+    .. admonition:: Note (Wayland)
+
+        Wayland does not allow a client to position itself so this option will
+        only affect the window size.
+
     .. admonition:: Examples
 
         ``50:40``
@@ -3248,7 +3316,7 @@ Window
         ``50%x50%``
             Forces the window width and height to half the screen width and
             height. Will show black borders to compensate for the video aspect
-            ratio (with most VOs and without ``--no-keepaspect``).
+            ratio (with most VOs and with ``--keepaspect=yes``).
         ``50%+10+10/2``
             Sets the window to half the screen widths, and positions it 10
             pixels below/left of the top left corner of the screen, on the
@@ -3296,8 +3364,8 @@ Window
             of the screen width, or higher than 60% of the screen height.
 
 ``--autofit-larger=<[W[xH]]>``
-    This option behaves exactly like ``--autofit``, except the window size is
-    only changed if the window would be larger than the specified size.
+    This option behaves exactly like ``--autofit``, except that it sets the
+    maximum size of the window.
 
     .. admonition:: Example
 
@@ -3372,20 +3440,19 @@ Window
     be the default behavior. Currently only affects X11 and SDL VOs.
 
 ``--auto-window-resize=<yes|no>``
-    (Wayland, Win32, and X11)
     By default, mpv will automatically resize itself if the video's size changes
     (i.e. advancing forward in a playlist). Setting this to ``no`` disables this
     behavior so the window size never changes automatically. This option does
     not have any impact on the ``--autofit`` or ``--geometry`` options.
 
-``--no-keepaspect``, ``--keepaspect``
-    ``--no-keepaspect`` will always stretch the video to window size, and will
+``--keepaspect=<yes|no>``
+    ``--keepaspect=no`` will always stretch the video to window size, and will
     disable the window manager hints that force the window aspect ratio.
     (Ignored in fullscreen mode.)
 
-``--no-keepaspect-window``, ``--keepaspect-window``
-    ``--keepaspect-window`` (the default) will lock the window size to the
-    video aspect. ``--no-keepaspect-window`` disables this behavior, and will
+``--keepaspect-window=<yes|no>``
+    ``--keepaspect-window=yes`` (the default) will lock the window size to the
+    video aspect. ``--keepaspect-window=no`` disables this behavior, and will
     instead add black bars if window aspect and video aspect mismatch. Whether
     this actually works depends on the VO backend.
     (Ignored in fullscreen mode.)
@@ -3402,13 +3469,12 @@ Window
         - ``--monitoraspect=4:3``  or ``--monitoraspect=1.3333``
         - ``--monitoraspect=16:9`` or ``--monitoraspect=1.7777``
 
-``--hidpi-window-scale``, ``--no-hidpi-window-scale``
-    (macOS, Windows, X11, and Wayland only)
-    Scale the window size according to the backing scale factor (default: yes).
-    On regular HiDPI resolutions the window opens with double the size but appears
-    as having the same size as on non-HiDPI resolutions.
+``--hidpi-window-scale=<yes|no>``
+    Scale the window size according to the backing DPI scale factor from the OS
+    (default: no). For example, if the OS DPI scaling is set to 200%, mpv's window
+    size will be multiplied by 2.
 
-``--native-fs``, ``--no-native-fs``
+``--native-fs=<yes|no>``
     (macOS only)
     Uses the native fullscreen mechanism of the OS (default: yes).
 
@@ -3423,10 +3489,12 @@ Window
     the screensaver will re-enable when playback is not active. ``always`` will
     always disable the screensaver. Note that stopping the screensaver is only
     possible if a video output is available (i.e. there is an open mpv window).
+    This is not supported on all video outputs, platforms, or desktop environments.
 
-    This is not supported on all video outputs or platforms. Sometimes it is
-    implemented, but does not work (especially with Linux "desktops"). Read the
-    `Disabling Screensaver`_ section very carefully.
+    Before mpv 0.33.0, the X11 backend ran ``xdg-screensaver reset`` in 10 second
+    intervals when not paused in order to support screensaver inhibition in some
+    environments. This functionality was removed in 0.33.0, but it is possible to
+    call the ``xdg-screensaver`` command line program from a user script instead.
 
 ``--wid=<ID>``
     This tells mpv to attach to an existing window. If a VO is selected that
@@ -3455,11 +3523,11 @@ Window
     ``--hwdec=mediacodec`` for direct rendering using MediaCodec, or with
     ``--vo=gpu --gpu-context=android`` (with or without ``--hwdec=mediacodec``).
 
-``--no-window-dragging``
-    Don't move the window when clicking on it and moving the mouse pointer.
+``--window-dragging=<yes|no>``
+    Move the window when clicking on it and moving the mouse pointer (default: yes).
 
 ``--x11-name=<string>``
-    Set the window class name for X11-based video output methods.
+    Set the window instance name for X11-based video output methods.
 
 ``--x11-netwm=<yes|no|auto>``
     (X11 only)
@@ -3511,7 +3579,7 @@ Window
     mechanism in case there is good/bad behavior with whatever your combination
     of hardware/drivers/etc. happens to be.
 
-``--x11-wid-title`` ``--no-x11-wid-title``
+``--x11-wid-title=<yes|no>``
     Whether or not to set the window title when mpv is embedded on X11 (default:
     ``no``).
 
@@ -4009,36 +4077,52 @@ Demuxer
 Input
 -----
 
-``--native-keyrepeat``
+``--native-keyrepeat=<yes|no>``
     Use system settings for keyrepeat delay and rate, instead of
-    ``--input-ar-delay`` and ``--input-ar-rate``. (Whether this applies
-    depends on the VO backend and how it handles keyboard input. Does not
-    apply to terminal input.)
+    ``--input-ar-delay`` and ``--input-ar-rate`` (default: no).
+    Whether this applies depends on the VO backend and how it handles
+    keyboard input. Does not apply to terminal input.
 
 ``--input-ar-delay``
-    Delay in milliseconds before we start to autorepeat a key (0 to disable).
+    Delay in milliseconds before we start to autorepeat a key (default: 200).
+    Set it to 0 to disable.
 
 ``--input-ar-rate``
-    Number of key presses to generate per second on autorepeat.
+    Number of key presses to generate per second on autorepeat (default: 40).
 
 ``--input-conf=<filename>``
     Specify input configuration file other than the default location in the mpv
     configuration directory (usually ``~/.config/mpv/input.conf``).
 
-``--no-input-default-bindings``
-    Disable default-level ("weak") key bindings. These are bindings which config
-    files like ``input.conf`` can override. It currently affects the builtin key
-    bindings, and keys which scripts bind using ``mp.add_key_binding`` (but not
-    ``mp.add_forced_key_binding`` because this overrides ``input.conf``).
+``--input-default-bindings=<yes|no>``
+    Enable default-level ("weak") key bindings (default: yes). These are bindings
+    which config files like ``input.conf`` can override. It currently affects the
+    builtin key bindings, and keys which scripts bind using ``mp.add_key_binding``
+    (but not ``mp.add_forced_key_binding`` because this overrides ``input.conf``).
 
-``--no-input-builtin-bindings``
-    Disable loading of built-in key bindings during start-up. This option is
-    applied only during (lib)mpv initialization, and if used then it will not
-    be not possible to enable them later. May be useful to libmpv clients.
+``--input-builtin-bindings=<yes|no>``
+    Enable loading of built-in key bindings during start-up (default: yes). This
+    option is applied only during (lib)mpv initialization, and if disabled then it
+    will not be not possible to enable them later. May be useful to libmpv clients.
 
 ``--input-cmdlist``
     Prints all commands that can be bound to keys.
 
+``--input-commands=<cmd1,cmd2,...>``
+    Define a list of commands for mpv to run. The syntax is the same as format
+    as ``input.conf`` but without the key binding argument at the beginning.
+    When this option is set at startup, the commands will run after audio and
+    video playback are about to begin if applicable (in idle mode with no file,
+    it will run immediately). When changing values at runtime, the commands will
+    also run as soon as possible.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        ``--input-commands="playlist-play-index 1,set ao-volume 40"``
+            sets the playlist index to 1 and the ao-volume to 40
+
 ``--input-doubleclick-time=<milliseconds>``
     Time in milliseconds to recognize two consecutive button presses as a
     double-click (default: 300).
@@ -4060,8 +4144,8 @@ Input
     work (key bindings that normally quit will be shown on OSD only, just
     like any other binding). See `INPUT.CONF`_.
 
-``--input-terminal``, ``--no-input-terminal``
-    ``--no-input-terminal`` prevents the player from reading key events from
+``--input-terminal=<yes|no>``
+    ``--input-terminal=no`` prevents the player from reading key events from
     standard input. Useful when reading data from standard input. This is
     automatically enabled when ``-`` is found on the command line. There are
     situations where you have to set it manually, e.g. if you open
@@ -4116,13 +4200,12 @@ Input
 ``--input-gamepad=<yes|no>``
     Enable/disable SDL2 Gamepad support. Disabled by default.
 
-``--input-cursor``, ``--no-input-cursor``
+``--input-cursor=<yes|no>``
     Permit mpv to receive pointer events reported by the video output
     driver. Necessary to use the OSC, or to select the buttons in DVD menus.
     Support depends on the VO in use.
 
-``--input-cursor-passthrough``, ``--no-input-cursor-passthrough``
-    (X11 and Wayland only)
+``--input-cursor-passthrough=<yes|no>``
     Tell the backend windowing system to allow pointer events to passthrough
     the mpv window. This allows windows under mpv to instead receive pointer
     events as if the mpv window was never there.
@@ -4138,8 +4221,22 @@ Input
     implemented. Whether media keys work when the mpv window is focused is
     implementation-defined.
 
-``--input-right-alt-gr``, ``--no-input-right-alt-gr``
-    (Cocoa and Windows only)
+``--input-preprocess-wheel=<yes|no>``
+    Preprocess ``WHEEL_*`` events so that while scrolling on the horizontal
+    or vertical direction, the events aren't generated for another direction
+    even when the two directions are scrolled together (default: yes).
+
+    This preprocessing can be beneficial for preventing accidentally seeking
+    while changing the volume by scrolling on a touchpad with the default
+    keybind. Due to the deadzone mechanism used, disabling the preprocessing
+    allows for diagonal scrolling (such as panning) and potentially reduces
+    input latency.
+
+    Note that disabling the preprocessing does not affect any filtering done
+    by the OS/driver before these events are delivered to mpv, if any.
+
+``--input-right-alt-gr=<yes|no>``
+    (macOS and Windows only)
     Use the right Alt key as Alt Gr to produce special characters. If disabled,
     count the right Alt as an Alt modifier key. Enabled by default.
 
@@ -4169,11 +4266,11 @@ Input
 OSD
 ---
 
-``--osc``, ``--no-osc``
+``--osc=<yes|no>``
     Whether to load the on-screen-controller (default: yes).
 
-``--no-osd-bar``, ``--osd-bar``
-    Disable display of the OSD bar.
+``--osd-bar=<yes|no>``
+    Enable display of the OSD bar (default: yes).
 
     You can configure this on a per-command basis in input.conf using ``osd-``
     prefixes, see ``Input Command Prefixes``. If you want to disable the OSD
@@ -4259,11 +4356,18 @@ OSD
 ``--osd-bar-h=<0.1-50>``
     Height of the OSD bar, in percentage of the screen height (default: 3.125).
 
+``--osd-bar-border-size=<size>``
+    Size of the border of the OSD bar in scaled pixels (see ``--sub-font-size``
+    for details).
+
+    Default: 0.5.
+
 ``--osd-back-color=<color>``
     See ``--sub-color``. Color used for OSD text background.
 
 ``--osd-blur=<0..20.0>``
-    Gaussian blur factor. 0 means no blur applied (default).
+    Gaussian blur factor applied to the OSD font border.
+    0 means no blur applied (default).
 
 ``--osd-bold=<yes|no>``
     Format text on bold.
@@ -4357,7 +4461,7 @@ OSD
     all OSD rendering, use ``--osd-level=0``.
 
     It does not affect subtitles or overlays created by scripts (in particular,
-    the OSC needs to be disabled with ``--no-osc``).
+    the OSC needs to be disabled with ``--osc=no``).
 
     This option is somewhat experimental and could be replaced by another
     mechanism in the future.
@@ -4547,15 +4651,14 @@ Screenshot
     Default: ``libaom-av1``
 
 ``--screenshot-avif-pixfmt=<format>``
-    Specify the pixel format to the libavcodec encoder.
-
-    Default: ``yuv420p``
+    Specify the pixel format for the libavcodec encoder. Defaults to empty,
+    which lets mpv pick one close to the source format.
 
 ``--screenshot-avif-opts=key1=value1,key2=value2,...``
     Specifies libavcodec options for selected encoder. For more information,
     consult the FFmpeg documentation.
 
-    Default: ``usage=allintra,crf=32,cpu-used=8,tune=ssim``
+    Default: ``usage=allintra,crf=0,cpu-used=8``
 
     Note: the default is only guaranteed to work with the libaom-av1 encoder.
     Above options may not be valid and or optimal for other encoders.
@@ -4564,8 +4667,8 @@ Screenshot
 
     .. admonition:: Example
 
-        "``--screenshot-avif-opts=crf=32,aq-mode=complexity``"
-            sets the crf to 32 and quantization (aq-mode) to complexity based.
+        "``--screenshot-avif-opts=crf=23,aq-mode=complexity``"
+            sets the crf to 23 and quantization (aq-mode) to complexity based.
 
 ``--screenshot-sw=<yes|no>``
     Whether to use software rendering for screenshots (default: no).
@@ -4696,8 +4799,6 @@ Audio Resampler
 This controls the default options of any resampling done by mpv (but not within
 libavfilter, within the system audio API resampler, or any other places).
 
-It also sets the defaults for the ``lavrresample`` audio filter.
-
 ``--audio-resample-filter-size=<length>``
     Length of the filter with respect to the lower sampling rate. (default:
     16)
@@ -4718,9 +4819,6 @@ It also sets the defaults for the ``lavrresample`` audio filter.
     (default: no). If this is disabled, downmix can cause clipping. If it's
     enabled, the output might be too quiet. It depends on the source audio.
 
-    Technically, this changes the ``normalize`` suboption of the
-    ``lavrresample`` audio filter, which performs the downmixing.
-
     If downmix happens outside of mpv for some reason, or in the decoder
     (decoder downmixing), or in the audio output (system mixer), this has no
     effect.
@@ -4736,7 +4834,7 @@ It also sets the defaults for the ``lavrresample`` audio filter.
 
 ``--audio-swresample-o=<string>``
     Set AVOptions on the SwrContext or AVAudioResampleContext. These should
-    be documented by FFmpeg or Libav.
+    be documented by FFmpeg.
 
     This is a key/value list option. See `List Options`_ for details.
 
@@ -4754,15 +4852,15 @@ Terminal
 ``--really-quiet``
     Display even less output and status messages than with ``--quiet``.
 
-``--no-terminal``, ``--terminal``
-    Disable any use of the terminal and stdin/stdout/stderr. This completely
-    silences any message output.
+``--terminal=<yes|no>``
+    ``--terminal=no`` disables any use of the terminal and stdin/stdout/stderr.
+    This completely silences any message output.
 
     Unlike ``--really-quiet``, this disables input and terminal initialization
     as well.
 
-``--no-msg-color``
-    Disable colorful console output on terminals.
+``--msg-color=<yes|no>``
+    Enable colorful console output on terminals (default: yes).
 
 ``--msg-level=<module1=level1,module2=level2,...>``
     Control verbosity directly for each module. The ``all`` module changes the
@@ -4821,7 +4919,7 @@ Terminal
 
     The ``auto`` mode also enables terminal OSD if ``--video-osd=no`` was set.
 
-``--term-osd-bar``, ``--no-term-osd-bar``
+``--term-osd-bar=<yes|no>``
     Enable printing a progress bar under the status line on the terminal.
     (Disabled by default.)
 
@@ -4840,10 +4938,6 @@ Terminal
 
     See `Property Expansion`_.
 
-``--term-remaining-playtime``, ``--no-term-remaining-playtime``
-    When printing out the time on the terminal, show the remaining time adjusted by
-    playback speed. Default: ``yes``
-
 ``--term-status-msg=<string>``
     Print out a custom string during playback instead of the standard status
     line. Expands properties. See `Property Expansion`_.
@@ -4884,9 +4978,6 @@ Cache
     of the cache in kilobytes. Use e.g. ``--cache --demuxer-max-bytes=123k``
     instead.
 
-``--no-cache``
-    Turn off input stream caching. See ``--cache``.
-
 ``--cache-secs=<seconds>``
     How many seconds of audio/video to prefetch if the cache is active. This
     overrides the ``--demuxer-readahead-secs`` option if and only if the cache
@@ -5055,7 +5146,7 @@ Network
 ``--user-agent=<string>``
     Use ``<string>`` as user agent for HTTP streaming.
 
-``--cookies``, ``--no-cookies``
+``--cookies=<yes|no>``
     Support cookies when making HTTP requests. Disabled by default.
 
 ``--cookies-file=<filename>``
@@ -5093,11 +5184,11 @@ Network
 
 ``--tls-ca-file=<filename>``
     Certificate authority database file for use with TLS. (Silently fails with
-    older FFmpeg or Libav versions.)
+    older FFmpeg versions.)
 
 ``--tls-verify``
     Verify peer certificates when using TLS (e.g. with ``https://...``).
-    (Silently fails with older FFmpeg or Libav versions.)
+    (Silently fails with older FFmpeg versions.)
 
 ``--tls-cert-file``
     A file containing a certificate to use in the handshake with the
@@ -5111,7 +5202,7 @@ Network
 
 ``--network-timeout=<seconds>``
     Specify the network timeout in seconds (default: 60 seconds). This affects
-    at least HTTP. The special value 0 uses the FFmpeg/Libav defaults. If a
+    at least HTTP. The special value 0 uses the FFmpeg defaults. If a
     protocol is used which does not support timeouts, this option is silently
     ignored.
 
@@ -5205,57 +5296,6 @@ DVB
     An example ``input.conf`` could contain:
     ``H cycle dvbin-channel-switch-offset up``, ``K cycle dvbin-channel-switch-offset down``
 
-ALSA audio output options
--------------------------
-
-
-``--alsa-device=<device>``
-    Deprecated, use ``--audio-device`` (requires ``alsa/`` prefix).
-
-``--alsa-resample=yes``
-    Enable ALSA resampling plugin. (This is disabled by default, because
-    some drivers report incorrect audio delay in some cases.)
-
-``--alsa-mixer-device=<device>``
-    Set the mixer device used with ``ao-volume`` (default: ``default``).
-
-``--alsa-mixer-name=<name>``
-    Set the name of the mixer element (default: ``Master``). This is for
-    example ``PCM`` or ``Master``.
-
-``--alsa-mixer-index=<number>``
-    Set the index of the mixer channel (default: 0). Consider the output of
-    "``amixer scontrols``", then the index is the number that follows the
-    name of the element.
-
-``--alsa-non-interleaved``
-    Allow output of non-interleaved formats (if the audio decoder uses
-    this format). Currently disabled by default, because some popular
-    ALSA plugins are utterly broken with non-interleaved formats.
-
-``--alsa-ignore-chmap``
-    Don't read or set the channel map of the ALSA device - only request the
-    required number of channels, and then pass the audio as-is to it. This
-    option most likely should not be used. It can be useful for debugging,
-    or for static setups with a specially engineered ALSA configuration (in
-    this case you should always force the same layout with ``--audio-channels``,
-    or it will work only for files which use the layout implicit to your
-    ALSA device).
-
-``--alsa-buffer-time=<microseconds>``
-    Set the requested buffer time in microseconds. A value of 0 skips requesting
-    anything from the ALSA API. This and the ``--alsa-periods`` option uses the
-    ALSA ``near`` functions to set the requested parameters. If doing so results
-    in an empty configuration set, setting these parameters is skipped.
-
-    Both options control the buffer size. A low buffer size can lead to higher
-    CPU usage and audio dropouts, while a high buffer size can lead to higher
-    latency in volume changes and other filtering.
-
-``--alsa-periods=<number>``
-    Number of periods requested from the ALSA API. See ``--alsa-buffer-time``
-    for further remarks.
-
 
 GPU renderer options
 -----------------------
@@ -5287,8 +5327,8 @@ them.
         (This filter is an alias for ``jinc``-windowed ``jinc``)
 
     ``ewa_lanczossharp``
-        A slightly sharpened version of ewa_lanczos. This is the default when
-        using the ``high-quality`` profile.
+        A slightly sharpened version of ``ewa_lanczos``. This is the default
+        when using the ``high-quality`` profile.
 
     ``ewa_lanczos4sharpest``
         Very sharp scaler, but also slightly slower than ``ewa_lanczossharp``.
@@ -5297,8 +5337,10 @@ them.
         built-in anti-ringing, so no extra action needs to be taken.
 
     ``mitchell``
-        Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with
-        ``--scale-param1`` and ``--scale-param2``.
+        Mitchell-Netravali. Piecewise cubic filter with a support of radius 2.0.
+        Provides a balanced compromise of all scaling artifacts. This filter has
+        both ``B`` and ``C`` set to ``1/3``. The ``B`` and ``C`` parameters can
+        be controlled with ``--scale-param1`` and ``--scale-param2``.
 
     ``hermite``
         Hermite spline. Similar to ``bicubic`` but with ``B`` set to ``0.0``.
@@ -5307,10 +5349,9 @@ them.
         default for ``--dscale``.
 
     ``catmull_rom``
-        Catmull-Rom. A Cubic filter in the same vein as ``mitchell``, where
-        the ``B`` and ``C`` parameters are ``0.0`` and ``0.5`` respectively.
-        This filter is sharper than ``mitchell``, but it results in more
-        ringing.
+        Catmull-Rom spline. Similar to ``mitchell``, but with ``B`` and ``C``
+        set to ``0.0`` and ``0.5`` respectively. This filter is sharper than
+        ``mitchell``, but prone to ringing.
 
     ``oversample``
         A version of nearest neighbour that (naively) oversamples pixels, so
@@ -5532,14 +5573,16 @@ them.
     no
         Disable any dithering done by mpv.
     auto
-        Automatic selection. If output bit depth cannot be detected, 8 bits per
-        component are assumed.
+        Automatic selection.
+        On ``--vo=gpu``: detected depth or 8 bpc otherwise
+        On ``--vo=gpu-next``: detected depth or 8 bpc (for SDR target)
     8
         Dither to 8 bit output.
 
-    Note that the depth of the connected video display device cannot be
-    detected. Often, LCD panels will do dithering on their own, which conflicts
-    with this option and leads to ugly output.
+    Note that the on-the-wire bit depth cannot be detected except when using
+    ``gpu-api=d3d11``. Explicitly setting the value to your display's bit depth
+    is recommended, as dithering performed by some LCD panels can be of low
+    quality.
 
 ``--dither-size-fruit=<2-8>``
     Set the size of the dither matrix (default: 6). The actual size of the
@@ -5729,6 +5772,11 @@ them.
         from Windows 10. Thus on older systems it will only automatically
         utilize the rgba8 output format.
 
+    .. note::
+
+        For ``--vo=gpu-next``, this is used as a best-effort hint and
+        libplacebo has the last say on which format is utilized.
+
 ``--d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>``
     Select a specific D3D11 output color space to utilize for D3D11 rendering.
     "auto" is the default, which will select the color space of the desktop
@@ -5774,7 +5822,7 @@ them.
 ``--wayland-disable-vsync=<yes|no>``
     Disable mpv's internal vsync for Wayland-based video output (default: no).
     This is mainly useful for benchmarking wayland VOs when combined with
-    ``video-sync=display-desync``, ``--no-audio``, and ``--untimed=yes``.
+    ``video-sync=display-desync``, ``--audio=no``, and ``--untimed=yes``.
 
 ``--wayland-edge-pixels-pointer=<value>``
     Defines the size of an edge border (default: 16) to initiate client side
@@ -5787,8 +5835,8 @@ them.
 
 ``--spirv-compiler=<compiler>``
     Controls which compiler is used to translate GLSL to SPIR-V. This is
-    (currently) only relevant for ``--gpu-api=vulkan`` and `--gpu-api=d3d11`.
-    The possible choices are currently only:
+    only relevant for ``--gpu-api=d3d11`` with ``--vo=gpu``.
+    The possible choices are currently:
 
     auto
         Use the first available compiler. (Default)
@@ -5798,7 +5846,7 @@ them.
 
     .. note::
 
-        This option is deprecated, since there is only one reasonable value.
+        This option is deprecated, since there is only one usable value.
         It may be removed in the future.
 
 ``--glsl-shader=<file>``, ``--glsl-shaders=<file-list>``
@@ -5811,7 +5859,7 @@ them.
     and overwrites the internal list with it. The latter is a path list option
     (see `List Options`_ for details).
 
-    .. admonition:: Warning
+    .. warning::
 
         The syntax is not stable yet and may change any time.
 
@@ -6192,21 +6240,21 @@ them.
     software renderer, and ``auto`` only falls back to the software renderer
     when the usual pixel format couldn't be created.
 
-    macOS only.
+    macOS and cocoa-cb only.
 
 ``--cocoa-cb-10bit-context=<yes|no>``
     Creates a 10bit capable pixel format for the context creation (default: yes).
     Instead of 8bit integer framebuffer a 16bit half-float framebuffer is
     requested.
 
-    macOS only.
+    macOS and cocoa-cb only.
 
 ``--macos-title-bar-appearance=<appearance>``
     Sets the appearance of the title bar (default: auto). Not all combinations
     of appearances and ``--macos-title-bar-material`` materials make sense or
     are unique. Appearances that are not supported by you current macOS version
     fall back to the default value.
-    macOS and cocoa-cb only
+    macOS only
 
     ``<appearance>`` can be one of the following:
 
@@ -6231,7 +6279,7 @@ them.
     ``--macos-title-bar-appearance`` appearances make sense or are unique.
     Materials that are not supported by you current macOS version fall back to
     the default value.
-    macOS and cocoa-cb only
+    macOS only
 
     ``<material>`` can be one of the following:
 
@@ -6280,7 +6328,7 @@ them.
     1000ms since it's possible that Apple or the user changes the system
     defaults. Anything higher than 1000ms though seems too long and shouldn't be
     set anyway.
-    (macOS and cocoa-cb only)
+    (macOS)
 
 
 ``--macos-app-activation-policy=<regular|accessory|prohibited>``
@@ -6310,6 +6358,7 @@ them.
     :precise:  Syncs to the time of the next vertical display refresh reported by the
                CVDisplayLink callback provided information
     :system:   No manual syncing, depend on the layer mechanic and the next drawable
+    :feedback: Same as precise but uses the presentation feedback core mechanism
 
 ``--android-surface-size=<WxH>``
     Set dimensions of the rendering surface used by the Android gpu context.
@@ -6328,8 +6377,6 @@ them.
 
     auto
         auto-select (default)
-    cocoa
-        Cocoa/macOS (deprecated, use --vo=libmpv instead)
     win
         Win32/WGL
     winvk
@@ -6355,7 +6402,7 @@ them.
     drm
         DRM/EGL
     displayvk
-        VK_KHR_display. This backend is roughly the Vukan equivalent of
+        VK_KHR_display. This backend is roughly the Vulkan equivalent of
         DRM/EGL, allowing for direct rendering via Vulkan without a display
         manager.
     x11egl
@@ -6816,8 +6863,11 @@ them.
     files contain uncompressed LUTs. Their size depends on the
     ``--icc-3dlut-size``, and can be very big.
 
-    NOTE: On ``--vo=gpu``, this is not cleaned automatically, so old, unused
-    cache files may stick around indefinitely.
+    On `--vo=gpu-next`, files that have not been accessed in the last 24 hours
+    may be cleared if the cache limit (1.5 GiB) is exceeded.
+
+    On ``--vo=gpu``, this is not cleaned automatically, so old, unused cache
+    files may stick around indefinitely.
 
 ``--icc-cache-dir``
     The directory where icc cache is stored. Cache is stored in the system's
@@ -6902,35 +6952,35 @@ them.
                  softsubbed ASS signs to match the video colors, but may cause
                  SRT subtitles or similar to look slightly off.
 
-``--alpha=<blend-tiles|blend|yes|no>``
-    Decides what to do if the input has an alpha component.
+``--background=<none|color|tiles>``
+    If the frame has an alpha component, decide what kind of background, if any,
+    to blend it with. This does nothing if there is no alpha component.
 
-    blend-tiles
+    color
+        Blend the frame against the background color (``--background-color``,
+        normally black).
+    tiles
         Blend the frame against a 16x16 gray/white tiles background (default).
-    blend
-        Blend the frame against the background color (``--background``, normally
-        black).
-    yes
-        Try to create a framebuffer with alpha component. This only makes sense
-        if the video contains alpha information (which is extremely rare) or if
-        you make the background color transparent. May not be supported on all
-        platforms. If alpha framebuffers are unavailable, it silently falls
-        back on a normal framebuffer. Note that if you set the ``--fbo-format``
-        option to a non-default value, a format with alpha must be specified,
-        or this won't work. Whether this really works depends on the windowing
-        system and desktop environment.
-    no
-        Ignore alpha component.
+    none
+        Do not blend the frame and leave the alpha as is.
+
+    Before mpv 0.38.0, this option used to accept a color value specifying the
+    background color. This is now done by the ``--background-color`` option.
+    Use that instead.
+
+``--background-color=<color>``
+    Color used to draw parts of the mpv window not covered by video. See the
+    ``--sub-color`` option for how colors are defined.
+
+``--border-background=<none|color|tiles>``
+    Same as ``--background`` but only applies to the black bar/border area of
+    the window. ``vo=gpu-next`` only. Defaults to ``color``.
 
 ``--opengl-rectangle-textures``
     Force use of rectangle textures (default: no). Normally this shouldn't have
     any advantages over normal textures. Note that hardware decoding overrides
     this flag. Could be removed any time.
 
-``--background=<color>``
-    Color used to draw parts of the mpv window not covered by video. See the
-    ``--sub-color`` option for how colors are defined.
-
 ``--gpu-tex-pad-x``, ``--gpu-tex-pad-y``
     Enlarge the video source textures by this many pixels. For debugging only
     (normally textures are sized exactly, but due to hardware decoding interop
@@ -6965,11 +7015,14 @@ them.
 ``--gpu-shader-cache``
     Store and load compiled GLSL shaders in the cache directory (Default:
     ``yes``). Normally, shader compilation is very fast, so this is not usually
-    needed. It mostly matters for anything based on D3D11 (including ANGLE), as
-    well as on some other proprietary drivers. Enabling this can improve startup
-    performance on these platforms.
+    needed. It mostly matters for anything involving GLSL to SPIR-V conversion,
+    that is: D3D11, ANGLE or Vulkan, as well as on some other proprietary
+    drivers. Enabling this can improve startup performance on these platforms.
+
+    On `--vo=gpu-next`, files that have not been accessed in the last 24 hours
+    may be cleared if the cache limit (128 MiB) is exceeded.
 
-    NOTE: On ``--vo=gpu``, is not cleaned automatically, so old, unused cache
+    On ``--vo=gpu``, this is not cleaned automatically, so old, unused cache
     files may stick around indefinitely.
 
 ``--gpu-shader-cache-dir``
@@ -7006,9 +7059,9 @@ Miscellaneous
     Specifying ``--autosync=0``, the default, will cause frame timing to be
     based entirely on audio delay measurements. Specifying ``--autosync=1``
     will do the same, but will subtly change the A/V correction algorithm. An
-    uneven video framerate in a video which plays fine with ``--no-audio`` can
+    uneven video framerate in a video which plays fine with ``--audio=no`` can
     often be helped by setting this to an integer value greater than 1. The
-    higher the value, the closer the timing will be to ``--no-audio``. Try
+    higher the value, the closer the timing will be to ``--audio=no``. Try
     ``--autosync=30`` to smooth out problems with sound drivers which do not
     implement a perfect audio delay measurement. With this value, if large A/V
     sync offsets occur, they will only take about 1 or 2 seconds to settle