Merging upstream version 0.38.0.

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

13 files changed, 888 insertions, 487 deletions

diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index 4e4e454..4ac1cc5 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -12,16 +12,59 @@ in the list.
 
 .. note::
 
-    See ``--ao=help`` for a list of compiled-in audio output drivers. The
-    driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems
-    where PulseAudio is used. On BSD systems, ``--ao=oss`` is preferred.
+    See ``--ao=help`` for a list of compiled-in audio output drivers sorted by
+    autoprobe order.
 
 Available audio output drivers are:
 
-``alsa`` (Linux only)
-    ALSA audio output driver
+``alsa``
+    ALSA audio output driver.
 
-    See `ALSA audio output options`_ for options specific to this AO.
+    The following global options are supported by this audio output:
+
+    ``--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.
 
     .. warning::
 
@@ -95,11 +138,21 @@ Available audio output drivers are:
         passthrough (even if the device reports it as supported). Use with
         extreme care.
 
-
 ``coreaudio_exclusive`` (macOS only)
     Native macOS audio output driver using direct device access and
     exclusive mode (bypasses the sound server).
 
+``avfoundation`` (macOS only)
+    Native macOS audio output driver using ``AVSampleBufferAudioRenderer``
+    in AVFoundation, which supports `spatial audio
+    <https://support.apple.com/en-us/HT211775>`_.
+
+    .. warning::
+
+        Turning on spatial audio may hang the playback
+        if mpv is not started out of the bundle,
+        though playback with spatial audio off always works.
+
 ``openal``
     OpenAL audio output driver.
 
@@ -131,15 +184,12 @@ Available audio output drivers are:
         changes. "native" lets the sound server determine buffers.
 
     ``--pulse-latency-hacks=<yes|no>``
-        Enable hacks to workaround PulseAudio timing bugs (default: no). If
+        Enable hacks to workaround PulseAudio timing bugs (default: yes). If
         enabled, mpv will do elaborate latency calculations on its own. If
         disabled, it will use PulseAudio automatically updated timing
         information. Disabling this might help with e.g. networked audio or
         some plugins, while enabling it might help in some unknown situations
-        (it used to be required to get good behavior on old PulseAudio versions).
-
-        If you have stuttering video when using pulse, try to enable this
-        option. (Or try to update PulseAudio.)
+        (it is currently enabled due to known bugs with PulseAudio 16.0).
 
     ``--pulse-allow-suspended=<yes|no>``
         Allow mpv to use PulseAudio even if the sink is suspended (default: no).
@@ -167,8 +217,8 @@ Available audio output drivers are:
         By default the channel volumes are used.
 
 ``sdl``
-    SDL 1.2+ audio output driver. Should work on any platform supported by SDL
-    1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
+    SDL 2.0+ audio output driver. Should work on any platform supported by SDL
+    2.0, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
     appropriately for your system.
 
     .. note:: This driver is for compatibility with extremely foreign
diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst
index 63de41c..3f5e0e1 100644
--- a/DOCS/man/changes.rst
+++ b/DOCS/man/changes.rst
@@ -10,8 +10,7 @@ There is no real changelog, but you can look at the following things:
 * The git log, which is the "real" changelog
 * The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
   documents changes to the command and user interface, such as options and
-  properties. (It usually documents breaking changes only, additions and
-  enhancements are often not listed.)
+  properties.
 * C API changes are listed in
   https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
 * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git
diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst
index 49502b3..b9f169f 100644
--- a/DOCS/man/console.rst
+++ b/DOCS/man/console.rst
@@ -86,7 +86,11 @@ Shift+INSERT
     Paste text (uses the primary selection on X11 and Wayland).
 
 TAB and Ctrl+i
-    Complete the command or property name at the cursor.
+    Complete the text at the cursor. The first press inserts the longest common
+    prefix of the completions, and subsequent presses cycle through them.
+
+Shift+TAB
+    Cycle through the completions backwards.
 
 Ctrl+l
     Clear all log messages from the console.
@@ -154,6 +158,11 @@ Configurable Options
 
     Set the font border size used for the REPL and the console.
 
+``case_sensitive``
+    Default: no on Windows, yes on other platforms.
+
+    Whether Tab completion is case sensitive. Only works with ASCII characters.
+
 ``history_dedup``
     Default: true
 
@@ -161,7 +170,8 @@ Configurable Options
     multiplied by "scale."
 
 ``font_hw_ratio``
-    Default: 2.0
+    Default: auto
 
     The ratio of font height to font width.
     Adjusts table width of completion suggestions.
+    Values in the range 1.8..2.5 make sense for common monospace fonts.
diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst
index 399eba2..26f3d6c 100644
--- a/DOCS/man/encode.rst
+++ b/DOCS/man/encode.rst
@@ -77,9 +77,8 @@ You can encode files from one format/codec to another using this facility.
     and all pts are passed through as-is. Never seek backwards or use multiple
     input files in this mode!
 
-``--no-ocopy-metadata``
-    Turns off copying of metadata from input files to output files when
-    encoding (which is enabled by default).
+``--ocopy-metadata=<yes|no>``
+    Copy metadata from input files to output files when encoding (default: yes).
 
 ``--oset-metadata=<metadata-tag[,metadata-tag,...]>``
     Specifies metadata to include in the output file.
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 8dbf58b..6d6b64c 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -49,8 +49,8 @@ input.conf syntax
 ``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*``
 
 Note that by default, the right Alt key can be used to create special
-characters, and thus does not register as a modifier. The option
-``--no-input-right-alt-gr`` changes this behavior.
+characters, and thus does not register as a modifier. This can be changed
+with ``--input-right-alt-gr`` option.
 
 Newlines always start a new binding. ``#`` starts a comment (outside of quoted
 string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used.
