Merging upstream version 0.38.0.

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

1 files changed, 187 insertions, 54 deletions

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