@@ -264,7 +264,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
 ``ignore``
     Use this to "block" keys that should be unbound, and do nothing. Useful for
     disabling default bindings, without disabling all bindings with
-    ``--no-input-default-bindings``.
+    ``--input-default-bindings=no``.
 
 ``seek <target> [<flags>]``
     Change the playback position. By default, seeks by a relative amount of
@@ -452,9 +452,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
     restarted if for example the new playlist entry is the same as the previous
     one.
 
-``loadfile <url> [<flags> [<options>]]``
+``loadfile <url> [<flags> [<index> [<options>]]]``
     Load the given file or URL and play it. Technically, this is just a playlist
-    manipulation command (which either replaces the playlist or appends an entry
+    manipulation command (which either replaces the playlist or adds an entry
     to it). Actual file loading happens independently. For example, a
     ``loadfile`` command that replaces the current file with a new one returns
     before the current file is stopped, and the new file even begins loading.
@@ -469,15 +469,34 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
         Append the file, and if nothing is currently playing, start playback.
         (Always starts with the added file, even if the playlist was not empty
         before running this command.)
-
-    The third argument is a list of options and values which should be set
+    <insert-next>
+        Insert the file into the playlist, directly after the current entry.
+    <insert-next-play>
+        Insert the file next, and if nothing is currently playing, start playback.
+        (Always starts with the added file, even if the playlist was not empty
+        before running this command.)
+    <insert-at>
+        Insert the file into the playlist, at the index given in the third
+        argument.
+    <insert-at-play>
+        Insert the file at the index given in the third argument, and if nothing
+        is currently playing, start playback. (Always starts with the added
+        file, even if the playlist was not empty before running this command.)
+
+    The third argument is an insertion index, used only by the ``insert-at`` and
+    ``insert-at-play`` actions. When used with those actions, the new item will
+    be inserted at the index position in the playlist, or appended to the end if
+    index is less than 0 or greater than the size of the playlist. This argument
+    will be ignored for all other actions.
+
+    The fourth argument is a list of options and values which should be set
     while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``.
     When using the client API, this can be a ``MPV_FORMAT_NODE_MAP`` (or a Lua
     table), however the values themselves must be strings currently. These
     options are set during playback, and restored to the previous value at end
     of playback (see `Per-File Options`_).
 
-``loadlist <url> [<flags>]``
+``loadlist <url> [<flags> [<index>]]``
     Load the given playlist file or URL (like ``--playlist``).
 
     Second argument:
@@ -490,6 +509,26 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
         Append the new playlist, and if nothing is currently playing, start
         playback. (Always starts with the new playlist, even if the internal
         playlist was not empty before running this command.)
+    <insert-next>
+        Insert the new playlist into the current internal playlist, directly
+        after the current entry.
+    <insert-next-play>
+        Insert the new playlist, and if nothing is currently playing, start
+        playback. (Always starts with the new playlist, even if the internal
+        playlist was not empty before running this command.)
+    <insert-at>
+        Insert the new playlist at the index given in the third argument.
+    <insert-at-play>
+        Insert the new playlist at the index given in the third argument, and if
+        nothing is currently playing, start playback. (Always starts with the
+        new playlist, even if the internal playlist was not empty before running
+        this command.)
+
+    The third argument is an insertion index, used only by the ``insert-at`` and
+    ``insert-at-play`` actions. When used with those actions, the new playlist
+    will be inserted at the index position in the internal playlist, or appended
+    to the end if index is less than 0 or greater than the size of the internal
+    playlist. This argument will be ignored for all other actions.
 
 ``playlist-clear``
     Clear the playlist, except the currently played file.
@@ -655,7 +694,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
               wasn't started in detached mode, even if ``playback_only`` is
               false.
 
-    .. admonition:: Warning
+    .. warning::
 
         Don't forget to set the ``playback_only`` field to false if you want
         the command to run while the player is in idle mode, or if you don't
@@ -827,11 +866,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
     <double>
         The mouse event represents double-click.
 
-``keypress <name>``
+``keypress <name> [<scale>]``
     Send a key event through mpv's input handler, triggering whatever
     behavior is configured to that key. ``name`` uses the ``input.conf``
-    naming scheme for keys and modifiers. Useful for the client API: key events
-    can be sent to libmpv to handle internally.
+    naming scheme for keys and modifiers. ``scale`` is used to scale numerical
+    change effected by the bound command (same mechanism as precise scrolling).
+    Useful for the client API: key events can be sent to libmpv to handle
+    internally.
 
 ``keydown <name>``
     Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is
@@ -886,6 +927,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
     <keep-selection>
         Do not change current track selections.
 
+``context-menu``
+    Show context menu on the video window. See `Context Menu`_ section for details.
+
 
 Input Commands that are Possibly Subject to Change
 --------------------------------------------------
@@ -1033,7 +1077,7 @@ Input Commands that are Possibly Subject to Change
     information about the key state. The special key name ``unmapped`` can be
     used to match any unmapped key.
 
-``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>``
+``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>``
     Add an OSD overlay sourced from raw data. This might be useful for scripts
     and applications controlling mpv, and which want to display things on top
     of the video window.
@@ -1091,6 +1135,11 @@ Input Commands that are Possibly Subject to Change
     (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but
     for simplicity, the player will access all ``stride * h`` bytes.)
 
+    ``dw`` and ``dh`` specify the (optional) display size of the overlay.
+    The overlay visible portion of the overlay (``w`` and ``h``) is scaled to
+    in display to ``dw`` and ``dh``.  If parameters are not present, the
+    values for ``w`` and ``h`` are used.
+
     .. note::
 
         Before mpv 0.18.1, you had to do manual "double buffering" when updating
@@ -1213,6 +1262,18 @@ Input Commands that are Possibly Subject to Change
         use the ``mp.create_osd_overlay()`` helper instead of invoking this
         command directly.
 
+``escape-ass <text>``
+    Modify ``text`` so that commands and functions that interpret ASS tags,
+    such as ``osd-overlay`` and ``mp.create_osd_overlay``, will display it
+    verbatim, and return it. This can only be used through the client API or
+    from a script using ``mp.command_native``.
+
+    .. admonition:: Example
+
+        ``mp.osd_message(mp.command_native({"escape-ass", "foo {bar}"}))``
+
+        This line of Lua prints "foo \\{bar}" on the OSD.
+
 ``script-message [<arg1> [<arg2> [...]]]``
     Send a message to all clients, and pass it the following list of arguments.
     What this message means, how many arguments it takes, and what the arguments
@@ -1329,6 +1390,16 @@ Input Commands that are Possibly Subject to Change
         relevant mode. Prints a warning if nothing could be done. See
         `Runtime profiles`_ for details.
 
+``load-config-file <filename>``
+    Load a configuration file, similar to the ``--include`` option. If the file
+    was already included, its previous options are not reset before it is
+    reparsed.
+
+``load-input-conf <filename>``
+    Load an input configuration file, similar to the ``--input-conf`` option. If
+    the file was already included, its previous bindings are not reset before it
+    is reparsed.
+
 ``load-script <filename>``
     Load a script, similar to the ``--script`` option. Whether this waits for
     the script to finish initialization or not changed multiple times, and the
@@ -1422,6 +1493,13 @@ Input Commands that are Possibly Subject to Change
     This command has an even more uncertain future than ``ab-loop-dump-cache``
     and might disappear without replacement if the author decides it's useless.
 
+``begin-vo-dragging``
+    Begin window dragging if supported by the current VO. This command should
+    only be called while a mouse button is being pressed, otherwise it will
+    be ignored. The exact effect of this command depends on the VO implementation
+    of window dragging. For example, on Windows only the left mouse button can
+    begin window dragging, while X11 and Wayland allow other mouse buttons.
+
 Undocumented commands: ``ao-reload`` (experimental/internal).
 
 List of events
@@ -2157,6 +2235,11 @@ Property list
 ``af-metadata/<filter-label>``
     Equivalent to ``vf-metadata/<filter-label>``, but for audio filters.
 
+``deinterlace-active``
+    Returns ``yes``/true if mpv's deinterlacing filter is active. Note that it
+    will not detect any manually inserted deinterlacing filters done via
+    ``--vf``.
+
 ``idle-active``
     Returns ``yes``/true if no file is loaded, but the player is staying around
     because of the ``--idle`` option.
@@ -2318,12 +2401,6 @@ Property list
     Similar to ``ao-volume``, but controls the mute state. May be unimplemented
     even if ``ao-volume`` works.
 
-``audio-codec``
-    Audio codec selected for decoding.
-
-``audio-codec-name``
-    Audio codec.
-
 ``audio-params``
     Audio format as output by the audio decoder.
     This has a number of sub-properties:
@@ -2407,12 +2484,6 @@ Property list
     multiple interop drivers for the same hardware decoder, depending on
     platform and VO.
 
-``video-format``
-    Video format as string.
-
-``video-codec``
-    Video codec selected for decoding.
-
 ``width``, ``height``
     Video size. This uses the size of the video as decoded, or if no video
     frame has been decoded yet, the (possibly incorrect) container indicated
@@ -2579,6 +2650,11 @@ Property list
 
     Has the same sub-properties as ``video-params``.
 
+``video-target-params``
+    Same as ``video-params``, but with the target properties that VO outputs to.
+
+    Has the same sub-properties as ``video-params``.
+
 ``video-frame-info``
     Approximate information of the current frame. Note that if any of these
     are used on OSD, the information might be off by a few frames due to OSD
@@ -2661,7 +2737,10 @@ Property list
     in the list will be the one that Windows considers associated with the
     window (as determined by the MonitorFromWindow API.) On macOS these are the
     Display Product Names as used in the System Information and only one display
-    name is returned since a window can only be on one screen.
+    name is returned since a window can only be on one screen. On Wayland, these
+    are the wl_output names if protocol version >= 4 is used
+    (LVDS-1, HDMI-A-1, X11-1, etc.), or the wl_output model reported by the
+    geometry event if protocol version < 4 is used.
 
 ``display-fps``
     The refresh rate of the current display. Currently, this is the lowest FPS
@@ -2728,6 +2807,19 @@ Property list
     Any of these properties may be unavailable or set to dummy values if the
     VO window is not created or visible.
 
+``term-size``
+    The current terminal size.
+
+    This has two sub-properties.
+
+    ``term-size/w``
+        width of the terminal in cells
+    ``term-size/h``
+        height of the terminal in cells
+
+    This property is not observable. Reacting to size changes requires
+    polling.
+
 ``window-id``
     Read-only - mpv's window id. May not always be available, i.e due to window
     not being opened yet or not being supported by the VO.
@@ -2953,6 +3045,13 @@ Property list
         The codec name used by this track, for example ``h264``. Unavailable
         in some rare cases.
 
+    ``track-list/N/codec-desc``
+        The codec descriptive name used by this track.
+
+    ``track-list/N/codec-profile``
+        The codec profile used by this track. Available only if the track has
+        been already decoded.
+
     ``track-list/N/external``
         ``yes``/true if the track is an external file, ``no``/false or
         unavailable otherwise. This is set for separate subtitle files.
@@ -3013,6 +3112,11 @@ Property list
     ``track-list/N/demux-par``
         Pixel aspect ratio.
 
+    ``track-list/N/format-name``
+        Short name for format from ffmpeg. If the track is audio, this will be
+        the name of the sample format. If the track is video, this will be the
+        name of the pixel format.
+
     ``track-list/N/audio-channels`` (deprecated)
         Deprecated alias for ``track-list/N/demux-channel-count``.
 
@@ -3048,6 +3152,8 @@ Property list
                 "external"          MPV_FORMAT_FLAG
                 "external-filename" MPV_FORMAT_STRING
                 "codec"             MPV_FORMAT_STRING
+                "codec-desc"        MPV_FORMAT_STRING
+                "codec-profile"     MPV_FORMAT_STRING
                 "ff-index"          MPV_FORMAT_INT64
                 "decoder-desc"      MPV_FORMAT_STRING
                 "demux-w"           MPV_FORMAT_INT64
@@ -3325,39 +3431,19 @@ Property list
 ``current-vo``
     Current video output driver (name as used with ``--vo``).
 
+``current-gpu-context``
+    Current GPU context of video output driver (name as used with ``--gpu-context``).
+    Valid for ``--vo=gpu`` and ``--vo=gpu-next``.
+
 ``current-ao``
     Current audio output driver (name as used with ``--ao``).
 
-``shared-script-properties`` (RW)
-    This is a key/value map of arbitrary strings shared between scripts for
-    general use. The player itself does not use any data in it (although some
-    builtin scripts may). The property is not preserved across player restarts.
-
-    This is very primitive, inefficient, and annoying to use. It's a makeshift
-    solution which could go away any time (for example, when a better solution
-    becomes available). This is also why this property has an annoying name. You
-    should avoid using it, unless you absolutely have to.
-
-    Lua scripting has helpers starting with ``utils.shared_script_property_``.
-    They are undocumented because you should not use this property. If you still
-    think you must, you should use the helpers instead of the property directly.
-
-    You are supposed to use the ``change-list`` command to modify the contents.
-    Reading, modifying, and writing the property manually could data loss if two
-    scripts update different keys at the same time due to lack of
-    synchronization. The Lua helpers take care of this.
-
-    (There is no way to ensure synchronization if two scripts try to update the
-    same key at the same time.)
-
 ``user-data`` (RW)
     This is a recursive key/value map of arbitrary nodes shared between clients for
     general use (i.e. scripts, IPC clients, host applications, etc).
     The player itself does not use any data in it (although some builtin scripts may).
     The property is not preserved across player restarts.
 
-    This is a more powerful replacement for ``shared-script-properties``.
-
     Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be
     read, written, or observed.
 
@@ -3368,6 +3454,48 @@ Property list
     and not using raw mode, the underlying content will be given (e.g. strings will be
     printed directly, rather than quoted and JSON-escaped).
 
+``menu-data`` (RW)
+    This property stores the raw menu definition. See `Context Menu`_ section for details.
+
+    ``type``
+        Menu item type. Can be: ``separator``, ``submenu``, or empty.
+
+    ``title``
+        Menu item title. Required if type is not ``separator``.
+
+    ``cmd``
+        Command to execute when the menu item is clicked.
+
+    ``shortcut``
+        Menu item shortcut key which appears to the right of the menu item.
+        A shortcut key does not have to be functional; it's just a visual hint.
+
+    ``state``
+        Menu item state. Can be: ``checked``, ``disabled``, ``hidden``, or empty.
+
+    ``submenu``
+        Submenu items, which is required if type is ``submenu``.
+
+    When querying the property with the client API using ``MPV_FORMAT_NODE``, or with
+    Lua ``mp.get_property_native``, this will return a mpv_node with the following
+    contents:
+
+    ::
+
+        MPV_FORMAT_NODE_ARRAY
+            MPV_FORMAT_NODE_MAP (menu item)
+                "type"           MPV_FORMAT_STRING
+                "title"          MPV_FORMAT_STRING
+                "cmd"            MPV_FORMAT_STRING
+                "shortcut"       MPV_FORMAT_STRING
+                "state"          MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]
+                "submenu"        MPV_FORMAT_NODE_ARRAY[menu item]
+
+    Writing to this property with the client API using ``MPV_FORMAT_NODE`` or with
+    Lua ``mp.set_property_native`` will trigger an immediate update of the menu if
+    mpv video output is currently active. You may observe the ``current-vo``
+    property to check if this is the case.
+
 ``working-directory``
     The working directory of the mpv process. Can be useful for JSON IPC users,
     because the command line player usually works with relative paths.
@@ -3430,9 +3558,8 @@ Property list
 ``ffmpeg-version``
     The contents of the ``av_version_info()`` API call. This is a string which
     identifies the build in some way, either through a release version number,
-    or a git hash. This applies to Libav as well (the property is still named
-    the same.) This property is unavailable if mpv is linked against older
-    FFmpeg and Libav versions.
+    or a git hash. This property is unavailable if mpv is linked against older
+    FFmpeg versions.
 
 ``libass-version``
     The value of ``ass_library_version()``. This is an integer, encoded in a
@@ -3681,7 +3808,9 @@ Normally, properties are formatted as human-readable text, meant to be
 displayed on OSD or on the terminal. It is possible to retrieve an unformatted
 (raw) value from a property by prefixing its name with ``=``. These raw values
 can be parsed by other programs and follow the same conventions as the options
-associated with the properties.
+associated with the properties. Additionally, there is a ``>`` prefix to format
+human-readable text, with fixed precision for floating-point values. This is
+useful for printing values where a constant width is important.
 
 .. admonition:: Examples
 
@@ -3690,6 +3819,10 @@ associated with the properties.
     - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds -
       milliseconds are normally not shown in the formatted case)
 
+    - ``${avsync}`` expands to ``+0.003``
+    - ``${>avsync}`` expands to ``+0.0030``
+    - ``${=avsync}`` expands to ``0.003028``
+
 Sometimes, the difference in amount of information carried by raw and formatted
 property values can be rather big. In some cases, raw values have more
 information, like higher precision than seconds with ``time-pos``. Sometimes
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
index bdbb04b..0edb01f 100644
--- a/DOCS/man/javascript.rst
+++ b/DOCS/man/javascript.rst
@@ -27,16 +27,17 @@ otherwise, the documented Lua options, script directories, loading, etc apply to
 JavaScript files too.
 
 Script initialization and lifecycle is the same as with Lua, and most of the Lua
-functions at the modules ``mp``, ``mp.utils``, ``mp.msg`` and ``mp.options`` are
-available to JavaScript with identical APIs - including running commands,
-getting/setting properties, registering events/key-bindings/hooks, etc.
+functions in the modules ``mp``, ``mp.utils``, ``mp.msg``, ``mp.options`` and
+``mp.input`` are available to JavaScript with identical APIs - including running
+commands, getting/setting properties, registering events/key-bindings/hooks,
+etc.
 
 Differences from Lua
 --------------------
 
-No need to load modules. ``mp``, ``mp.utils``,  ``mp.msg`` and ``mp.options``
-are preloaded, and you can use e.g. ``var cwd = mp.utils.getcwd();`` without
-prior setup.
+No need to load modules. ``mp``, ``mp.utils``,  ``mp.msg``, ``mp.options`` and
+``mp.input`` are preloaded, and you can use e.g. ``var cwd =
+mp.utils.getcwd();`` without prior setup.
 
 Errors are slightly different. Where the Lua APIs return ``nil`` for error,
 the JavaScript ones return ``undefined``. Where Lua returns ``something, error``
@@ -195,6 +196,16 @@ meta-paths like ``~~/foo`` (other JS file functions do expand meta paths).
 ``mp.options.read_options(obj [, identifier [, on_update]])`` (types:
 string/boolean/number)
 
+``mp.input.get(obj)`` (LE)
+
+``mp.input.terminate()``
+
+``mp.input.log(message, style)``
+
+``mp.input.log_error(message)``
+
+``mp.input.set_log(log)``
+
 Additional utilities
 --------------------
 
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 5708e19..7377696 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -308,16 +308,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
         ``repeatable``
             If set to ``true``, enables key repeat for this specific binding.
+            This option only makes sense when ``complex`` is not set to ``true``.
 
         ``complex``
-            If set to ``true``, then ``fn`` is called on both key up and down
-            events (as well as key repeat, if enabled), with the first
-            argument being a table. This table has the following entries (and
-            may contain undocumented ones):
+            If set to ``true``, then ``fn`` is called on key down, repeat and up
+            events, with the first argument being a table. This table has the
+            following entries (and may contain undocumented ones):
 
                 ``event``
                     Set to one of the strings ``down``, ``repeat``, ``up`` or
-                    ``press`` (the latter if key up/down can't be tracked).
+                    ``press`` (the latter if key up/down/repeat can't be
+                    tracked).
 
                 ``is_mouse``
                     Boolean Whether the event was caused by a mouse button.
@@ -426,9 +427,9 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     This depends on the property, and it's a valid feature request to ask for
     better update handling of a specific property.
 
-    If the ``type`` is ``none`` or ``nil``, sporadic property change events are
-    possible. This means the change function ``fn`` can be called even if the
-    property doesn't actually change.
+    If the ``type`` is ``none`` or ``nil``, the change function ``fn`` will be
+    called sporadically even if the property doesn't actually change. You should
+    therefore avoid using these types.
 
     You always get an initial change notification. This is meant to initialize
     the user's state to the current value of the property.
@@ -862,6 +863,94 @@ strictly part of the guaranteed API.
     Turn the given value into a string. Formats tables and their contents. This
     doesn't do anything special; it is only needed because Lua is terrible.
 
+mp.input functions
+--------------------
+
+This module lets scripts get textual input from the user using the console
+REPL.
+
+``input.get(table)``
+    Show the console to let the user enter text.
+
+    The following entries of ``table`` are read:
+
+    ``prompt``
+        The string to be displayed before the input field.
+
+    ``submit``
+        A callback invoked when the user presses Enter. The first argument is
+        the text in the console. You can close the console from within the
+        callback by calling ``input.terminate()``. If you don't, the console
+        stays open and the user can input more text.
+
+    ``opened``
+        A callback invoked when the console is shown. This can be used to
+        present a list of options with ``input.set_log()``.
+
+    ``edited``
+        A callback invoked when the text changes. This can be used to filter a
+        list of options based on what the user typed with ``input.set_log()``,
+        like dmenu does. The first argument is the text in the console.
+
+    ``complete``
+        A callback invoked when the user presses TAB. The first argument is the
+        text before the cursor. The callback should return a table of the string
+        candidate completion values and the 1-based cursor position from which
+        the completion starts. console.lua will filter the suggestions beginning
+        with the the text between this position and the cursor, sort them
+        alphabetically, insert their longest common prefix, and show them when
+        there are multiple ones.
+
+    ``closed``
+        A callback invoked when the console is hidden, either because
+        ``input.terminate()`` was invoked from the other callbacks, or because
+        the user closed it with a key binding. The first argument is the text in
+        the console, and the second argument is the cursor position.
+
+    ``default_text``
+        A string to pre-fill the input field with.
+
+    ``cursor_position``
+        The initial cursor position, starting from 1.
+
+    ``id``
+        An identifier that determines which input history and log buffer to use
+        among the ones stored for ``input.get()`` calls. The input histories
+        and logs are stored in memory and do not persist across different mpv
+        invocations. Defaults to the calling script name with ``prompt``
+        appended.
+
+``input.terminate()``
+    Close the console.
+
+``input.log(message, style, terminal_style)``
+    Add a line to the log buffer. ``style`` can contain additional ASS tags to
+    apply to ``message``, and ``terminal_style`` can contain escape sequences
+    that are used when the console is displayed in the terminal.
+
+``input.log_error(message)``
+    Helper to add a line to the log buffer with the same color as the one the
+    console uses for errors. Useful when the user submits invalid input.
+
+``input.set_log(log)``
+    Replace the entire log buffer.
+
+    ``log`` is a table of strings, or tables with ``text``, ``style`` and
+    ``terminal_style`` keys.
+
+    Example:
+
+    ::
+
+        input.set_log({
+            "regular text",
+            {
+                text = "error text",
+                style = "{\\c&H7a77f2&}",
+                terminal_style = "\027[31m",
+            }
+        })
+
 Events
 ------
 
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index e97422d..479458b 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -205,8 +205,11 @@ Shift+PGUP and Shift+PGDWN
     Seek backward or forward by 10 minutes. (This used to be mapped to
     PGUP/PGDWN without Shift.)
 
+b
+    Activate/deactivate debanding.
+
 d
-    Activate/deactivate deinterlacer.
+    Cycle the deinterlacing filter.
 
 A
     Cycle aspect ratio override.
@@ -218,18 +221,16 @@ Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
     Move the video rectangle (panning).
 
 Alt++ and Alt+-
-    Combining ``Alt`` with the ``+`` or ``-`` keys changes video zoom.
+    Change video zoom.
 
 Alt+BACKSPACE
     Reset the pan/zoom settings.
 
 F8
-    Show the playlist and the current position in it (useful only if a UI window
-    is used, broken on the terminal).
+    Show the playlist and the current position in it.
 
 F9
-    Show the list of audio and subtitle streams (useful only if a UI window  is
-    used, broken on the terminal).
+    Show the list of audio and subtitle streams.
 
 i and I
     Show/toggle an overlay displaying statistics about the currently playing
@@ -281,7 +282,7 @@ PREVIOUS and NEXT
     Seek backward/forward 1 minute.
 
 ZOOMIN and ZOOMOUT
-    Changes video zoom.
+    Change video zoom.
 
 If you miss some older key bindings, look at ``etc/restore-old-bindings.conf``
 in the mpv git repository.
@@ -304,6 +305,23 @@ Wheel up/down
 Wheel left/right
     Seek forward/backward 10 seconds.
 
+Ctrl+Wheel up/down
+    Change video zoom.
+
+Context Menu
+-------------
+
+.. warning::
+
+    This feature is experimental. It may not work with all VOs. A libass based
+    fallback may be implemented in the future.
+
+Context Menu is a menu that pops up on the video window on user interaction
+(mouse right click, etc.).
+
+To use this feature, you need to fill the ``menu-data`` property with menu
+definition data, and add a keybinding to run the ``context-menu`` command,
+which can be done with a user script.
 
 USAGE
 =====
@@ -651,8 +669,9 @@ before. This is like passing the exact contents of the quoted string as a
 command line option. C-style escapes are currently _not_ interpreted on this
 level, although some options do this manually (this is a mess and should
 probably be changed at some point). The shell is not involved here, so option
-values only need to be quoted to escape ``#`` and ``\``, ``"``, ``'`` or ``%``
-at the beginning of the value, and leading and trailing whitespace.
+values only need to be quoted to escape ``#`` anywhere in the value, ``"``,
+``'`` or ``%`` at the beginning of the value, and leading and trailing
+whitespace.
 
 Putting Command Line Options into the Configuration File
 --------------------------------------------------------
@@ -710,22 +729,24 @@ or at runtime with the ``apply-profile <name>`` command.
         # a profile that can be enabled with --profile=big-cache
         [big-cache]
         cache=yes
-        demuxer-max-bytes=123400KiB
+        demuxer-max-bytes=512MiB
         demuxer-readahead-secs=20
 
-        [slow]
-        profile-desc="some profile name"
-        # reference a builtin profile
-        profile=high-quality
+        [network]
+        profile-desc="profile for content over network"
+        force-window=immediate
+        # you can also include other profiles
+        profile=big-cache
 
-        [fast]
-        vo=vdpau
+        [reduce-judder]
+        video-sync=display-resample
+        interpolation=yes
 
         # using a profile again extends it
-        [slow]
-        framedrop=no
-        # you can also include other profiles
-        profile=big-cache
+        [network]
+        demuxer-max-back-bytes=512MiB
+        # reference a builtin profile
+        profile=fast
 
 Runtime profiles
 ----------------
@@ -968,7 +989,7 @@ There are three choices for using mpv from other programs or scripts:
        addition, terminal behavior itself may change any time. Compatibility
        cannot be guaranteed.
 
-       Your code should work even if you pass ``--no-terminal``. Do not attempt
+       Your code should work even if you pass ``--terminal=no``. Do not attempt
        to simulate user input by sending terminal control codes to mpv's stdin.
        If you need interactive control, using ``--input-ipc-server`` is
        recommended. This gives you access to the `JSON IPC`_  over unix domain
@@ -1092,7 +1113,7 @@ this with ``--untimed``, but it will likely break, unless the stream has no
 audio, and the input feeds data to the player at a constant rate.
 
 Another common problem is with MJPEG streams. These do not signal the correct
-framerate. Using ``--untimed`` or ``--no-correct-pts --container-fps-override=60``
+framerate. Using ``--untimed`` or ``--correct-pts=no --container-fps-override=60``
 might help.
 
 For livestreams, data can build up due to pausing the stream, due to slightly
@@ -1121,10 +1142,10 @@ commands ``quit-watch-later`` (bound to Shift+Q by default) and
 
 The difference between always quitting with a key bound to ``quit-watch-later``
 and using ``--save-position-on-quit`` is that the latter will save the playback
-position even when mpv is closed with a method other than a keybinding, for
-example if you shutdown your system without closing mpv beforehand, unless of
-course mpv is terminated abruptly and doesn't have the time to save (e.g. with
-the KILL Unix signal).
+position even when mpv is closed with a method other than a keybinding, such as
+clicking the close button in the window title bar. However if mpv is terminated
+abruptly and doesn't have the time to save, then the position will not be saved.
+For example, if you shutdown your system without closing mpv beforehand.
 
 mpv also stores options other than the playback position when they have been
 modified after playback began, for example the volume and selected audio/subtitles,
@@ -1152,8 +1173,8 @@ PROTOCOLS
     either aliases to documented protocols, or are just redirections to
     protocols implemented and documented in FFmpeg.
 
-    ``data:`` is supported in FFmpeg (not in Libav), but needs to be in the
-    format ``data://``. This is done to avoid ambiguity with filenames. You
+    ``data:`` is supported, but needs to be in the format ``data://``.
+    This is done to avoid ambiguity with filenames. You
     can also prefix it with ``lavf://`` or ``ffmpeg://``.
 
 ``ytdl://...``
@@ -1199,17 +1220,28 @@ PROTOCOLS
 
     Digital TV via DVB. (Linux only.)
 
-``mf://[filemask|@listfile]`` ``--mf-...``
+``mf://[@listfile|filemask|glob|printf-format]`` ``--mf-...``
 
     Play a series of images as video.
 
+    If the URL path begins with ``@``, it is interpreted as the path to a file
+    containing a list of image paths separated by newlines. If the URL path
+    contains ``,``, it is interpreted as a list of image paths separated by
+    ``,``. If the URL path does not contain ``%`` and if on POSIX platforms, is
+    interpreted as a glob, and ``*`` is automatically appended if it was not
+    specified. Otherwise, the printf sequences ``%[.][NUM]d``, where ``NUM`` is
+    one, two, or three decimal digits, and ``%%`` and are interpreted. For
+    example, ``mf://image-%d.jpg`` plays files like ``image-1.jpg``,
+    ``image-2.jpg`` and ``image-10.jpg``, provided that there are no big gaps
+    between the files.
+
 ``cdda://[device]`` ``--cdrom-device=PATH`` ``--cdda-...``
 
     Play CD.
 
 ``lavf://...``
 
-    Access any FFmpeg/Libav libavformat protocol. Basically, this passed the
+    Access any FFmpeg libavformat protocol. Basically, this passed the
     string after the ``//`` directly to libavformat.
 
 ``av://type:options``
@@ -1357,27 +1389,6 @@ works like in older mpv releases:
     change, and not apply your additional settings, and/or use a different
     profile name.
 
-Linux desktop issues
-====================
-
-This subsection describes common problems on the Linux desktop. None of these
-problems exist on systems like Windows or macOS.
-
-Disabling Screensaver
----------------------
-
-By default, mpv tries to disable the OS screensaver during playback (only if
-a VO using the OS GUI API is active). ``--stop-screensaver=no`` disables this.
-
-A common problem is that Linux desktop environments ignore the standard
-screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver
-extension (XSS) on X11, and the idle-inhibit protocol on Wayland.
-
-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 these
-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.
-
 
 .. include:: options.rst
 
@@ -1445,7 +1456,7 @@ behavior of mpv.
 ``DISPLAY``
     Standard X11 display name to use.
 
-FFmpeg/Libav:
+FFmpeg:
     This library accesses various environment variables. However, they are not
     centrally documented, and documenting them is not our job. Therefore, this
     list is incomplete.
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
diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst
index c791d75..9ed338a 100644
--- a/DOCS/man/osc.rst
+++ b/DOCS/man/osc.rst
@@ -211,6 +211,13 @@ Configurable Options
 
     Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent).
 
+``scrollcontrols``
+    Default: yes
+
+    By default, going up or down with the mouse wheel can trigger certain
+    actions (such as seeking) if the mouse is hovering an OSC element.
+    Set to ``no`` to disable any special mouse wheel behavior.
+
 ``deadzonesize``
     Default: 0.5
 
@@ -300,7 +307,7 @@ Configurable Options
 
     String that supports property expansion that will be displayed as
     OSC title.
-    ASS tags are escaped, and newlines and trailing slashes are stripped.
+    ASS tags are escaped and newlines are converted to spaces.
 
 ``tooltipborder``
     Default: 1
@@ -393,6 +400,13 @@ Configurable Options
     Supports ``left`` and ``right`` which will place the controls on those
     respective sides.
 
+``windowcontrols_title``
+    Default: ${media-title}
+
+    String that supports property expansion that will be displayed as the
+    windowcontrols title.
+    ASS tags are escaped, and newlines and trailing slashes are stripped.
+
 ``greenandgrumpy``
     Default: no
 
diff --git a/DOCS/man/stats.rst b/DOCS/man/stats.rst
index 88238bc..7ddf851 100644
--- a/DOCS/man/stats.rst
+++ b/DOCS/man/stats.rst
@@ -85,6 +85,18 @@ Configurable Options
     respective duration. This can result in overlapping text when multiple
     scripts decide to print text at the same time.
 
+``term_width_limit``
+    Default: -1
+
+    Sets the terminal width.
+    A value of 0 means the width is infinite, -1 means it's automatic.
+
+``term_height_limit``
+    Default: -1
+
+    Sets the terminal height.
+    A value of 0 means the height is infinite, -1 means it's automatic.
+
 ``plot_perfdata``
     Default: yes
 
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index 1423e4c..59175e7 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -204,10 +204,13 @@ Available mpv-only filters are:
         Available color spaces are:
 
         :auto:          automatic selection (default)
-        :bt.601:        ITU-R BT.601 (SD)
-        :bt.709:        ITU-R BT.709 (HD)
-        :bt.2020-ncl:   ITU-R BT.2020 non-constant luminance system
-        :bt.2020-cl:    ITU-R BT.2020 constant luminance system
+        :bt.601:        ITU-R Rec. BT.601 (SD)
+        :bt.709:        ITU-R Rec. BT.709 (HD)
+        :bt.2020-ncl:   ITU-R Rec. BT.2020 (non-constant luminance)
+        :bt.2020-cl:    ITU-R Rec. BT.2020 (constant luminance)
+        :bt.2100-pq:    ITU-R Rec. BT.2100 ICtCp PQ variant
+        :bt.2100-hlg:   ITU-R Rec. BT.2100 ICtCp HLG variant
+        :dolbyvision:   Dolby Vision
         :smpte-240m:    SMPTE-240M
 
     ``<colorlevels>``
@@ -313,6 +316,10 @@ Available mpv-only filters are:
         Whether or not to include Dolby Vision metadata (default: yes). If
         disabled, any Dolby Vision metadata will be stripped from frames.
 
+    ``<hdr10plus=yes|no>``
+        Whether or not to include HDR10+ metadata (default: yes). If
+        disabled, any HDR10+ metadata will be stripped from frames.
+
     ``<film-grain=yes|no>``
         Whether or not to include film grain metadata (default: yes). If
         disabled, any film grain metadata will be stripped from frames.
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index 5ee4eaa..41fcb71 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -325,7 +325,7 @@ Available video output drivers are:
 ``null``
     Produces no video output. Useful for benchmarking.
 
-    Usually, it's better to disable video with ``--no-video`` instead.
+    Usually, it's better to disable video with ``--video=no`` instead.
 
     The following global options are supported by this video output:
 
@@ -336,6 +336,21 @@ Available video output drivers are:
 ``caca``
     Color ASCII art video output driver that works on a text console.
 
+    This driver reserves some keys for runtime configuration. These keys are
+    hardcoded and cannot be bound:
+
+    d and D
+        Toggle dithering algorithm.
+
+    a and A
+        Toggle antialiasing method.
+
+    h and H
+        Toggle charset method.
+
+    c and C
+        Toggle color method.
+
     .. note:: This driver is a joke.
 
 ``tct``
@@ -348,7 +363,7 @@ Available video output drivers are:
     performance.
 
     Note: the TCT image output is not synchronized with other terminal output
-    from mpv, which can lead to broken images. The options ``--no-terminal`` or
+    from mpv, which can lead to broken images. The options ``--terminal=no`` or
     ``--really-quiet`` can help with that.
 
     ``--vo-tct-algo=<algo>``
@@ -361,6 +376,25 @@ Available video output drivers are:
             Uses spaces. Causes vertical resolution to drop twofolds, but in
             theory works in more places.
 
+    ``--vo-tct-buffering=<pixel|line|frame>``
+        Specifies the size of data batches buffered before being sent to the
+        terminal.
+
+        TCT image output is not synchronized with other terminal output from mpv,
+        which can lead to broken images. Sending data to the terminal in small
+        batches may improve parallelism between terminal processing and mpv
+        processing but incurs a static overhead of generating tens of thousands
+        of small writes. Also, depending on the terminal used, sending frames in
+        one chunk might help with tearing of the output, especially if not used
+        with ``--really-quiet`` and other logs interrupt the data stream.
+
+        pixel
+            Send data to terminal for each pixel.
+        line
+            Send data to terminal for each line. (Default)
+        frame
+            Send data to terminal for each frame.
+
     ``--vo-tct-width=<width>``  ``--vo-tct-height=<height>``
         Assume the terminal has the specified character width and/or height.
         These default to 80x25 if the terminal size cannot be determined.
@@ -567,30 +601,6 @@ Available video output drivers are:
     This also supports many of the options the ``gpu`` VO has, depending on the
     backend.
 
-``rpi`` (Raspberry Pi)
-    Native video output on the Raspberry Pi using the MMAL API.
-
-    The following global options are supported by this video output:
-
-    ``--rpi-display=<number>``
-        Select the display number on which the video overlay should be shown
-        (default: 0).
-
-    ``--rpi-layer=<number>``
-        Select the dispmanx layer on which the video overlay should be shown
-        (default: -10). Note that mpv will also use the 2 layers above the
-        selected layer, to handle the window background and OSD. Actual video
-        rendering will happen on the layer above the selected layer.
-
-    ``--rpi-background=<yes|no>``
-        Whether to render a black background behind the video (default: no).
-        Normally it's better to kill the console framebuffer instead, which
-        gives better performance.
-
-    ``--rpi-osd=<yes|no>``
-        Enabled by default. If disabled with ``no``, no OSD layer is created.
-        This also means there will be no subtitles rendered.
-
 ``drm`` (Direct Rendering Manager)
     Video output driver using Kernel Mode Setting / Direct Rendering Manager.
     Should be used when one doesn't want to install full-blown graphical
@@ -651,17 +661,20 @@ Available video output drivers are:
         lower resolution (the video when handled by the hwdec will be on the
         drmprime-video plane and at full 4K resolution)
 
-    ``--drm-format=<xrgb8888|xrgb2101010>``
+    ``--drm-format=<xrgb8888|xbgr8888|xrgb2101010|xbgr2101010|yuyv>``
         Select the DRM format to use (default: xrgb8888). This allows you to
-        choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per
-        pixel/8 bits per channel packed RGB format with 8 bits of padding.
-        xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB
-        format with 2 bits of padding.
+        choose the bit depth and color type of the DRM mode.
+
+        xrgb8888 is your usual 24bpp packed RGB format with 8 bits of padding.
+        xrgb2101010 is a 30bpp packed RGB format with 2 bits of padding.
+        yuyv is a 32bpp packed YUV 4:2:2 format. No planar formats are currently
+        supported.
 
         There are cases when xrgb2101010 will work with the ``drm`` VO, but not
         with the ``drm`` backend for the ``gpu`` VO. This is because with the
         ``gpu`` VO, in addition to requiring support in your DRM driver,
-        requires support for xrgb2101010 in your EGL driver
+        requires support for xrgb2101010 in your EGL driver.
+        yuyv only ever works with the ``drm`` VO.
 
     ``--drm-draw-surface-size=<[WxH]>``
         Sets the size of the surface used on the draw plane. The surface will