Adding upstream version 0.37.0.upstream/0.37.0

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

1 files changed, 3697 insertions, 0 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
new file mode 100644
index 0000000..8dbf58b
--- /dev/null
+++ b/DOCS/man/input.rst
@@ -0,0 +1,3697 @@
+COMMAND INTERFACE
+=================
+
+The mpv core can be controlled with commands and properties. A number of ways
+to interact with the player use them: key bindings (``input.conf``), OSD
+(showing information with properties), JSON IPC, the client API (``libmpv``),
+and the classic slave mode.
+
+input.conf
+----------
+
+The input.conf file consists of a list of key bindings, for example::
+
+    s screenshot      # take a screenshot with the s key
+    LEFT seek 15      # map the left-arrow key to seeking forward by 15 seconds
+
+Each line maps a key to an input command. Keys are specified with their literal
+value (upper case if combined with ``Shift``), or a name for special keys. For
+example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a``
+with shift.
+
+The file is located in the mpv configuration directory (normally at
+``~/.config/mpv/input.conf`` depending on platform). The default bindings are
+defined here::
+
+    https://github.com/mpv-player/mpv/blob/master/etc/input.conf
+
+A list of special keys can be obtained with
+
+    ``mpv --input-keylist``
+
+In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``::
+
+    ctrl+q quit
+
+**mpv** can be started in input test mode, which displays key bindings and the
+commands they're bound to on the OSD, instead of executing the commands::
+
+    mpv --input-test --force-window --idle
+
+(Only closing the window will make **mpv** exit, pressing normal keys will
+merely display the binding, even if mapped to quit.)
+
+Also see `Key names`_.
+
+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.
+
+Newlines always start a new binding. ``#`` starts a comment (outside of quoted
+string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used.
+
+``<key>`` is either the literal character the key produces (ASCII or Unicode
+character), or a symbolic name (as printed by ``--input-keylist``).
+
+``<section>`` (braced with ``{`` and ``}``) is the input section for this
+command.
+
+``<command>`` is the command itself. It consists of the command name and
+multiple (or none) arguments, all separated by whitespace. String arguments
+should be quoted, typically with ``"``. See ``Flat command syntax``.
+
+You can bind multiple commands to one key. For example:
+
+| a show-text "command 1" ; show-text "command 2"
+
+It's also possible to bind a command to a sequence of keys:
+
+| a-b-c show-text "command run after a, b, c have been pressed"
+
+(This is not shown in the general command syntax.)
+
+If ``a`` or ``a-b`` or ``b`` are already bound, this will run the first command
+that matches, and the multi-key command will never be called. Intermediate keys
+can be remapped to ``ignore`` in order to avoid this issue. The maximum number
+of (non-modifier) keys for combinations is currently 4.
+
+Key names
+---------
+
+All mouse and keyboard input is to converted to mpv-specific key names. Key
+names are either special symbolic identifiers representing a physical key, or a
+text key names, which are unicode code points encoded as UTF-8. These are what
+keyboard input would normally produce, for example ``a`` for the A key. As a
+consequence, mpv uses input translated by the current OS keyboard layout, rather
+than physical scan codes.
+
+Currently there is the hardcoded assumption that every text key can be
+represented as a single unicode code point (in NFKC form).
+
+All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``,
+``Meta``. They must be prefixed to the actual key name, where each modifier
+is followed by a ``+`` (for example ``ctrl+q``).
+
+The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should
+usually be specified as key-name ``@`` at ``input.conf``, and similarly the
+combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like
+``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check
+how a key/combination is seen by mpv.
+
+Symbolic key names and modifier names are case-insensitive. Unicode key names
+are case-sensitive because input bindings typically respect the shift key.
+
+Another type of key names are hexadecimal key names, that serve as fallback
+for special keys that are neither unicode, nor have a special mpv defined name.
+They will break as soon as mpv adds proper names for them, but can enable you
+to use a key at all if that does not happen.
+
+All symbolic names are listed by ``--input-keylist``. ``--input-test`` is a
+special mode that prints all input on the OSD.
+
+Comments on some symbolic names:
+
+``KP*``
+    Keypad names. Behavior varies by backend (whether they implement this, and
+    on how they treat numlock), but typically, mpv tries to map keys on the
+    keypad to separate names, even if they produce the same text as normal keys.
+
+``MOUSE_BTN*``, ``MBTN*``
+    Various mouse buttons.
+
+    Depending on backend, the mouse wheel might also be represented as a button.
+    In addition, ``MOUSE_BTN3`` to ``MOUSE_BTN6`` are deprecated aliases for
+    ``WHEEL_UP``, ``WHEEL_DOWN``, ``WHEEL_LEFT``, ``WHEEL_RIGHT``.
+
+    ``MBTN*`` are aliases for ``MOUSE_BTN*``.
+
+``WHEEL_*``
+    Mouse wheels (typically).
+
+``AXIS_*``
+    Deprecated aliases for ``WHEEL_*``.
+
+``*_DBL``
+    Mouse button double clicks.
+
+``MOUSE_MOVE``, ``MOUSE_ENTER``, ``MOUSE_LEAVE``
+    Emitted by mouse move events. Enter/leave happens when the mouse enters or
+    leave the mpv window (or the current mouse region, using the deprecated
+    mouse region input section mechanism).
+
+``CLOSE_WIN``
+    Pseudo key emitted when closing the mpv window using the OS window manager
+    (for example, by clicking the close button in the window title bar).
+
+``GAMEPAD_*``
+    Keys emitted by the SDL gamepad backend.
+
+``UNMAPPED``
+    Pseudo-key that matches any unmapped key. (You should probably avoid this
+    if possible, because it might change behavior or get removed in the future.)
+
+``ANY_UNICODE``
+    Pseudo-key that matches any key that produces text. (You should probably
+    avoid this if possible, because it might change behavior or get removed in
+    the future.)
+
+Flat command syntax
+-------------------
+
+This is the syntax used in input.conf, and referred to "input.conf syntax" in
+a number of other places.
+
+|
+| ``<command>  ::= [<prefixes>] <command_name> (<argument>)*``
+| ``<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)``
+
+``command_name`` is an unquoted string with the command name itself. See
+`List of Input Commands`_ for a list.
+
+Arguments are separated by whitespaces even if the command expects only one
+argument. Arguments with whitespaces or other special characters must be quoted,
+or the command cannot be parsed correctly.
+
+Double quotes interpret JSON/C-style escaping, like ``\t`` or ``\"`` or ``\\``.
+JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the
+only form which allows newlines at the value - as ``\n``.
+
+Single quotes take the content literally, and cannot include the single-quote
+character at the value.
+
+Custom quotes also take the content literally, but are more flexible than single
+quotes. They start with ````` (back-quote) followed by any ASCII character,
+and end at the first occurrence of the same pair in reverse order, e.g.
+```-foo-``` or ````bar````. The final pair sequence is not allowed at the
+value - in these examples ``-``` and `````` respectively. In the second
+example the last character of the value also can't be a back-quote.
+
+Mixed quoting at the same argument, like ``'foo'"bar"``, is not supported.
+
+Note that argument parsing and property expansion happen at different stages.
+First, arguments are determined as described above, and then, where applicable,
+properties are expanded - regardless of argument quoting. However, expansion
+can still be prevented with the ``raw`` prefix or ``$>``. See `Input Command
+Prefixes`_ and `Property Expansion`_.
+
+Commands specified as arrays
+----------------------------
+
+This applies to certain APIs, such as ``mp.commandv()`` or
+``mp.command_native()`` (with array parameters) in Lua scripting, or
+``mpv_command()`` or ``mpv_command_node()`` (with MPV_FORMAT_NODE_ARRAY) in the
+C libmpv client API.
+
+The command as well as all arguments are passed as a single array. Similar to
+the `Flat command syntax`_, you can first pass prefixes as strings (each as
+separate array item), then the command name as string, and then each argument
+as string or a native value.
+
+Since these APIs pass arguments as separate strings or native values, they do
+not expect quotes, and do support escaping. Technically, there is the input.conf
+parser, which first splits the command string into arguments, and then invokes
+argument parsers for each argument. The input.conf parser normally handles
+quotes and escaping. The array command APIs mentioned above pass strings
+directly to the argument parsers, or can sidestep them by the ability to pass
+non-string values.
+
+Property expansion is disabled by default for these APIs. This can be changed
+with the ``expand-properties`` prefix. See `Input Command Prefixes`_.
+
+Sometimes commands have string arguments, that in turn are actually parsed by
+other components (e.g. filter strings with ``vf add``) - in these cases, you
+you would have to double-escape in input.conf, but not with the array APIs.
+
+For complex commands, consider using `Named arguments`_ instead, which should
+give slightly more compatibility. Some commands do not support named arguments
+and inherently take an array, though.
+
+Named arguments
+---------------
+
+This applies to certain APIs, such as ``mp.command_native()`` (with tables that
+have string keys) in Lua scripting, or ``mpv_command_node()`` (with
+MPV_FORMAT_NODE_MAP) in the C libmpv client API.
+
+The name of the command is provided with a ``name`` string field. The name of
+each command is defined in each command description in the
+`List of Input Commands`_. ``--input-cmdlist`` also lists them. See the
+``subprocess`` command for an example.
+
+Some commands do not support named arguments (e.g. ``run`` command). You need
+to use APIs that pass arguments as arrays.
+
+Named arguments are not supported in the "flat" input.conf syntax, which means
+you cannot use them for key bindings in input.conf at all.
+
+Property expansion is disabled by default for these APIs. This can be changed
+with the ``expand-properties`` prefix. See `Input Command Prefixes`_.
+
+List of Input Commands
+----------------------
+
+Commands with parameters have the parameter name enclosed in ``<`` / ``>``.
+Don't add those to the actual command. Optional arguments are enclosed in
+``[`` / ``]``. If you don't pass them, they will be set to a default value.
+
+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``.
+
+``seek <target> [<flags>]``
+    Change the playback position. By default, seeks by a relative amount of
+    seconds.
+
+    The second argument consists of flags controlling the seek mode:
+
+    relative (default)
+        Seek relative to current position (a negative value seeks backwards).
+    absolute
+        Seek to a given time (a negative value starts from the end of the file).
+    absolute-percent
+        Seek to a given percent position.
+    relative-percent
+        Seek relative to current position in percent.
+    keyframes
+        Always restart playback at keyframe boundaries (fast).
+    exact
+        Always do exact/hr/precise seeks (slow).
+
+    Multiple flags can be combined, e.g.: ``absolute+keyframes``.
+
+    By default, ``keyframes`` is used for ``relative``, ``relative-percent``,
+    and ``absolute-percent`` seeks, while ``exact`` is used for ``absolute``
+    seeks.
+
+    Before mpv 0.9, the ``keyframes`` and ``exact`` flags had to be passed as
+    3rd parameter (essentially using a space instead of ``+``). The 3rd
+    parameter is still parsed, but is considered deprecated.
+
+``revert-seek [<flags>]``
+    Undoes the ``seek`` command, and some other commands that seek (but not
+    necessarily all of them). Calling this command once will jump to the
+    playback position before the seek. Calling it a second time undoes the
+    ``revert-seek`` command itself. This only works within a single file.
+
+    The first argument is optional, and can change the behavior:
+
+    mark
+        Mark the current time position. The next normal ``revert-seek`` command
+        will seek back to this point, no matter how many seeks happened since
+        last time.
+    mark-permanent
+        If set, mark the current position, and do not change the mark position
+        before the next ``revert-seek`` command that has ``mark`` or
+        ``mark-permanent`` set (or playback of the current file ends). Until
+        this happens, ``revert-seek`` will always seek to the marked point. This
+        flag cannot be combined with ``mark``.
+
+    Using it without any arguments gives you the default behavior.
+
+``frame-step``
+    Play one frame, then pause. Does nothing with audio-only playback.
+
+``frame-back-step``
+    Go back by one frame, then pause. Note that this can be very slow (it tries
+    to be precise, not fast), and sometimes fails to behave as expected. How
+    well this works depends on whether precise seeking works correctly (e.g.
+    see the ``--hr-seek-demuxer-offset`` option). Video filters or other video
+    post-processing that modifies timing of frames (e.g. deinterlacing) should
+    usually work, but might make backstepping silently behave incorrectly in
+    corner cases. Using ``--hr-seek-framedrop=no`` should help, although it
+    might make precise seeking slower.
+
+    This does not work with audio-only playback.
+
+``set <name> <value>``
+    Set the given property or option to the given value.
+
+``del <name>``
+    Delete the given property. Most properties cannot be deleted.
+
+``add <name> [<value>]``
+    Add the given value to the property or option. On overflow or underflow,
+    clamp the property to the maximum. If ``<value>`` is omitted, assume ``1``.
+
+``cycle <name> [<value>]``
+    Cycle the given property or option. The second argument can be ``up`` or
+    ``down`` to set the cycle direction. On overflow, set the property back to
+    the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is
+    omitted, assume ``up``.
+
+    Whether or not key-repeat is enabled by default depends on the property.
+    Currently properties with continuous values are repeatable by default (like
+    ``volume``), while discrete values are not (like ``osd-level``).
+
+``multiply <name> <value>``
+    Similar to ``add``, but multiplies the property or option with the numeric
+    value.
+
+``screenshot <flags>``
+    Take a screenshot.
+
+    Multiple flags are available (some can be combined with ``+``):
+
+    <subtitles> (default)
+        Save the video image, in its original resolution, and with subtitles.
+        Some video outputs may still include the OSD in the output under certain
+        circumstances.
+    <video>
+        Like ``subtitles``, but typically without OSD or subtitles. The exact
+        behavior depends on the selected video output.
+    <window>
+        Save the contents of the mpv window. Typically scaled, with OSD and
+        subtitles. The exact behavior depends on the selected video output.
+    <each-frame>
+        Take a screenshot each frame. Issue this command again to stop taking
+        screenshots. Note that you should disable frame-dropping when using
+        this mode - or you might receive duplicate images in cases when a
+        frame was dropped. This flag can be combined with the other flags,
+        e.g. ``video+each-frame``.
+
+    Older mpv versions required passing ``single`` and ``each-frame`` as
+    second argument (and did not have flags). This syntax is still understood,
+    but deprecated and might be removed in the future.
+
+    If you combine this command with another one using ``;``, you can use the
+    ``async`` flag to make encoding/writing the image file asynchronous. For
+    normal standalone commands, this is always asynchronous, and the flag has
+    no effect. (This behavior changed with mpv 0.29.0.)
+
+    On success, returns a ``mpv_node`` with a ``filename`` field set to the
+    saved screenshot location.
+
+``screenshot-to-file <filename> <flags>``
+    Take a screenshot and save it to a given file. The format of the file will
+    be guessed by the extension (and ``--screenshot-format`` is ignored - the
+    behavior when the extension is missing or unknown is arbitrary).
+
+    The second argument is like the first argument to ``screenshot`` and
+    supports ``subtitles``, ``video``, ``window``.
+
+    If the file already exists, it's overwritten.
+
+    Like all input command parameters, the filename is subject to property
+    expansion as described in `Property Expansion`_.
+
+``playlist-next <flags>``
+    Go to the next entry on the playlist.
+
+    First argument:
+
+    weak (default)
+        If the last file on the playlist is currently played, do nothing.
+    force
+        Terminate playback if there are no more files on the playlist.
+
+``playlist-prev <flags>``
+    Go to the previous entry on the playlist.
+
+    First argument:
+
+    weak (default)
+        If the first file on the playlist is currently played, do nothing.
+    force
+        Terminate playback if the first file is being played.
+
+``playlist-next-playlist``
+    Go to the next entry on the playlist with a different ``playlist-path``.
+
+``playlist-prev-playlist``
+    Go to the first of the previous entries on the playlist with a different
+    ``playlist-path``.
+
+``playlist-play-index <integer|current|none>``
+    Start (or restart) playback of the given playlist index. In addition to the
+    0-based playlist entry index, it supports the following values:
+
+    <current>
+        The current playlist entry (as in ``playlist-current-pos``) will be
+        played again (unload and reload). If none is set, playback is stopped.
+        (In corner cases, ``playlist-current-pos`` can point to a playlist entry
+        even if playback is currently inactive,
+
+    <none>
+        Playback is stopped. If idle mode (``--idle``) is enabled, the player
+        will enter idle mode, otherwise it will exit.
+
+    This command is similar to ``loadfile`` in that it only manipulates the
+    state of what to play next, without waiting until the current file is
+    unloaded, and the next one is loaded.
+
+    Setting ``playlist-pos`` or similar properties can have a similar effect to
+    this command. However, it's more explicit, and guarantees that playback is
+    restarted if for example the new playlist entry is the same as the previous
+    one.
+
+``loadfile <url> [<flags> [<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
+    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.
+
+    Second argument:
+
+    <replace> (default)
+        Stop playback of the current file, and play the new file immediately.
+    <append>
+        Append the file to the playlist.
+    <append-play>
+        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
+    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>]``
+    Load the given playlist file or URL (like ``--playlist``).
+
+    Second argument:
+
+    <replace> (default)
+        Stop playback and replace the internal playlist with the new one.
+    <append>
+        Append the new playlist at the end of the current internal playlist.
+    <append-play>
+        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.)
+
+``playlist-clear``
+    Clear the playlist, except the currently played file.
+
+``playlist-remove <index>``
+    Remove the playlist entry at the given index. Index values start counting
+    with 0. The special value ``current`` removes the current entry. Note that
+    removing the current entry also stops playback and starts playing the next
+    entry.
+
+``playlist-move <index1> <index2>``
+    Move the playlist entry at index1, so that it takes the place of the
+    entry index2. (Paradoxically, the moved playlist entry will not have
+    the index value index2 after moving if index1 was lower than index2,
+    because index2 refers to the target entry, not the index the entry
+    will have after moving.)
+
+``playlist-shuffle``
+    Shuffle the playlist. This is similar to what is done on start if the
+    ``--shuffle`` option is used.
+
+``playlist-unshuffle``
+    Attempt to revert the previous ``playlist-shuffle`` command. This works
+    only once (multiple successive ``playlist-unshuffle`` commands do nothing).
+    May not work correctly if new recursive playlists have been opened since
+    a ``playlist-shuffle`` command.
+
+``run <command> [<arg1> [<arg2> [...]]]``
+    Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of
+    mpv (0.2.x and older), this doesn't call the shell. Instead, the command
+    is run directly, with each argument passed separately. Each argument is
+    expanded like in `Property Expansion`_.
+
+    This command has a variable number of arguments, and cannot be used with
+    named arguments.
+
+    The program is run in a detached way. mpv doesn't wait until the command
+    is completed, but continues playback right after spawning it.
+
+    To get the old behavior, use ``/bin/sh`` and ``-c`` as the first two
+    arguments.
+
+    .. admonition:: Example
+
+        ``run "/bin/sh" "-c" "echo ${title} > /tmp/playing"``
+
+        This is not a particularly good example, because it doesn't handle
+        escaping, and a specially prepared file might allow an attacker to
+        execute arbitrary shell commands. It is recommended to write a small
+        shell script, and call that with ``run``.
+
+``subprocess``
+    Similar to ``run``, but gives more control about process execution to the
+    caller, and does does not detach the process.
+
+    You can avoid blocking until the process terminates by running this command
+    asynchronously. (For example ``mp.command_native_async()`` in Lua scripting.)
+
+    This has the following named arguments. The order of them is not guaranteed,
+    so you should always call them with named arguments, see `Named arguments`_.
+
+    ``args`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``)
+        Array of strings with the command as first argument, and subsequent
+        command line arguments following. This is just like the ``run`` command
+        argument list.
+
+        The first array entry is either an absolute path to the executable, or
+        a filename with no path components, in which case the executable is
+        searched in the directories in the ``PATH`` environment variable. On
+        Unix, this is equivalent to ``posix_spawnp`` and ``execvp`` behavior.
+
+    ``playback_only`` (``MPV_FORMAT_FLAG``)
+        Boolean indicating whether the process should be killed when playback
+        of the current playlist entry terminates (optional, default: true). If
+        enabled, stopping playback will automatically kill the process, and you
+        can't start it outside of playback.
+
+    ``capture_size`` (``MPV_FORMAT_INT64``)
+        Integer setting the maximum number of stdout plus stderr bytes that can
+        be captured (optional, default: 64MB). If the number of bytes exceeds
+        this, capturing is stopped. The limit is per captured stream.
+
+    ``capture_stdout`` (``MPV_FORMAT_FLAG``)
+        Capture all data the process outputs to stdout and return it once the
+        process ends (optional, default: no).
+
+    ``capture_stderr`` (``MPV_FORMAT_FLAG``)
+        Same as ``capture_stdout``, but for stderr.
+
+    ``detach`` (``MPV_FORMAT_FLAG``)
+        Whether to run the process in detached mode (optional, default: no). In
+        this mode, the process is run in a new process session, and the command
+        does not wait for the process to terminate. If neither
+        ``capture_stdout`` nor ``capture_stderr`` have been set to true,
+        the command returns immediately after the new process has been started,
+        otherwise the command will read as long as the pipes are open.
+
+    ``env`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``)
+        Set a list of environment variables for the new process (default: empty).
+        If an empty list is passed, the environment of the mpv process is used
+        instead. (Unlike the underlying OS mechanisms, the mpv command cannot
+        start a process with empty environment. Fortunately, that is completely
+        useless.) The format of the list is as in the ``execle()`` syscall. Each
+        string item defines an environment variable as in ``NAME=VALUE``.
+
+        On Lua, you may use ``utils.get_env_list()`` to retrieve the current
+        environment if you e.g. simply want to add a new variable.
+
+    ``stdin_data`` (``MPV_FORMAT_STRING``)
+        Feed the given string to the new process' stdin. Since this is a string,
+        you cannot pass arbitrary binary data. If the process terminates or
+        closes the pipe before all data is written, the remaining data is
+        silently discarded. Probably does not work on win32.
+
+    ``passthrough_stdin`` (``MPV_FORMAT_FLAG``)
+        If enabled, wire the new process' stdin to mpv's stdin (default: no).
+        Before mpv 0.33.0, this argument did not exist, but the behavior was as
+        if this was set to true.
+
+    The command returns the following result (as ``MPV_FORMAT_NODE_MAP``):
+
+    ``status`` (``MPV_FORMAT_INT64``)
+        Typically this is the process exit code (0 or positive) if the process
+        terminates normally, or negative for other errors (failed to start,
+        terminated by mpv, and others).  The meaning of negative values is
+        undefined, other than meaning error (and does not correspond to OS low
+        level exit status values).
+
+        On Windows, it can happen that a negative return value is returned even
+        if the process terminates normally, because the win32 ``UINT`` exit
+        code is assigned to an ``int`` variable before being set as ``int64_t``
+        field in the result map. This might be fixed later.
+
+    ``stdout`` (``MPV_FORMAT_BYTE_ARRAY``)
+        Captured stdout stream, limited to ``capture_size``.
+
+    ``stderr`` (``MPV_FORMAT_BYTE_ARRAY``)
+        Same as ``stdout``, but for stderr.
+
+    ``error_string`` (``MPV_FORMAT_STRING``)
+        Empty string if the process terminated normally. The string ``killed``
+        if the process was terminated in an unusual way. The string ``init`` if
+        the process could not be started.
+
+        On Windows, ``killed`` is only returned when the process has been
+        killed by mpv as a result of ``playback_only`` being set to true.
+
+    ``killed_by_us`` (``MPV_FORMAT_FLAG``)
+        Whether the process has been killed by mpv, for example as a result of
+        ``playback_only`` being set to true, aborting the command (e.g. by
+        ``mp.abort_async_command()``), or if the player is about to exit.
+
+    Note that the command itself will always return success as long as the
+    parameters are correct. Whether the process could be spawned or whether
+    it was somehow killed or returned an error status has to be queried from
+    the result value.
+
+    This command can be asynchronously aborted via API. Also see `Asynchronous
+    command details`_. Only the ``run`` command can start processes in a truly
+    detached way.
+
+    .. note:: The subprocess will always be terminated on player exit if it
+              wasn't started in detached mode, even if ``playback_only`` is
+              false.
+
+    .. admonition:: 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
+        want the end of playback to kill the command.
+
+    .. admonition:: Example
+
+        ::
+
+            local r = mp.command_native({
+                name = "subprocess",
+                playback_only = false,
+                capture_stdout = true,
+                args = {"cat", "/proc/cpuinfo"},
+            })
+            if r.status == 0 then
+                print("result: " .. r.stdout)
+            end
+
+        This is a fairly useless Lua example, which demonstrates how to run
+        a process in a blocking manner, and retrieving its stdout output.
+
+``quit [<code>]``
+    Exit the player. If an argument is given, it's used as process exit code.
+
+``quit-watch-later [<code>]``
+    Exit player, and store current playback position. Playing that file later
+    will seek to the previous position on start. The (optional) argument is
+    exactly as in the ``quit`` command. See `RESUMING PLAYBACK`_.
+
+``sub-add <url> [<flags> [<title> [<lang>]]]``
+    Load the given subtitle file or stream. By default, it is selected as
+    current subtitle  after loading.
+
+    The ``flags`` argument is one of the following values:
+
+    <select>
+
+        Select the subtitle immediately (default).
+
+    <auto>
+
+        Don't select the subtitle. (Or in some special situations, let the
+        default stream selection mechanism decide.)
+
+    <cached>
+
+        Select the subtitle. If a subtitle with the same filename was already
+        added, that one is selected, instead of loading a duplicate entry.
+        (In this case, title/language are ignored, and if the was changed since
+        it was loaded, these changes won't be reflected.)
+
+    The ``title`` argument sets the track title in the UI.
+
+    The ``lang`` argument sets the track language, and can also influence
+    stream selection with ``flags`` set to ``auto``.
+
+``sub-remove [<id>]``
+    Remove the given subtitle track. If the ``id`` argument is missing, remove
+    the current track. (Works on external subtitle files only.)
+
+``sub-reload [<id>]``
+    Reload the given subtitle tracks. If the ``id`` argument is missing, reload
+    the current track. (Works on external subtitle files only.)
+
+    This works by unloading and re-adding the subtitle track.
+
+``sub-step <skip> <flags>``
+    Change subtitle timing such, that the subtitle event after the next
+    ``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step
+    backwards.
+
+    Secondary argument:
+
+    primary (default)
+        Steps through the primary subtitles.
+    secondary
+        Steps through the secondary subtitles.
+
+``sub-seek <skip> <flags>``
+    Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle.
+    This is similar to ``sub-step``, except that it seeks video and audio
+    instead of adjusting the subtitle delay.
+
+    Secondary argument:
+
+    primary (default)
+        Seeks through the primary subtitles.
+    secondary
+        Seeks through the secondary subtitles.
+
+    For embedded subtitles (like with Matroska), this works only with subtitle
+    events that have already been displayed, or are within a short prefetch
+    range.
+
+``print-text <text>``
+    Print text to stdout. The string can contain properties (see
+    `Property Expansion`_). Take care to put the argument in quotes.
+
+``show-text <text> [<duration>|-1 [<level>]]``
+    Show text on the OSD. The string can contain properties, which are expanded
+    as described in `Property Expansion`_. This can be used to show playback
+    time, filename, and so on. ``no-osd`` has no effect on this command.
+
+    <duration>
+        The time in ms to show the message for. By default, it uses the same
+        value as ``--osd-duration``.
+
+    <level>
+        The minimum OSD level to show the text at (see ``--osd-level``).
+
+``expand-text <string>``
+    Property-expand the argument and return the expanded string. This can be
+    used only through the client API or from a script using
+    ``mp.command_native``. (see `Property Expansion`_).
+
+``expand-path "<string>"``
+    Expand a path's double-tilde placeholders into a platform-specific path.
+    As ``expand-text``, 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({"expand-path", "~~home/"}))``
+
+        This line of Lua would show the location of the user's mpv
+        configuration directory on the OSD.
+
+``show-progress``
+    Show the progress bar, the elapsed time and the total duration of the file
+    on the OSD. ``no-osd`` has no effect on this command.
+
+``write-watch-later-config``
+    Write the resume config file that the ``quit-watch-later`` command writes,
+    but continue playback normally.
+
+``delete-watch-later-config [<filename>]``
+    Delete any existing resume config file that was written by
+    ``quit-watch-later`` or ``write-watch-later-config``. If a filename is
+    specified, then the deleted config is for that file; otherwise, it is the
+    same one as would be written by ``quit-watch-later`` or
+    ``write-watch-later-config`` in the current circumstance.
+
+``stop [<flags>]``
+    Stop playback and clear playlist. With default settings, this is
+    essentially like ``quit``. Useful for the client API: playback can be
+    stopped without terminating the player.
+
+    The first argument is optional, and supports the following flags:
+
+    keep-playlist
+        Do not clear the playlist.
+
+
+``mouse <x> <y> [<button> [<mode>]]``
+    Send a mouse event with given coordinate (``<x>``, ``<y>``).
+
+    Second argument:
+
+    <button>
+        The button number of clicked mouse button. This should be one of 0-19.
+        If ``<button>`` is omitted, only the position will be updated.
+
+    Third argument:
+
+    <single> (default)
+        The mouse event represents regular single click.
+
+    <double>
+        The mouse event represents double-click.
+
+``keypress <name>``
+    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.
+
+``keydown <name>``
+    Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is
+    bound to a repeatable command, it will be run repeatedly with mpv's key
+    repeat timing until the ``keyup`` command is called.
+
+``keyup [<name>]``
+    Set the ``KEYUP`` flag, stopping any repeated behavior that had been
+    triggered. ``name`` is optional. If ``name`` is not given or is an
+    empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will
+    only be set on the key specified by ``name``.
+
+``keybind <name> <command>``
+    Binds a key to an input command. ``command`` must be a complete command
+    containing all the desired arguments and flags. Both ``name`` and
+    ``command`` use the ``input.conf`` naming scheme. This is primarily
+    useful for the client API.
+
+``audio-add <url> [<flags> [<title> [<lang>]]]``
+    Load the given audio file. See ``sub-add`` command.
+
+``audio-remove [<id>]``
+    Remove the given audio track. See ``sub-remove`` command.
+
+``audio-reload [<id>]``
+    Reload the given audio tracks. See ``sub-reload`` command.
+
+``video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]``
+    Load the given video file. See ``sub-add`` command for common options.
+
+    ``albumart`` (``MPV_FORMAT_FLAG``)
+        If enabled, mpv will load the given video as album art.
+
+``video-remove [<id>]``
+    Remove the given video track. See ``sub-remove`` command.
+
+``video-reload [<id>]``
+    Reload the given video tracks. See ``sub-reload`` command.
+
+``rescan-external-files [<mode>]``
+    Rescan external files according to the current ``--sub-auto``,
+    ``--audio-file-auto`` and ``--cover-art-auto`` settings. This can be used
+    to auto-load external files *after* the file was loaded.
+
+    The ``mode`` argument is one of the following:
+
+    <reselect> (default)
+        Select the default audio and subtitle streams, which typically selects
+        external files with the highest preference. (The implementation is not
+        perfect, and could be improved on request.)
+
+    <keep-selection>
+        Do not change current track selections.
+
+
+Input Commands that are Possibly Subject to Change
+--------------------------------------------------
+
+``af <operation> <value>``
+    Change audio filter chain. See ``vf`` command.
+
+``vf <operation> <value>``
+    Change video filter chain.
+
+    The semantics are exactly the same as with option parsing (see
+    `VIDEO FILTERS`_). As such the text below is a redundant and incomplete
+    summary.
+
+    The first argument decides what happens:
+
+    <set>
+        Overwrite the previous filter chain with the new one.
+
+    <add>
+        Append the new filter chain to the previous one.
+
+    <toggle>
+        Check if the given filter (with the exact parameters) is already in the
+        video chain. If it is, remove the filter. If it isn't, add the filter.
+        (If several filters are passed to the command, this is done for
+        each filter.)
+
+        A special variant is combining this with labels, and using ``@name``
+        without filter name and parameters as filter entry. This toggles the
+        enable/disable flag.
+
+    <remove>
+        Like ``toggle``, but always remove the given filter from the chain.
+
+    <clr>
+        Remove all filters. Note that like the other sub-commands, this does
+        not control automatically inserted filters.
+
+    The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``.
+
+    You can assign labels to filter by prefixing them with ``@name:`` (where
+    ``name`` is a user-chosen arbitrary identifier). Labels can be used to
+    refer to filters by name in all of the filter chain modification commands.
+    For ``add``, using an already used label will replace the existing filter.
+
+    The ``vf`` command shows the list of requested filters on the OSD after
+    changing the filter chain. This is roughly equivalent to
+    ``show-text ${vf}``. Note that auto-inserted filters for format conversion
+    are not shown on the list, only what was requested by the user.
+
+    Normally, the commands will check whether the video chain is recreated
+    successfully, and will undo the operation on failure. If the command is run
+    before video is configured (can happen if the command is run immediately
+    after opening a file and before a video frame is decoded), this check can't
+    be run. Then it can happen that creating the video chain fails.
+
+    .. admonition:: Example for input.conf
+
+        - ``a vf set vflip`` turn the video upside-down on the ``a`` key
+        - ``b vf set ""`` remove all video filters on ``b``
+        - ``c vf toggle gradfun`` toggle debanding on ``c``
+
+    .. admonition:: Example how to toggle disabled filters at runtime
+
+        - Add something like ``vf-add=@deband:!gradfun`` to ``mpv.conf``.
+          The ``@deband:`` is the label, an arbitrary, user-given name for this
+          filter entry. The ``!`` before the filter name disables the filter by
+          default. Everything after this is the normal filter name and possibly
+          filter parameters, like in the normal ``--vf`` syntax.
+        - Add ``a vf toggle @deband`` to ``input.conf``. This toggles the
+          "disabled" flag for the filter with the label ``deband`` when the
+          ``a`` key is hit.
+
+``cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]``
+    Cycle through a list of values. Each invocation of the command will set the
+    given property to the next value in the list. The command will use the
+    current value of the property/option, and use it to determine the current
+    position in the list of values. Once it has found it, it will set the
+    next value in the list (wrapping around to the first item if needed).
+
+    This command has a variable number of arguments, and cannot be used with
+    named arguments.
+
+    The special argument ``!reverse`` can be used to cycle the value list in
+    reverse. The only advantage is that you don't need to reverse the value
+    list yourself when adding a second key binding for cycling backwards.
+
+``enable-section <name> [<flags>]``
+    This command is deprecated, except for mpv-internal uses.
+
+    Enable all key bindings in the named input section.
+
+    The enabled input sections form a stack. Bindings in sections on the top of
+    the stack are preferred to lower sections. This command puts the section
+    on top of the stack. If the section was already on the stack, it is
+    implicitly removed beforehand. (A section cannot be on the stack more than
+    once.)
+
+    The ``flags`` parameter can be a combination (separated by ``+``) of the
+    following flags:
+
+    <exclusive>
+        All sections enabled before the newly enabled section are disabled.
+        They will be re-enabled as soon as all exclusive sections above them
+        are removed. In other words, the new section shadows all previous
+        sections.
+    <allow-hide-cursor>
+        This feature can't be used through the public API.
+    <allow-vo-dragging>
+        Same.
+
+``disable-section <name>``
+    This command is deprecated, except for mpv-internal uses.
+
+    Disable the named input section. Undoes ``enable-section``.
+
+``define-section <name> <contents> [<flags>]``
+    This command is deprecated, except for mpv-internal uses.
+
+    Create a named input section, or replace the contents of an already existing
+    input section. The ``contents`` parameter uses the same syntax as the
+    ``input.conf`` file (except that using the section syntax in it is not
+    allowed), including the need to separate bindings with a newline character.
+
+    If the ``contents`` parameter is an empty string, the section is removed.
+
+    The section with the name ``default`` is the normal input section.
+
+    In general, input sections have to be enabled with the ``enable-section``
+    command, or they are ignored.
+
+    The last parameter has the following meaning:
+
+    <default> (also used if parameter omitted)
+        Use a key binding defined by this section only if the user hasn't
+        already bound this key to a command.
+    <force>
+        Always bind a key. (The input section that was made active most recently
+        wins if there are ambiguities.)
+
+    This command can be used to dispatch arbitrary keys to a script or a client
+    API user. If the input section defines ``script-binding`` commands, it is
+    also possible to get separate events on key up/down, and relatively detailed
+    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>``
+    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.
+
+    Overlays are usually displayed in screen resolution, but with some VOs,
+    the resolution is reduced to that of the video's. You can read the
+    ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and
+    anamorphic video (such as DVD), ``osd-par`` should be read as well, and the
+    overlay should be aspect-compensated.
+
+    This has the following named arguments. The order of them is not guaranteed,
+    so you should always call them with named arguments, see `Named arguments`_.
+
+    ``id`` is an integer between 0 and 63 identifying the overlay element. The
+    ID can be used to add multiple overlay parts, update a part by using this
+    command with an already existing ID, or to remove a part with
+    ``overlay-remove``. Using a previously unused ID will add a new overlay,
+    while reusing an ID will update it.
+
+    ``x`` and ``y`` specify the position where the OSD should be displayed.
+
+    ``file`` specifies the file the raw image data is read from. It can be
+    either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``),
+    or a filename. The file will be mapped into memory with ``mmap()``,
+    copied, and unmapped before the command returns (changed in mpv 0.18.1).
+
+    It is also possible to pass a raw memory address for use as bitmap memory
+    by passing a memory address as integer prefixed with an ``&`` character.
+    Passing the wrong thing here will crash the player. This mode might be
+    useful for use with libmpv. The ``offset`` parameter is simply added to the
+    memory address (since mpv 0.8.0, ignored before).
+
+    ``offset`` is the byte offset of the first pixel in the source file.
+    (The current implementation always mmap's the whole file from position 0 to
+    the end of the image, so large offsets should be avoided. Before mpv 0.8.0,
+    the offset was actually passed directly to ``mmap``, but it was changed to
+    make using it easier.)
+
+    ``fmt`` is a string identifying the image format. Currently, only ``bgra``
+    is defined. This format has 4 bytes per pixels, with 8 bits per component.
+    The least significant 8 bits are blue, and the most significant 8 bits
+    are alpha (in little endian, the components are B-G-R-A, with B as first
+    byte). This uses premultiplied alpha: every color component is already
+    multiplied with the alpha component. This means the numeric value of each
+    component is equal to or smaller than the alpha component. (Violating this
+    rule will lead to different results with different VOs: numeric overflows
+    resulting from blending broken alpha values is considered something that
+    shouldn't happen, and consequently implementations don't ensure that you
+    get predictable behavior in this case.)
+
+    ``w``, ``h``, and ``stride`` specify the size of the overlay. ``w`` is the
+    visible width of the overlay, while ``stride`` gives the width in bytes in
+    memory. In the simple case, and with the ``bgra`` format, ``stride==4*w``.
+    In general, the total amount of memory accessed is ``stride * h``.
+    (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but
+    for simplicity, the player will access all ``stride * h`` bytes.)
+
+    .. note::
+
+        Before mpv 0.18.1, you had to do manual "double buffering" when updating
+        an overlay by replacing it with a different memory buffer. Since mpv
+        0.18.1, the memory is simply copied and doesn't reference any of the
+        memory indicated by the command's arguments after the command returns.
+        If you want to use this command before mpv 0.18.1, reads the old docs
+        to see how to handle this correctly.
+
+``overlay-remove <id>``
+    Remove an overlay added with ``overlay-add`` and the same ID. Does nothing
+    if no overlay with this ID exists.
+
+``osd-overlay``
+    Add/update/remove an OSD overlay.
+
+    (Although this sounds similar to ``overlay-add``, ``osd-overlay`` is for
+    text overlays, while ``overlay-add`` is for bitmaps. Maybe ``overlay-add``
+    will be merged into ``osd-overlay`` to remove this oddity.)
+
+    You can use this to add text overlays in ASS format. ASS has advanced
+    positioning and rendering tags, which can be used to render almost any kind
+    of vector graphics.
+
+    This command accepts the following parameters:
+
+    ``id``
+        Arbitrary integer that identifies the overlay. Multiple overlays can be
+        added by calling this command with different ``id`` parameters. Calling
+        this command with the same ``id`` replaces the previously set overlay.
+
+        There is a separate namespace for each libmpv client (i.e. IPC
+        connection, script), so IDs can be made up and assigned by the API user
+        without conflicting with other API users.
+
+        If the libmpv client is destroyed, all overlays associated with it are
+        also deleted. In particular, connecting via ``--input-ipc-server``,
+        adding an overlay, and disconnecting will remove the overlay immediately
+        again.
+
+    ``format``
+        String that gives the type of the overlay. Accepts the following values
+        (HTML rendering of this is broken, view the generated manpage instead,
+        or the raw RST source):
+
+        ``ass-events``
+            The ``data`` parameter is a string. The string is split on the
+            newline character. Every line is turned into the ``Text`` part of
+            a ``Dialogue`` ASS event. Timing is unused (but behavior of timing
+            dependent ASS tags may change in future mpv versions).
+
+            Note that it's better to put multiple lines into ``data``, instead
+            of adding multiple OSD overlays.
+
+            This provides 2 ASS ``Styles``. ``OSD`` contains the text style as
+            defined by the current ``--osd-...`` options. ``Default`` is
+            similar, and contains style that ``OSD`` would have if all options
+            were set to the default.
+
+            In addition, the ``res_x`` and ``res_y`` options specify the value
+            of the ASS ``PlayResX`` and ``PlayResY`` header fields. If ``res_y``
+            is set to 0, ``PlayResY`` is initialized to an arbitrary default
+            value (but note that the default for this command is 720, not 0).
+            If ``res_x`` is set to 0, ``PlayResX`` is set based on ``res_y``
+            such that a virtual ASS pixel has a square pixel aspect ratio.
+
+        ``none``
+            Special value that causes the overlay to be removed. Most parameters
+            other than ``id`` and ``format`` are mostly ignored.
+
+    ``data``
+        String defining the overlay contents according to the ``format``
+        parameter.
+
+    ``res_x``, ``res_y``
+        Used if ``format`` is set to ``ass-events`` (see description there).
+        Optional, defaults to 0/720.
+
+    ``z``
+        The Z order of the overlay. Optional, defaults to 0.
+
+        Note that Z order between different overlays of different formats is
+        static, and cannot be changed (currently, this means that bitmap
+        overlays added by ``overlay-add`` are always on top of the ASS overlays
+        added by ``osd-overlay``). In addition, the builtin OSD components are
+        always below any of the custom OSD. (This includes subtitles of any kind
+        as well as text rendered by ``show-text``.)
+
+        It's possible that future mpv versions will randomly change how Z order
+        between different OSD formats and builtin OSD is handled.
+
+    ``hidden``
+        If set to true, do not display this (default: false).
+
+    ``compute_bounds``
+        If set to true, attempt to determine bounds and write them to the
+        command's result value as ``x0``, ``x1``, ``y0``, ``y1`` rectangle
+        (default: false). If the rectangle is empty, not known, or somehow
+        degenerate, it is not set. ``x1``/``y1`` is the coordinate of the
+        bottom exclusive corner of the rectangle.
+
+        The result value may depend on the VO window size, and is based on the
+        last known window size at the time of the call. This means the results
+        may be different from what is actually rendered.
+
+        For ``ass-events``, the result rectangle is recomputed to ``PlayRes``
+        coordinates (``res_x``/``res_y``). If window size is not known, a
+        fallback is chosen.
+
+        You should be aware that this mechanism is very inefficient, as it
+        renders the full result, and then uses the bounding box of the rendered
+        bitmap list (even if ``hidden`` is set). It will flush various caches.
+        Its results also depend on the used libass version.
+
+        This feature is experimental, and may change in some way again.
+
+    .. note::
+
+        Always use named arguments (``mpv_command_node()``). Lua scripts should
+        use the ``mp.create_osd_overlay()`` helper instead of invoking this
+        command directly.
+
+``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
+    mean is fully up to the receiver and the sender. Every client receives the
+    message, so be careful about name clashes (or use ``script-message-to``).
+
+    This command has a variable number of arguments, and cannot be used with
+    named arguments.
+
+``script-message-to <target> [<arg1> [<arg2> [...]]]``
+    Same as ``script-message``, but send it only to the client named
+    ``<target>``. Each client (scripts etc.) has a unique name. For example,
+    Lua scripts can get their name via ``mp.get_script_name()``. Note that
+    client names only consist of alphanumeric characters and ``_``.
+
+    This command has a variable number of arguments, and cannot be used with
+    named arguments.
+
+``script-binding <name>``
+    Invoke a script-provided key binding. This can be used to remap key
+    bindings provided by external Lua scripts.
+
+    The argument is the name of the binding.
+
+    It can optionally be prefixed with the name of the script, using ``/`` as
+    separator, e.g. ``script-binding scriptname/bindingname``. Note that script
+    names only consist of alphanumeric characters and ``_``.
+
+    For completeness, here is how this command works internally. The details
+    could change any time. On any matching key event, ``script-message-to``
+    or ``script-message`` is called (depending on whether the script name is
+    included), with the following arguments:
+
+    1. The string ``key-binding``.
+    2. The name of the binding (as established above).
+    3. The key state as string (see below).
+    4. The key name (since mpv 0.15.0).
+    5. The text the key would produce, or empty string if not applicable.
+
+    The 5th argument is only set if no modifiers are present (using the shift
+    key with a letter is normally not emitted as having a modifier, and results
+    in upper case text instead, but some backends may mess up).
+
+    The key state consists of 2 characters:
+
+    1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key
+       is still down, and was repeated; only if key repeat is enabled for this
+       binding), ``p`` (key was pressed; happens if up/down can't be tracked).
+    2. Whether the event originates from the mouse, either ``m`` (mouse button)
+       or ``-`` (something else).
+
+    Future versions can add more arguments and more key state characters to
+    support more input peculiarities.
+
+``ab-loop``
+    Cycle through A-B loop states. The first command will set the ``A`` point
+    (the ``ab-loop-a`` property); the second the ``B`` point, and the third
+    will clear both points.
+
+``drop-buffers``
+    Drop audio/video/demuxer buffers, and restart from fresh. Might help with
+    unseekable streams that are going out of sync.
+    This command might be changed or removed in the future.
+
+``screenshot-raw [<flags>]``
+    Return a screenshot in memory. This can be used only through the client
+    API. The MPV_FORMAT_NODE_MAP returned by this command has the ``w``, ``h``,
+    ``stride`` fields set to obvious contents. The ``format`` field is set to
+    ``bgr0`` by default. This format is organized as ``B8G8R8X8`` (where ``B``
+    is the LSB). The contents of the padding ``X`` are undefined. The ``data``
+    field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image
+    is freed as soon as the result mpv_node is freed. As usual with client API
+    semantics, you are not allowed to write to the image data.
+
+    The ``stride`` is the number of bytes from a pixel at ``(x0, y0)`` to the
+    pixel at ``(x0, y0 + 1)``. This can be larger than ``w * 4`` if the image
+    was cropped, or if there is padding. This number can be negative as well.
+    You access a pixel with ``byte_index = y * stride + x * 4`` (assuming the
+    ``bgr0`` format).
+
+    The ``flags`` argument is like the first argument to ``screenshot`` and
+    supports ``subtitles``, ``video``, ``window``.
+
+``vf-command <label> <command> <argument> [<target>]``
+    Send a command to the filter. Note that currently, this only works with
+    the ``lavfi`` filter. Refer to the libavfilter documentation for the list
+    of supported commands for each filter.
+
+    ``<label>`` is a mpv filter label, use ``all`` to send it to all filters
+    at once.
+
+    ``<command>`` and ``<argument>`` are filter-specific strings.
+
+    ``<target>`` is a filter or filter instance name and defaults to ``all``.
+    Note that the target is an additional specifier for filters that
+    support them, such as complex ``lavfi`` filter chains.
+
+``af-command <label> <command> <argument> [<target>]``
+    Same as ``vf-command``, but for audio filters.
+
+``apply-profile <name> [<mode>]``
+    Apply the contents of a named profile. This is like using ``profile=name``
+    in a config file, except you can map it to a key binding to change it at
+    runtime.
+
+    The mode argument:
+
+    ``default``
+        Apply the profile. Default if the argument is omitted.
+
+    ``restore``
+        Restore options set by a previous ``apply-profile`` command for this
+        profile. Only works if the profile has ``profile-restore`` set to a
+        relevant mode. Prints a warning if nothing could be done. See
+        `Runtime profiles`_ for details.
+
+``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
+    future behavior is left undefined.
+
+    On success, returns a ``mpv_node`` with a ``client_id`` field set to the
+    return value of the ``mpv_client_id()`` API call of the newly created script
+    handle.
+
+``change-list <name> <operation> <value>``
+    This command changes list options as described in `List Options`_. The
+    ``<name>`` parameter is the normal option name, while ``<operation>`` is
+    the suffix or action used on the option.
+
+    Some operations take no value, but the command still requires the value
+    parameter. In these cases, the value must be an empty string.
+
+    .. admonition:: Example
+
+        ``change-list glsl-shaders append file.glsl``
+
+        Add a filename to the ``glsl-shaders`` list. The command line
+        equivalent is ``--glsl-shaders-append=file.glsl`` or alternatively
+        ``--glsl-shader=file.glsl``.
+
+``dump-cache <start> <end> <filename>``
+    Dump the current cache to the given filename. The ``<filename>`` file is
+    overwritten if it already exists. ``<start>`` and ``<end>`` give the
+    time range of what to dump. If no data is cached at the given time range,
+    nothing may be dumped (creating a file with no packets).
+
+    Dumping a larger part of the cache will freeze the player. No effort was
+    made to fix this, as this feature was meant mostly for creating small
+    excerpts.
+
+    See ``--stream-record`` for various caveats that mostly apply to this
+    command too, as both use the same underlying code for writing the output
+    file.
+
+    If ``<filename>`` is an empty string, an ongoing ``dump-cache`` is stopped.
+
+    If ``<end>`` is ``no``, then continuous dumping is enabled. Then, after
+    dumping the existing parts of the cache, anything read from network is
+    appended to the cache as well. This behaves similar to ``--stream-record``
+    (although it does not conflict with that option, and they can be both active
+    at the same time).
+
+    If the ``<end>`` time is after the cache, the command will _not_ wait and
+    write newly received data to it.
+
+    The end of the resulting file may be slightly damaged or incomplete at the
+    end. (Not enough effort was made to ensure that the end lines up properly.)
+
+    Note that this command will finish only once dumping ends. That means it
+    works similar to the ``screenshot`` command, just that it can block much
+    longer. If continuous dumping is used, the command will not finish until
+    playback is stopped, an error happens, another ``dump-cache`` command is
+    run, or an API like ``mp.abort_async_command`` was called to explicitly stop
+    the command. See `Synchronous vs. Asynchronous`_.
+
+    .. note::
+
+        This was mostly created for network streams. For local files, there may
+        be much better methods to create excerpts and such. There are tons of
+        much more user-friendly Lua scripts, that will re-encode parts of a file
+        by spawning a separate instance of ``ffmpeg``. With network streams,
+        this is not that easily possible, as the stream would have to be
+        downloaded again. Even if ``--stream-record`` is used to record the
+        stream to the local filesystem, there may be problems, because the
+        recorded file is still written to.
+
+    This command is experimental, and all details about it may change in the
+    future.
+
+``ab-loop-dump-cache <filename>``
+    Essentially calls ``dump-cache`` with the current AB-loop points as
+    arguments. Like ``dump-cache``, this will overwrite the file at
+    ``<filename>``. Likewise, if the B point is set to ``no``, it will enter
+    continuous dumping after the existing cache was dumped.
+
+    The author reserves the right to remove this command if enough motivation
+    is found to move this functionality to a trivial Lua script.
+
+``ab-loop-align-cache``
+    Re-adjust the A/B loop points to the start and end within the cache the
+    ``ab-loop-dump-cache`` command will (probably) dump. Basically, it aligns
+    the times on keyframes. The guess might be off especially at the end (due to
+    granularity issues due to remuxing). If the cache shrinks in the meantime,
+    the points set by the command will not be the effective parameters either.
+
+    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.
+
+Undocumented commands: ``ao-reload`` (experimental/internal).
+
+List of events
+~~~~~~~~~~~~~~
+
+This is a partial list of events. This section describes what
+``mpv_event_to_node()`` returns, and which is what scripting APIs and the JSON
+IPC sees. Note that the C API has separate C-level declarations with
+``mpv_event``, which may be slightly different.
+
+Note that events are asynchronous: the player core continues running while
+events are delivered to scripts and other clients. In some cases, you can use
+hooks to enforce synchronous execution.
+
+All events can have the following fields:
+
+``event``
+    Name as the event (as returned by ``mpv_event_name()``).
+
+``id``
+    The ``reply_userdata`` field (opaque user value). If ``reply_userdata`` is 0,
+    the field is not added.
+
+``error``
+    Set to an error string (as returned by ``mpv_error_string()``). This field
+    is missing if no error happened, or the event type does not report error.
+    Most events leave this unset.
+
+This list uses the event name field value, and the C API symbol in brackets:
+
+``start-file`` (``MPV_EVENT_START_FILE``)
+    Happens right before a new file is loaded. When you receive this, the
+    player is loading the file (or possibly already done with it).
+
+    This has the following fields:
+
+    ``playlist_entry_id``
+        Playlist entry ID of the file being loaded now.
+
+``end-file`` (``MPV_EVENT_END_FILE``)
+    Happens after a file was unloaded. Typically, the player will load the
+    next file right away, or quit if this was the last file.
+
+    The event has the following fields:
+
+    ``reason``
+        Has one of these values:
+
+        ``eof``
+            The file has ended. This can (but doesn't have to) include
+            incomplete files or broken network connections under
+            circumstances.
+
+        ``stop``
+            Playback was ended by a command.
+
+        ``quit``
+            Playback was ended by sending the quit command.
+
+        ``error``
+            An error happened. In this case, an ``error`` field is present with
+            the error string.
+
+        ``redirect``
+            Happens with playlists and similar. Details see
+            ``MPV_END_FILE_REASON_REDIRECT`` in the C API.
+
+        ``unknown``
+            Unknown. Normally doesn't happen, unless the Lua API is out of sync
+            with the C API. (Likewise, it could happen that your script gets
+            reason strings that did not exist yet at the time your script was
+            written.)
+
+    ``playlist_entry_id``
+        Playlist entry ID of the file that was being played or attempted to be
+        played. This has the same value as the ``playlist_entry_id`` field in the
+        corresponding ``start-file`` event.
+
+    ``file_error``
+        Set to mpv error string describing the approximate reason why playback
+        failed. Unset if no error known. (In Lua scripting, this value was set
+        on the ``error`` field directly. This is deprecated since mpv 0.33.0.
+        In the future, this ``error`` field will be unset for this specific
+        event.)
+
+    ``playlist_insert_id``
+        If loading ended, because the playlist entry to be played was for example
+        a playlist, and the current playlist entry is replaced with a number of
+        other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT
+        (other event types may use this for similar but different purposes in the
+        future). In this case, playlist_insert_id will be set to the playlist
+        entry ID of the first inserted entry, and playlist_insert_num_entries to
+        the total number of inserted playlist entries. Note this in this specific
+        case, the ID of the last inserted entry is playlist_insert_id+num-1.
+        Beware that depending on circumstances, you may observe the new playlist
+        entries before seeing the event (e.g. reading the "playlist" property or
+        getting a property change notification before receiving the event).
+        If this is 0 in the C API, this field isn't added.
+
+    ``playlist_insert_num_entries``
+        See playlist_insert_id. Only present if playlist_insert_id is present.
+
+``file-loaded``  (``MPV_EVENT_FILE_LOADED``)
+    Happens after a file was loaded and begins playback.
+
+``seek`` (``MPV_EVENT_SEEK``)
+    Happens on seeking. (This might include cases when the player seeks
+    internally, even without user interaction. This includes e.g. segment
+    changes when playing ordered chapters Matroska files.)
+
+``playback-restart`` (``MPV_EVENT_PLAYBACK_RESTART``)
+    Start of playback after seek or after file was loaded.
+
+``shutdown`` (``MPV_EVENT_SHUTDOWN``)
+    Sent when the player quits, and the script should terminate. Normally
+    handled automatically. See `Details on the script initialization and lifecycle`_.
+
+``log-message`` (``MPV_EVENT_LOG_MESSAGE``)
+    Receives messages enabled with ``mpv_request_log_messages()`` (Lua:
+    ``mp.enable_messages``).
+
+    This contains, in addition to the default event fields, the following
+    fields:
+
+    ``prefix``
+        The module prefix, identifies the sender of the message. This is what
+        the terminal player puts in front of the message text when using the
+        ``--v`` option, and is also what is used for ``--msg-level``.
+
+    ``level``
+        The log level as string. See ``msg.log`` for possible log level names.
+        Note that later versions of mpv might add new levels or remove
+        (undocumented) existing ones.
+
+    ``text``
+        The log message. The text will end with a newline character. Sometimes
+        it can contain multiple lines.
+
+    Keep in mind that these messages are meant to be hints for humans. You
+    should not parse them, and prefix/level/text of messages might change
+    any time.
+
+``hook``
+    The event has the following fields:
+
+    ``hook_id``
+        ID to pass to ``mpv_hook_continue()``. The Lua scripting wrapper
+        provides a better API around this with ``mp.add_hook()``.
+
+``get-property-reply`` (``MPV_EVENT_GET_PROPERTY_REPLY``)
+    See C API.
+
+``set-property-reply`` (``MPV_EVENT_SET_PROPERTY_REPLY``)
+    See C API.
+
+``command-reply`` (``MPV_EVENT_COMMAND_REPLY``)
+    This is one of the commands for which the ```error`` field is meaningful.
+
+    JSON IPC and Lua and possibly other backends treat this specially and may
+    not pass the actual event to the user. See C API.
+
+    The event has the following fields:
+
+    ``result``
+        The result (on success) of any ``mpv_node`` type, if any.
+
+``client-message`` (``MPV_EVENT_CLIENT_MESSAGE``)
+    Lua and possibly other backends treat this specially and may not pass the
+    actual event to the user.
+
+    The event has the following fields:
+
+    ``args``
+        Array of strings with the message data.
+
+``video-reconfig`` (``MPV_EVENT_VIDEO_RECONFIG``)
+    Happens on video output or filter reconfig.
+
+``audio-reconfig`` (``MPV_EVENT_AUDIO_RECONFIG``)
+    Happens on audio output or filter reconfig.
+
+``property-change`` (``MPV_EVENT_PROPERTY_CHANGE``)
+    Happens when a property that is being observed changes value.
+
+    The event has the following fields:
+
+    ``name``
+        The name of the property.
+
+    ``data``
+        The new value of the property.
+
+The following events also happen, but are deprecated: ``idle``, ``tick``
+Use ``mpv_observe_property()`` (Lua: ``mp.observe_property()``) instead.
+
+Hooks
+~~~~~
+
+Hooks are synchronous events between player core and a script or similar. This
+applies to client API (including the Lua scripting interface). Normally,
+events are supposed to be asynchronous, and the hook API provides an awkward
+and obscure way to handle events that require stricter coordination. There are
+no API stability guarantees made. Not following the protocol exactly can make
+the player freeze randomly. Basically, nobody should use this API.
+
+The C API is described in the header files. The Lua API is described in the
+Lua section.
+
+Before a hook is actually invoked on an API clients, it will attempt to return
+new values for all observed properties that were changed before the hook. This
+may make it easier for an application to set defined "barriers" between property
+change notifications by registering hooks. (That means these hooks will have an
+effect, even if you do nothing and make them continue immediately.)
+
+The following hooks are currently defined:
+
+``on_load``
+    Called when a file is to be opened, before anything is actually done.
+    For example, you could read and write the ``stream-open-filename``
+    property to redirect an URL to something else (consider support for
+    streaming sites which rarely give the user a direct media URL), or
+    you could set per-file options with by setting the property
+    ``file-local-options/<option name>``. The player will wait until all
+    hooks are run.
+
+    Ordered after ``start-file`` and before ``playback-restart``.
+
+``on_load_fail``
+    Called after after a file has been opened, but failed to. This can be
+    used to provide a fallback in case native demuxers failed to recognize
+    the file, instead of always running before the native demuxers like
+    ``on_load``. Demux will only be retried if ``stream-open-filename``
+    was changed. If it fails again, this hook is _not_ called again, and
+    loading definitely fails.
+
+    Ordered after ``on_load``, and before ``playback-restart`` and ``end-file``.
+
+``on_preloaded``
+    Called after a file has been opened, and before tracks are selected and
+    decoders are created. This has some usefulness if an API users wants
+    to select tracks manually, based on the set of available tracks. It's
+    also useful to initialize ``--lavfi-complex`` in a specific way by API,
+    without having to "probe" the available streams at first.
+
+    Note that this does not yet apply default track selection. Which operations
+    exactly can be done and not be done, and what information is available and
+    what is not yet available yet, is all subject to change.
+
+    Ordered after ``on_load_fail`` etc. and before ``playback-restart``.
+
+``on_unload``
+    Run before closing a file, and before actually uninitializing
+    everything. It's not possible to resume playback in this state.
+
+    Ordered before ``end-file``. Will also happen in the error case (then after
+    ``on_load_fail``).
+
+``on_before_start_file``
+    Run before a ``start-file`` event is sent. (If any client changes the
+    current playlist entry, or sends a quit command to the player, the
+    corresponding event will not actually happen after the hook returns.)
+    Useful to drain property changes before a new file is loaded.
+
+``on_after_end_file``
+    Run after an ``end-file`` event. Useful to drain property changes after a
+    file has finished.
+
+Input Command Prefixes
+----------------------
+
+These prefixes are placed between key name and the actual command. Multiple
+prefixes can be specified. They are separated by whitespace.
+
+``osd-auto``
+    Use the default behavior for this command. This is the default for
+    ``input.conf`` commands. Some libmpv/scripting/IPC APIs do not use this as
+    default, but use ``no-osd`` instead.
+``no-osd``
+    Do not use any OSD for this command.
+``osd-bar``
+    If possible, show a bar with this command. Seek commands will show the
+    progress bar, property changing commands may show the newly set value.
+``osd-msg``
+    If possible, show an OSD message with this command. Seek command show
+    the current playback time, property changing commands show the newly set
+    value as text.
+``osd-msg-bar``
+    Combine osd-bar and osd-msg.
+``raw``
+    Do not expand properties in string arguments. (Like ``"${property-name}"``.)
+    This is the default for some libmpv/scripting/IPC APIs.
+``expand-properties``
+    All string arguments are expanded as described in `Property Expansion`_.
+    This is the default for ``input.conf`` commands.
+``repeatable``
+    For some commands, keeping a key pressed doesn't run the command repeatedly.
+    This prefix forces enabling key repeat in any case. For a list of commands:
+    the first command determines the repeatability of the whole list (up to and
+    including version 0.33 - a list was always repeatable).
+``async``
+    Allow asynchronous execution (if possible). Note that only a few commands
+    will support this (usually this is explicitly documented). Some commands
+    are asynchronous by default (or rather, their effects might manifest
+    after completion of the command). The semantics of this flag might change
+    in the future. Set it only if you don't rely on the effects of this command
+    being fully realized when it returns. See `Synchronous vs. Asynchronous`_.
+``sync``
+    Allow synchronous execution (if possible). Normally, all commands are
+    synchronous by default, but some are asynchronous by default for
+    compatibility with older behavior.
+
+All of the osd prefixes are still overridden by the global ``--osd-level``
+settings.
+
+Synchronous vs. Asynchronous
+----------------------------
+
+The ``async`` and ``sync`` prefix matter only for how the issuer of the command
+waits on the completion of the command. Normally it does not affect how the
+command behaves by itself. There are the following cases:
+
+- Normal input.conf commands are always run asynchronously. Slow running
+  commands are queued up or run in parallel.
+- "Multi" input.conf commands (1 key binding, concatenated with ``;``) will be
+  executed in order, except for commands that are async (either prefixed with
+  ``async``, or async by default for some commands). The async commands are
+  run in a detached manner, possibly in parallel to the remaining sync commands
+  in the list.
+- Normal Lua and libmpv commands (e.g. ``mpv_command()``) are run in a blocking
+  manner, unless the ``async`` prefix is used, or the command is async by
+  default. This means in the sync case the caller will block, even if the core
+  continues playback. Async mode runs the command in a detached manner.
+- Async libmpv command API (e.g. ``mpv_command_async()``) never blocks the
+  caller, and always notify their completion with a message. The ``sync`` and
+  ``async`` prefixes make no difference.
+- Lua also provides APIs for running async commands, which behave similar to the
+  C counterparts.
+- In all cases, async mode can still run commands in a synchronous manner, even
+  in detached mode. This can for example happen in cases when a command does not
+  have an  asynchronous implementation. The async libmpv API still never blocks
+  the caller in these cases.
+
+Before mpv 0.29.0, the ``async`` prefix was only used by screenshot commands,
+and made them run the file saving code in a detached manner. This is the
+default now, and ``async`` changes behavior only in the ways mentioned above.
+
+Currently the following commands have different waiting characteristics with
+sync vs. async: sub-add, audio-add, sub-reload, audio-reload,
+rescan-external-files, screenshot, screenshot-to-file, dump-cache,
+ab-loop-dump-cache.
+
+Asynchronous command details
+----------------------------
+
+On the API level, every asynchronous command is bound to the context which
+started it. For example, an asynchronous command started by ``mpv_command_async``
+is bound to the ``mpv_handle`` passed to the function. Only this ``mpv_handle``
+receives the completion notification (``MPV_EVENT_COMMAND_REPLY``), and only
+this handle can abort a still running command directly. If the ``mpv_handle`` is
+destroyed, any still running async. commands started by it are terminated.
+
+The scripting APIs and JSON IPC give each script/connection its own implicit
+``mpv_handle``.
+
+If the player is closed, the core may abort all pending async. commands on its
+own (like a forced ``mpv_abort_async_command()`` call for each pending command
+on behalf of the API user). This happens at the same time ``MPV_EVENT_SHUTDOWN``
+is sent, and there is no way to prevent this.
+
+Input Sections
+--------------
+
+Input sections group a set of bindings, and enable or disable them at once.
+In ``input.conf``, each key binding is assigned to an input section, rather
+than actually having explicit text sections.
+
+See also: ``enable-section`` and ``disable-section`` commands.
+
+Predefined bindings:
+
+``default``
+    Bindings without input section are implicitly assigned to this section. It
+    is enabled by default during normal playback.
+``encode``
+    Section which is active in encoding mode. It is enabled exclusively, so
+    that bindings in the ``default`` sections are ignored.
+
+Properties
+----------
+
+Properties are used to set mpv options during runtime, or to query arbitrary
+information. They can be manipulated with the ``set``/``add``/``cycle``
+commands, and retrieved with ``show-text``, or anything else that uses property
+expansion. (See `Property Expansion`_.)
+
+The property name is annotated with RW to indicate whether the property is
+generally writable.
+
+If an option is referenced, the property will normally take/return exactly the
+same values as the option. In these cases, properties are merely a way to change
+an option at runtime.
+
+Property list
+-------------
+
+.. note::
+
+    Most options can be set at runtime via properties as well. Just remove the
+    leading ``--`` from the option name. These are not documented below, see
+    `OPTIONS`_ instead. Only properties which do not exist as option with the
+    same name, or which have very different behavior from the options are
+    documented below.
+
+    Properties marked as (RW) are writeable, while those that aren't are
+    read-only.
+
+``audio-speed-correction``, ``video-speed-correction``
+    Factor multiplied with ``speed`` at which the player attempts to play the
+    file. Usually it's exactly 1. (Display sync mode will make this useful.)
+
+    OSD formatting will display it in the form of ``+1.23456%``, with the number
+    being ``(raw - 1) * 100`` for the given raw property value.
+
+``display-sync-active``
+    Whether ``--video-sync=display`` is actually active.
+
+``filename``
+    Currently played file, with path stripped. If this is an URL, try to undo
+    percent encoding as well. (The result is not necessarily correct, but
+    looks better for display purposes. Use the ``path`` property to get an
+    unmodified filename.)
+
+    This has a sub-property:
+
+    ``filename/no-ext``
+        Like the ``filename`` property, but if the text contains a ``.``, strip
+        all text after the last ``.``. Usually this removes the file extension.
+
+``file-size``
+    Length in bytes of the source file/stream. (This is the same as
+    ``${stream-end}``. For segmented/multi-part files, this will return the
+    size of the main or manifest file, whatever it is.)
+
+``estimated-frame-count``
+    Total number of frames in current file.
+
+    .. note:: This is only an estimate. (It's computed from two unreliable
+              quantities: fps and stream length.)
+
+``estimated-frame-number``
+    Number of current frame in current stream.
+
+    .. note:: This is only an estimate. (It's computed from two unreliable
+              quantities: fps and possibly rounded timestamps.)
+
+``pid``
+    Process-id of mpv.
+
+``path``
+    Full path of the currently played file. Usually this is exactly the same
+    string you pass on the mpv command line or the ``loadfile`` command, even
+    if it's a relative path. If you expect an absolute path, you will have to
+    determine it yourself, for example by using the ``working-directory``
+    property.
+
+``stream-open-filename``
+    The full path to the currently played media. This is different from
+    ``path`` only in special cases. In particular, if ``--ytdl=yes`` is used,
+    and the URL is detected by ``youtube-dl``, then the script will set this
+    property to the actual media URL. This property should be set only during
+    the ``on_load`` or ``on_load_fail`` hooks, otherwise it will have no effect
+    (or may do something implementation defined in the future). The property is
+    reset if playback of the current media ends.
+
+``media-title``
+    If the currently played file has a ``title`` tag, use that.
+
+    Otherwise, return the ``filename`` property.
+
+``file-format``
+    Symbolic name of the file format. In some cases, this is a comma-separated
+    list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list
+    may grow in the future for any format).
+
+``current-demuxer``
+    Name of the current demuxer. (This is useless.)
+
+    (Renamed from ``demuxer``.)
+
+``stream-path``
+    Filename (full path) of the stream layer filename. (This is probably
+    useless and is almost never different from ``path``.)
+
+``stream-pos``
+    Raw byte position in source stream. Technically, this returns the position
+    of the most recent packet passed to a decoder.
+
+``stream-end``
+    Raw end position in bytes in source stream.
+
+``duration``
+    Duration of the current file in seconds. If the duration is unknown, the
+    property is unavailable. Note that the file duration is not always exactly
+    known, so this is an estimate.
+
+    This replaces the ``length`` property, which was deprecated after the
+    mpv 0.9 release. (The semantics are the same.)
+
+    This has a sub-property:
+
+    ``duration/full``
+        ``duration`` with milliseconds.
+
+``avsync``
+    Last A/V synchronization difference. Unavailable if audio or video is
+    disabled.
+
+``total-avsync-change``
+    Total A-V sync correction done. Unavailable if audio or video is
+    disabled.
+
+``decoder-frame-drop-count``
+    Video frames dropped by decoder, because video is too far behind audio (when
+    using ``--framedrop=decoder``). Sometimes, this may be incremented in other
+    situations, e.g. when video packets are damaged, or the decoder doesn't
+    follow the usual rules. Unavailable if video is disabled.
+
+``frame-drop-count``
+    Frames dropped by VO (when using ``--framedrop=vo``).
+
+``mistimed-frame-count``
+    Number of video frames that were not timed correctly in display-sync mode
+    for the sake of keeping A/V sync. This does not include external
+    circumstances, such as video rendering being too slow or the graphics
+    driver somehow skipping a vsync. It does not include rounding errors either
+    (which can happen especially with bad source timestamps). For example,
+    using the ``display-desync`` mode should never change this value from 0.
+
+``vsync-ratio``
+    For how many vsyncs a frame is displayed on average. This is available if
+    display-sync is active only. For 30 FPS video on a 60 Hz screen, this will
+    be 2. This is the moving average of what actually has been scheduled, so
+    24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on
+    the last frame displayed.
+
+``vo-delayed-frame-count``
+    Estimated number of frames delayed due to external circumstances in
+    display-sync mode. Note that in general, mpv has to guess that this is
+    happening, and the guess can be inaccurate.
+
+``percent-pos`` (RW)
+    Position in current file (0-100). The advantage over using this instead of
+    calculating it out of other properties is that it properly falls back to
+    estimating the playback position from the byte position, if the file
+    duration is not known.
+
+``time-pos`` (RW)
+    Position in current file in seconds.
+
+    This has a sub-property:
+
+    ``time-pos/full``
+        ``time-pos`` with milliseconds.
+
+``time-start``
+    Deprecated. Always returns 0. Before mpv 0.14, this used to return the start
+    time of the file (could affect e.g. transport streams). See
+    ``--rebase-start-time`` option.
+
+``time-remaining``
+    Remaining length of the file in seconds. Note that the file duration is not
+    always exactly known, so this is an estimate.
+
+    This has a sub-property:
+
+    ``time-remaining/full``
+        ``time-remaining`` with milliseconds.
+
+``audio-pts``
+    Current audio playback position in current file in seconds. Unlike time-pos,
+    this updates more often than once per frame. For audio-only files, it is
+    mostly equivalent to time-pos, while for video-only files this property is
+    not available.
+
+    This has a sub-property:
+
+    ``audio-pts/full``
+        ``audio-pts`` with milliseconds.
+
+``playtime-remaining``
+    ``time-remaining`` scaled by the current ``speed``.
+
+    This has a sub-property:
+
+    ``playtime-remaining/full``
+        ``playtime-remaining`` with milliseconds.
+
+``playback-time`` (RW)
+    Position in current file in seconds. Unlike ``time-pos``, the time is
+    clamped to the range of the file. (Inaccurate file durations etc. could
+    make it go out of range. Useful on attempts to seek outside of the file,
+    as the seek target time is considered the current position during seeking.)
+
+    This has a sub-property:
+
+    ``playback-time/full``
+        ``playback-time`` with milliseconds.
+
+``chapter`` (RW)
+    Current chapter number. The number of the first chapter is 0.
+
+``edition`` (RW)
+    Current MKV edition number. Setting this property to a different value will
+    restart playback. The number of the first edition is 0.
+
+    Before mpv 0.31.0, this showed the actual edition selected at runtime, if
+    you didn't set the option or property manually. With mpv 0.31.0 and later,
+    this strictly returns the user-set option or property value, and the
+    ``current-edition`` property was added to return the runtime selected
+    edition (this matters with ``--edition=auto``, the default).
+
+``current-edition``
+    Currently selected edition. This property is unavailable if no file is
+    loaded, or the file has no editions. (Matroska files make a difference
+    between having no editions and a single edition, which will be reflected by
+    the property, although in practice it does not matter.)
+
+``chapters``
+    Number of chapters.
+
+``editions``
+    Number of MKV editions.
+
+``edition-list``
+    List of editions, current entry marked. Currently, the raw property value
+    is useless.
+
+    This has a number of sub-properties. Replace ``N`` with the 0-based edition
+    index.
+
+    ``edition-list/count``
+        Number of editions. If there are no editions, this can be 0 or 1 (1
+        if there's a useless dummy edition).
+
+    ``edition-list/N/id`` (RW)
+        Edition ID as integer. Use this to set the ``edition`` property.
+        Currently, this is the same as the edition index.
+
+    ``edition-list/N/default``
+        Whether this is the default edition.
+
+    ``edition-list/N/title``
+        Edition title as stored in the file. Not always available.
+
+    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 (for each edition)
+                "id"                MPV_FORMAT_INT64
+                "title"             MPV_FORMAT_STRING
+                "default"           MPV_FORMAT_FLAG
+
+``metadata``
+    Metadata key/value pairs.
+
+    If the property is accessed with Lua's ``mp.get_property_native``, this
+    returns a table with metadata keys mapping to metadata values. If it is
+    accessed with the client API, this returns a ``MPV_FORMAT_NODE_MAP``,
+    with tag keys mapping to tag values.
+
+    For OSD, it returns a formatted list. Trying to retrieve this property as
+    a raw string doesn't work.
+
+    This has a number of sub-properties:
+
+    ``metadata/by-key/<key>``
+        Value of metadata entry ``<key>``.
+
+    ``metadata/list/count``
+        Number of metadata entries.
+
+    ``metadata/list/N/key``
+        Key name of the Nth metadata entry. (The first entry is ``0``).
+
+    ``metadata/list/N/value``
+        Value of the Nth metadata entry.
+
+    ``metadata/<key>``
+        Old version of ``metadata/by-key/<key>``. Use is discouraged, because
+        the metadata key string could conflict with other sub-properties.
+
+    The layout of this property might be subject to change. Suggestions are
+    welcome how exactly this property should work.
+
+    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_MAP
+            (key and string value for each metadata entry)
+
+``filtered-metadata``
+    Like ``metadata``, but includes only fields listed in the ``--display-tags``
+    option. This is the same set of tags that is printed to the terminal.
+
+``chapter-metadata``
+    Metadata of current chapter. Works similar to ``metadata`` property. It
+    also allows the same access methods (using sub-properties).
+
+    Per-chapter metadata is very rare. Usually, only the chapter name
+    (``title``) is set.
+
+    For accessing other information, like chapter start, see the
+    ``chapter-list`` property.
+
+``vf-metadata/<filter-label>``
+    Metadata added by video filters. Accessed by the filter label,
+    which, if not explicitly specified using the ``@filter-label:`` syntax,
+    will be ``<filter-name>NN``.
+
+    Works similar to ``metadata`` property. It allows the same access
+    methods (using sub-properties).
+
+    An example of this kind of metadata are the cropping parameters
+    added by ``--vf=lavfi=cropdetect``.
+
+``af-metadata/<filter-label>``
+    Equivalent to ``vf-metadata/<filter-label>``, but for audio filters.
+
+``idle-active``
+    Returns ``yes``/true if no file is loaded, but the player is staying around
+    because of the ``--idle`` option.
+
+    (Renamed from ``idle``.)
+
+``core-idle``
+    Whether the playback core is paused. This can differ from ``pause`` in
+    special situations, such as when the player pauses itself due to low
+    network cache.
+
+    This also returns ``yes``/true if playback is restarting or if nothing is
+    playing at all. In other words, it's only ``no``/false if there's actually
+    video playing. (Behavior since mpv 0.7.0.)
+
+``cache-speed``
+    Current I/O read speed between the cache and the lower layer (like network).
+    This gives the number bytes per seconds over a 1 second window (using
+    the type ``MPV_FORMAT_INT64`` for the client API).
+
+    This is the same as ``demuxer-cache-state/raw-input-rate``.
+
+``demuxer-cache-duration``
+    Approximate duration of video buffered in the demuxer, in seconds. The
+    guess is very unreliable, and often the property will not be available
+    at all, even if data is buffered.
+
+``demuxer-cache-time``
+    Approximate time of video buffered in the demuxer, in seconds. Same as
+    ``demuxer-cache-duration`` but returns the last timestamp of buffered
+    data in demuxer.
+
+``demuxer-cache-idle``
+    Whether the demuxer is idle, which means that the demuxer cache is filled
+    to the requested amount, and is currently not reading more data.
+
+``demuxer-cache-state``
+    Each entry in ``seekable-ranges`` represents a region in the demuxer cache
+    that can be seeked to, with a ``start`` and ``end`` fields containing the
+    respective timestamps. If there are multiple demuxers active, this only
+    returns information about the "main" demuxer, but might be changed in
+    future to return unified information about all demuxers. The ranges are in
+    arbitrary order. Often, ranges will overlap for a bit, before being joined.
+    In broken corner cases, ranges may overlap all over the place.
+
+    The end of a seek range is usually smaller than the value returned by the
+    ``demuxer-cache-time`` property, because that property returns the guessed
+    buffering amount, while the seek ranges represent the buffered data that
+    can actually be used for cached seeking.
+
+    ``bof-cached`` indicates whether the seek range with the lowest timestamp
+    points to the beginning of the stream (BOF). This implies you cannot seek
+    before this position at all. ``eof-cached`` indicates whether the seek range
+    with the highest timestamp points to the end of the stream (EOF). If both
+    ``bof-cached`` and ``eof-cached`` are true, and there's only 1 cache range,
+    the entire stream is cached.
+
+    ``fw-bytes`` is the number of bytes of packets buffered in the range
+    starting from the current decoding position. This is a rough estimate
+    (may not account correctly for various overhead), and stops at the
+    demuxer position (it ignores seek ranges after it).
+
+    ``file-cache-bytes`` is the number of bytes stored in the file cache. This
+    includes all overhead, and possibly unused data (like pruned data). This
+    member is missing if the file cache wasn't enabled with
+    ``--cache-on-disk=yes``.
+
+    ``cache-end`` is ``demuxer-cache-time``. Missing if unavailable.
+
+    ``reader-pts`` is the approximate timestamp of the start of the buffered
+    range. Missing if unavailable.
+
+    ``cache-duration`` is ``demuxer-cache-duration``. Missing if unavailable.
+
+    ``raw-input-rate`` is the estimated input rate of the network layer (or any
+    other byte-oriented input layer) in bytes per second. May be inaccurate or
+    missing.
+
+    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_MAP
+            "seekable-ranges"   MPV_FORMAT_NODE_ARRAY
+                MPV_FORMAT_NODE_MAP
+                    "start"             MPV_FORMAT_DOUBLE
+                    "end"               MPV_FORMAT_DOUBLE
+            "bof-cached"        MPV_FORMAT_FLAG
+            "eof-cached"        MPV_FORMAT_FLAG
+            "fw-bytes"          MPV_FORMAT_INT64
+            "file-cache-bytes"  MPV_FORMAT_INT64
+            "cache-end"         MPV_FORMAT_DOUBLE
+            "reader-pts"        MPV_FORMAT_DOUBLE
+            "cache-duration"    MPV_FORMAT_DOUBLE
+            "raw-input-rate"    MPV_FORMAT_INT64
+
+    Other fields (might be changed or removed in the future):
+
+    ``eof``
+        Whether the reader thread has hit the end of the file.
+
+    ``underrun``
+        Whether the reader thread could not satisfy a decoder's request for a
+        new packet.
+
+    ``idle``
+        Whether the thread is currently not reading.
+
+    ``total-bytes``
+        Sum of packet bytes (plus some overhead estimation) of the entire packet
+        queue, including cached seekable ranges.
+
+``demuxer-via-network``
+    Whether the stream demuxed via the main demuxer is most likely played via
+    network. What constitutes "network" is not always clear, might be used for
+    other types of untrusted streams, could be wrong in certain cases, and its
+    definition might be changing. Also, external files (like separate audio
+    files or streams) do not influence the value of this property (currently).
+
+``demuxer-start-time``
+    The start time reported by the demuxer in fractional seconds.
+
+``paused-for-cache``
+    Whether playback is paused because of waiting for the cache.
+
+``cache-buffering-state``
+    The percentage (0-100) of the cache fill status until the player will
+    unpause (related to ``paused-for-cache``).
+
+``eof-reached``
+    Whether the end of playback was reached. Note that this is usually
+    interesting only if ``--keep-open`` is enabled, since otherwise the player
+    will immediately play the next file (or exit or enter idle mode), and in
+    these cases the ``eof-reached`` property will logically be cleared
+    immediately after it's set.
+
+``seeking``
+    Whether the player is currently seeking, or otherwise trying to restart
+    playback. (It's possible that it returns ``yes``/true while a file is
+    loaded. This is because the same underlying code is used for seeking and
+    resyncing.)
+
+``mixer-active``
+    Whether the audio mixer is active.
+
+    This option is relatively useless. Before mpv 0.18.1, it could be used to
+    infer behavior of the ``volume`` property.
+
+``ao-volume`` (RW)
+    System volume. This property is available only if mpv audio output is
+    currently active, and only if the underlying implementation supports volume
+    control. What this option does depends on the API. For example, on ALSA
+    this usually changes system-wide audio, while with PulseAudio this controls
+    per-application volume.
+
+``ao-mute`` (RW)
+    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:
+
+    ``audio-params/format``
+        The sample format as string. This uses the same names as used in other
+        places of mpv.
+
+    ``audio-params/samplerate``
+        Samplerate.
+
+    ``audio-params/channels``
+        The channel layout as a string. This is similar to what the
+        ``--audio-channels`` accepts.
+
+    ``audio-params/hr-channels``
+        As ``channels``, but instead of the possibly cryptic actual layout
+        sent to the audio device, return a hopefully more human readable form.
+        (Usually only ``audio-out-params/hr-channels`` makes sense.)
+
+    ``audio-params/channel-count``
+        Number of audio channels. This is redundant to the ``channels`` field
+        described above.
+
+    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_MAP
+            "format"            MPV_FORMAT_STRING
+            "samplerate"        MPV_FORMAT_INT64
+            "channels"          MPV_FORMAT_STRING
+            "channel-count"     MPV_FORMAT_INT64
+            "hr-channels"       MPV_FORMAT_STRING
+
+``audio-out-params``
+    Same as ``audio-params``, but the format of the data written to the audio
+    API.
+
+``colormatrix``
+    Redirects to ``video-params/colormatrix``. This parameter (as well as
+    similar ones) can be overridden with the ``format`` video filter.
+
+``colormatrix-input-range``
+    See ``colormatrix``.
+
+``colormatrix-primaries``
+    See ``colormatrix``.
+
+``hwdec`` (RW)
+    Reflects the ``--hwdec`` option.
+
+    Writing to it may change the currently used hardware decoder, if possible.
+    (Internally, the player may reinitialize the decoder, and will perform a
+    seek to refresh the video properly.) You can watch the other hwdec
+    properties to see whether this was successful.
+
+    Unlike in mpv 0.9.x and before, this does not return the currently active
+    hardware decoder. Since mpv 0.18.0, ``hwdec-current`` is available for
+    this purpose.
+
+``hwdec-current``
+    The current hardware decoding in use. If decoding is active, return one of
+    the values used by the ``hwdec`` option/property. ``no``/false indicates
+    software decoding. If no decoder is loaded, the property is unavailable.
+
+``hwdec-interop``
+    This returns the currently loaded hardware decoding/output interop driver.
+    This is known only once the VO has opened (and possibly later). With some
+    VOs (like ``gpu``), this might be never known in advance, but only when
+    the decoder attempted to create the hw decoder successfully. (Using
+    ``--gpu-hwdec-interop`` can load it eagerly.) If there are multiple
+    drivers loaded, they will be separated by ``,``.
+
+    If no VO is active or no interop driver is known, this property is
+    unavailable.
+
+    This does not necessarily use the same values as ``hwdec``. There can be
+    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
+    size.
+
+``video-params``
+    Video parameters, as output by the decoder (with overrides like aspect
+    etc. applied). This has a number of sub-properties:
+
+    ``video-params/pixelformat``
+        The pixel format as string. This uses the same names as used in other
+        places of mpv.
+
+    ``video-params/hw-pixelformat``
+        The underlying pixel format as string. This is relevant for some cases
+        of hardware decoding and unavailable otherwise.
+
+    ``video-params/average-bpp``
+        Average bits-per-pixel as integer. Subsampled planar formats use a
+        different resolution, which is the reason this value can sometimes be
+        odd or confusing. Can be unavailable with some formats.
+
+    ``video-params/w``, ``video-params/h``
+        Video size as integers, with no aspect correction applied.
+
+    ``video-params/dw``, ``video-params/dh``
+        Video size as integers, scaled for correct aspect ratio.
+
+    ``video-params/crop-x``, ``video-params/crop-y``
+        Crop offset of the source video frame.
+
+    ``video-params/crop-w``, ``video-params/crop-h``
+        Video size after cropping.
+
+    ``video-params/aspect``
+        Display aspect ratio as float.
+
+    ``video-params/aspect-name``
+        Display aspect ratio name as string. The name coresponds to motion
+        picture film format that introduced given aspect ratio in film.
+
+    ``video-params/par``
+        Pixel aspect ratio.
+
+    ``video-params/sar``
+        Storage aspect ratio.
+
+    ``video-params/sar-name``
+        Storage aspect ratio name as string.
+
+    ``video-params/colormatrix``
+        The colormatrix in use as string. (Exact values subject to change.)
+
+    ``video-params/colorlevels``
+        The colorlevels as string. (Exact values subject to change.)
+
+    ``video-params/primaries``
+        The primaries in use as string. (Exact values subject to change.)
+
+    ``video-params/gamma``
+        The gamma function in use as string. (Exact values subject to change.)
+
+    ``video-params/sig-peak`` (deprecated)
+        The video file's tagged signal peak as float.
+
+    ``video-params/light``
+        The light type in use as a string. (Exact values subject to change.)
+
+    ``video-params/chroma-location``
+        Chroma location as string. (Exact values subject to change.)
+
+    ``video-params/rotate``
+        Intended display rotation in degrees (clockwise).
+
+    ``video-params/stereo-in``
+        Source file stereo 3D mode. (See the ``format`` video filter's
+        ``stereo-in`` option.)
+
+    ``video-params/alpha``
+        Alpha type. If the format has no alpha channel, this will be unavailable
+        (but in future releases, it could change to ``no``). If alpha is
+        present, this is set to ``straight`` or ``premul``.
+
+    ``video-params/min-luma``
+        Minimum luminance, as reported by HDR10 metadata (in cd/m²)
+
+    ``video-params/max-luma``
+        Maximum luminance, as reported by HDR10 metadata (in cd/m²)
+
+    ``video-params/max-cll``
+        Maximum content light level, as reported by HDR10 metadata (in cd/m²)
+
+    ``video-params/max-fall``
+        Maximum frame average light level, as reported by HDR10 metadata (in cd/m²)
+
+    ``video-params/scene-max-r``
+        MaxRGB of a scene for R component, as reported by HDR10+ metadata (in cd/m²)
+
+    ``video-params/scene-max-g``
+        MaxRGB of a scene for G component, as reported by HDR10+ metadata (in cd/m²)
+
+    ``video-params/scene-max-b``
+        MaxRGB of a scene for B component, as reported by HDR10+ metadata (in cd/m²)
+
+    ``video-params/max-pq-y``
+        Maximum PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)
+
+    ``video-params/avg-pq-y``
+        Average PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)
+
+    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_MAP
+            "pixelformat"       MPV_FORMAT_STRING
+            "hw-pixelformat"    MPV_FORMAT_STRING
+            "w"                 MPV_FORMAT_INT64
+            "h"                 MPV_FORMAT_INT64
+            "dw"                MPV_FORMAT_INT64
+            "dh"                MPV_FORMAT_INT64
+            "aspect"            MPV_FORMAT_DOUBLE
+            "par"               MPV_FORMAT_DOUBLE
+            "colormatrix"       MPV_FORMAT_STRING
+            "colorlevels"       MPV_FORMAT_STRING
+            "primaries"         MPV_FORMAT_STRING
+            "gamma"             MPV_FORMAT_STRING
+            "sig-peak"          MPV_FORMAT_DOUBLE
+            "light"             MPV_FORMAT_STRING
+            "chroma-location"   MPV_FORMAT_STRING
+            "rotate"            MPV_FORMAT_INT64
+            "stereo-in"         MPV_FORMAT_STRING
+            "average-bpp"       MPV_FORMAT_INT64
+            "alpha"             MPV_FORMAT_STRING
+            "min-luma"          MPV_FORMAT_DOUBLE
+            "max-luma"          MPV_FORMAT_DOUBLE
+            "max-cll"           MPV_FORMAT_DOUBLE
+            "max-fall"          MPV_FORMAT_DOUBLE
+            "scene-max-r"       MPV_FORMAT_DOUBLE
+            "scene-max-g"       MPV_FORMAT_DOUBLE
+            "scene-max-b"       MPV_FORMAT_DOUBLE
+            "max-pq-y"          MPV_FORMAT_DOUBLE
+            "avg-pq-y"          MPV_FORMAT_DOUBLE
+
+``dwidth``, ``dheight``
+    Video display size. This is the video size after filters and aspect scaling
+    have been applied. The actual video window size can still be different
+    from this, e.g. if the user resized the video window manually.
+
+    These have the same values as ``video-out-params/dw`` and
+    ``video-out-params/dh``.
+
+``video-dec-params``
+    Exactly like ``video-params``, but no overrides applied.
+
+``video-out-params``
+    Same as ``video-params``, but after video filters have been applied. If
+    there are no video filters in use, this will contain the same values as
+    ``video-params``. Note that this is still not necessarily what the video
+    window uses, since the user can change the window size, and all real VOs
+    do their own scaling independently from the filter chain.
+
+    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
+    redrawing and frame display being somewhat disconnected, and you might
+    have to pause and force a redraw.
+
+    This has a number of sub-properties:
+
+    ``video-frame-info/picture-type``
+        The type of the picture. It can be "I" (intra), "P" (predicted), "B"
+        (bi-dir predicted) or unavailable.
+
+    ``video-frame-info/interlaced``
+        Whether the content of the frame is interlaced.
+
+    ``video-frame-info/tff``
+        If the content is interlaced, whether the top field is displayed first.
+
+    ``video-frame-info/repeat``
+        Whether the frame must be delayed when decoding.
+
+``container-fps``
+    Container FPS. This can easily contain bogus values. For videos that use
+    modern container formats or video codecs, this will often be incorrect.
+
+    (Renamed from ``fps``.)
+
+``estimated-vf-fps``
+    Estimated/measured FPS of the video filter chain output. (If no filters
+    are used, this corresponds to decoder output.) This uses the average of
+    the 10 past frame durations to calculate the FPS. It will be inaccurate
+    if frame-dropping is involved (such as when framedrop is explicitly
+    enabled, or after precise seeking). Files with imprecise timestamps (such
+    as Matroska) might lead to unstable results.
+
+``window-scale`` (RW)
+    Window size multiplier. Setting this will resize the video window to the
+    values contained in ``dwidth`` and ``dheight`` multiplied with the value
+    set with this property. Setting ``1`` will resize to original video size
+    (or to be exact, the size the video filters output). ``2`` will set the
+    double size, ``0.5`` halves the size.
+
+    Note that setting a value identical to its previous value will not resize
+    the window. That's because this property mirrors the ``window-scale``
+    option, and setting an option to its previous value is ignored. If this
+    value is set while the window is in a fullscreen, the multiplier is not
+    applied until the window is taken out of that state. Writing this property
+    to a maximized window can unmaximize the window depending on the OS and
+    window manager. If the window does not unmaximize, the multiplier will be
+    applied if the user unmaximizes the window later.
+
+    See ``current-window-scale`` for the value derived from the actual window
+    size.
+
+    Since mpv 0.31.0, this always returns the previously set value (or the
+    default value), instead of the value implied by the actual window size.
+    Before mpv 0.31.0, this returned what ``current-window-scale`` returns now,
+    after the window was created.
+
+``current-window-scale`` (RW)
+    The ``window-scale`` value calculated from the current window size. This
+    has the same value as ``window-scale`` if the window size was not changed
+    since setting the option, and the window size was not restricted in other
+    ways. If the window is fullscreened, this will return the scale value
+    calculated from the last non-fullscreen size of the window. The property
+    is unavailable if no video is active.
+
+    When setting this property in the fullscreen or maximized state, the behavior
+    is the same as window-scale. In all other cases, setting the value of this
+    property will always resize the window. This does not affect the value of
+    ``window-scale``.
+
+``focused``
+    Whether the window has focus. Might not be supported by all VOs.
+
+``display-names``
+    Names of the displays that the mpv window covers. On X11, these
+    are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these
+    are the GDI names (\\.\DISPLAY1, \\.\DISPLAY2, etc.) and the first display
+    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.
+
+``display-fps``
+    The refresh rate of the current display. Currently, this is the lowest FPS
+    of any display covered by the video, as retrieved by the underlying system
+    APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily
+    available on all platforms. Note that any of the listed facts may change
+    any time without a warning.
+
+``estimated-display-fps``
+    The actual rate at which display refreshes seem to occur, measured by
+    system time. Only available if display-sync mode (as selected by
+    ``--video-sync``) is active.
+
+``vsync-jitter``
+    Estimated deviation factor of the vsync duration.
+
+``display-width``, ``display-height``
+    The current display's horizontal and vertical resolution in pixels. Whether
+    or not these values update as the mpv window changes displays depends on
+    the windowing backend. It may not be available on all platforms.
+
+``display-hidpi-scale``
+    The HiDPI scale factor as reported by the windowing backend. If no VO is
+    active, or if the VO does not report a value, this property is unavailable.
+    It may be saner to report an absolute DPI, however, this is the way HiDPI
+    support is implemented on most OS APIs. See also ``--hidpi-window-scale``.
+
+``osd-width``, ``osd-height``
+    Last known OSD width (can be 0). This is needed if you want to use the
+    ``overlay-add`` command. It gives you the actual OSD/window size (not
+    including decorations drawn by the OS window manager).
+
+    Alias to ``osd-dimensions/w`` and ``osd-dimensions/h``.
+
+``osd-par``
+    Last known OSD display pixel aspect (can be 0).
+
+    Alias to ``osd-dimensions/osd-par``.
+
+``osd-dimensions``
+    Last known OSD dimensions.
+
+    Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE``
+    or Lua table with ``mp.get_property_native``):
+
+    ``osd-dimensions/w``
+        Size of the VO window in OSD render units (usually pixels, but may be
+        scaled pixels with VOs like ``xv``).
+
+    ``osd-dimensions/h``
+        Size of the VO window in OSD render units,
+
+    ``osd-dimensions/par``
+        Pixel aspect ratio of the OSD (usually 1).
+
+    ``osd-dimensions/aspect``
+        Display aspect ratio of the VO window. (Computing from the properties
+        above.)
+
+    ``osd-dimensions/mt``, ``osd-dimensions/mb``, ``osd-dimensions/ml``, ``osd-dimensions/mr``
+        OSD to video margins (top, bottom, left, right). This describes the
+        area into which the video is rendered.
+
+    Any of these properties may be unavailable or set to dummy values if the
+    VO window is not created or visible.
+
+``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.
+
+``mouse-pos``
+    Read-only - last known mouse position, normalizd to OSD dimensions.
+
+    Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE``
+    or Lua table with ``mp.get_property_native``):
+
+    ``mouse-pos/x``, ``mouse-pos/y``
+        Last known coordinates of the mouse pointer.
+
+    ``mouse-pos/hover``
+        Boolean - whether the mouse pointer hovers the video window. The
+        coordinates should be ignored when this value is false, because the
+        video backends update them only when the pointer hovers the window.
+
+``sub-ass-extradata``
+    The current ASS subtitle track's extradata. There is no formatting done.
+    The extradata is returned as a string as-is. This property is not
+    available for non-ASS subtitle tracks.
+
+``sub-text``
+    The current subtitle text regardless of sub visibility. Formatting is
+    stripped. If the subtitle is not text-based (i.e. DVD/BD subtitles), an
+    empty string is returned.
+
+``sub-text-ass``
+    Like ``sub-text``, but return the text in ASS format. Text subtitles in
+    other formats are converted. For native ASS subtitles, events that do
+    not contain any text (but vector drawings etc.) are not filtered out. If
+    multiple events match with the current playback time, they are concatenated
+    with line breaks. Contains only the "Text" part of the events.
+
+    This property is not enough to render ASS subtitles correctly, because ASS
+    header and per-event metadata are not returned. You likely need to do
+    further filtering on the returned string to make it useful.
+
+``secondary-sub-text``
+    Same as ``sub-text``, but for the secondary subtitles.
+
+``sub-start``
+    The current subtitle start time (in seconds). If there's multiple current
+    subtitles, returns the first start time. If no current subtitle is present
+    null is returned instead.
+
+``secondary-sub-start``
+    Same as ``sub-start``, but for the secondary subtitles.
+
+``sub-end``
+    The current subtitle end time (in seconds). If there's multiple current
+    subtitles, return the last end time. If no current subtitle is present, or
+    if it's present but has unknown or incorrect duration, null is returned
+    instead.
+
+``secondary-sub-end``
+    Same as ``sub-end``, but for the secondary subtitles.
+
+``playlist-pos`` (RW)
+    Current position on playlist. The first entry is on position 0. Writing to
+    this property may start playback at the new position.
+
+    In some cases, this is not necessarily the currently playing file. See
+    explanation of ``current`` and ``playing`` flags in ``playlist``.
+
+    If there the playlist is empty, or if it's non-empty, but no entry is
+    "current", this property returns -1. Likewise, writing -1 will put the
+    player into idle mode (or exit playback if idle mode is not enabled). If an
+    out of range index is written to the property, this behaves as if writing -1.
+    (Before mpv 0.33.0, instead of returning -1, this property was unavailable
+    if no playlist entry was current.)
+
+    Writing the current value back to the property will have no effect.
+    Use ``playlist-play-index`` to restart the playback of the current entry if
+    desired.
+
+``playlist-pos-1`` (RW)
+    Same as ``playlist-pos``, but 1-based.
+
+``playlist-current-pos`` (RW)
+    Index of the "current" item on playlist. This usually, but not necessarily,
+    the currently playing item (see ``playlist-playing-pos``). Depending on the
+    exact internal state of the player, it may refer to the playlist item to
+    play next, or the playlist item used to determine what to play next.
+
+    For reading, this is exactly the same as ``playlist-pos``.
+
+    For writing, this *only* sets the position of the "current" item, without
+    stopping playback of the current file (or starting playback, if this is done
+    in idle mode). Use -1 to remove the current flag.
+
+    This property is only vaguely useful. If set during playback, it will
+    typically cause the playlist entry *after* it to be played next. Another
+    possibly odd observable state is that if ``playlist-next`` is run during
+    playback, this property is set to the playlist entry to play next (unlike
+    the previous case). There is an internal flag that decides whether the
+    current playlist entry or the next one should be played, and this flag is
+    currently inaccessible for API users. (Whether this behavior will kept is
+    possibly subject to change.)
+
+``playlist-playing-pos``
+    Index of the "playing" item on playlist. A playlist item is "playing" if
+    it's being loaded, actually playing, or being unloaded. This property is set
+    during the ``MPV_EVENT_START_FILE`` (``start-file``) and the
+    ``MPV_EVENT_START_END`` (``end-file``) events. Outside of that, it returns
+    -1. If the playlist entry was somehow removed during playback, but playback
+    hasn't stopped yet, or is in progress of being stopped, it also returns -1.
+    (This can happen at least during state transitions.)
+
+    In the "playing" state, this is usually the same as ``playlist-pos``, except
+    during state changes, or if ``playlist-current-pos`` was written explicitly.
+
+``playlist-count``
+    Number of total playlist entries.
+
+``playlist-path``
+    The original path of the playlist for the current entry before mpv expanded
+    the entries. Unavailable if the file was not originally associated with a
+    playlist in some way.
+
+``playlist``
+    Playlist, current entry marked. Currently, the raw property value is
+    useless.
+
+    This has a number of sub-properties. Replace ``N`` with the 0-based playlist
+    entry index.
+
+    ``playlist/count``
+        Number of playlist entries (same as ``playlist-count``).
+
+    ``playlist/N/filename``
+        Filename of the Nth entry.
+
+    ``playlist/N/playing``
+        ``yes``/true if the ``playlist-playing-pos`` property points to this
+        entry, ``no``/false or unavailable otherwise.
+
+    ``playlist/N/current``
+        ``yes``/true if the ``playlist-current-pos`` property points to this
+        entry, ``no``/false or unavailable otherwise.
+
+    ``playlist/N/title``
+        Name of the Nth entry. Available if the playlist file contains
+        such fields and mpv's parser supports it for the given
+        playlist format, or if the playlist entry has been opened before and a
+        media-title other then then filename has been acquired.
+
+    ``playlist/N/id``
+        Unique ID for this entry. This is an automatically assigned integer ID
+        that is unique for the entire life time of the current mpv core
+        instance. Other commands, events, etc. use this as ``playlist_entry_id``
+        fields.
+
+    ``playlist/N/playlist-path``
+        The original path of the playlist for this entry before mpv expanded
+        it. Unavailable if the file was not originally associated with a playlist
+        in some way.
+
+    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 (for each playlist entry)
+                "filename"  MPV_FORMAT_STRING
+                "current"   MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
+                "playing"   MPV_FORMAT_FLAG (same)
+                "title"     MPV_FORMAT_STRING (optional)
+                "id"        MPV_FORMAT_INT64
+
+``track-list``
+    List of audio/video/sub tracks, current entry marked. Currently, the raw
+    property value is useless.
+
+    This has a number of sub-properties. Replace ``N`` with the 0-based track
+    index.
+
+    ``track-list/count``
+        Total number of tracks.
+
+    ``track-list/N/id``
+        The ID as it's used for ``-sid``/``--aid``/``--vid``. This is unique
+        within tracks of the same type (sub/audio/video), but otherwise not.
+
+    ``track-list/N/type``
+        String describing the media type. One of ``audio``, ``video``, ``sub``.
+
+    ``track-list/N/src-id``
+        Track ID as used in the source file. Not always available. (It is
+        missing if the format has no native ID, if the track is a pseudo-track
+        that does not exist in this way in the actual file, or if the format
+        is handled by libavformat, and the format was not whitelisted as having
+        track IDs.)
+
+    ``track-list/N/title``
+        Track title as it is stored in the file. Not always available.
+
+    ``track-list/N/lang``
+        Track language as identified by the file. Not always available.
+
+    ``track-list/N/image``
+        ``yes``/true if this is a video track that consists of a single
+        picture, ``no``/false or unavailable otherwise. The heuristic used to
+        determine if a stream is an image doesn't attempt to detect images in
+        codecs normally used for videos. Otherwise, it is reliable.
+
+    ``track-list/N/albumart``
+        ``yes``/true if this is an image embedded in an audio file or external
+        cover art, ``no``/false or unavailable otherwise.
+
+    ``track-list/N/default``
+        ``yes``/true if the track has the default flag set in the file,
+        ``no``/false or unavailable otherwise.
+
+    ``track-list/N/forced``
+        ``yes``/true if the track has the forced flag set in the file,
+        ``no``/false or unavailable otherwise.
+
+    ``track-list/N/codec``
+        The codec name used by this track, for example ``h264``. Unavailable
+        in some rare cases.
+
+    ``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.
+
+    ``track-list/N/external-filename``
+        The filename if the track is from an external file, unavailable
+        otherwise.
+
+    ``track-list/N/selected``
+        ``yes``/true if the track is currently decoded, ``no``/false or
+        unavailable otherwise.
+
+    ``track-list/N/main-selection``
+        It indicates the selection order of tracks for the same type.
+        If a track is not selected, or is selected by the ``--lavfi-complex``,
+        it is not available. For subtitle tracks, ``0`` represents the ``sid``,
+        and ``1`` represents the ``secondary-sid``.
+
+    ``track-list/N/ff-index``
+        The stream index as usually used by the FFmpeg utilities. Note that
+        this can be potentially wrong if a demuxer other than libavformat
+        (``--demuxer=lavf``) is used. For mkv files, the index will usually
+        match even if the default (builtin) demuxer is used, but there is
+        no hard guarantee.
+
+    ``track-list/N/decoder-desc``
+        If this track is being decoded, the human-readable decoder name,
+
+    ``track-list/N/demux-w``, ``track-list/N/demux-h``
+        Video size hint as indicated by the container. (Not always accurate.)
+
+    ``track-list/N/demux-crop-x``, ``track-list/N/demux-crop-y``
+        Crop offset of the source video frame.
+
+    ``track-list/N/demux-crop-w``, ``track-list/N/demux-crop-h``
+        Video size after cropping.
+
+    ``track-list/N/demux-channel-count``
+        Number of audio channels as indicated by the container. (Not always
+        accurate - in particular, the track could be decoded as a different
+        number of channels.)
+
+    ``track-list/N/demux-channels``
+        Channel layout as indicated by the container. (Not always accurate.)
+
+    ``track-list/N/demux-samplerate``
+        Audio sample rate as indicated by the container. (Not always accurate.)
+
+    ``track-list/N/demux-fps``
+        Video FPS as indicated by the container. (Not always accurate.)
+
+    ``track-list/N/demux-bitrate``
+        Audio average bitrate, in bits per second. (Not always accurate.)
+
+    ``track-list/N/demux-rotation``
+        Video clockwise rotation metadata, in degrees.
+
+    ``track-list/N/demux-par``
+        Pixel aspect ratio.
+
+    ``track-list/N/audio-channels`` (deprecated)
+        Deprecated alias for ``track-list/N/demux-channel-count``.
+
+    ``track-list/N/replaygain-track-peak``, ``track-list/N/replaygain-track-gain``
+        Per-track replaygain values. Only available for audio tracks with
+        corresponding information stored in the source file.
+
+    ``track-list/N/replaygain-album-peak``, ``track-list/N/replaygain-album-gain``
+        Per-album replaygain values. If the file has per-track but no per-album
+        information, the per-album values will be copied from the per-track
+        values currently. It's possible that future mpv versions will make
+        these properties unavailable instead in this case.
+
+    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 (for each track)
+                "id"                MPV_FORMAT_INT64
+                "type"              MPV_FORMAT_STRING
+                "src-id"            MPV_FORMAT_INT64
+                "title"             MPV_FORMAT_STRING
+                "lang"              MPV_FORMAT_STRING
+                "image"             MPV_FORMAT_FLAG
+                "albumart"          MPV_FORMAT_FLAG
+                "default"           MPV_FORMAT_FLAG
+                "forced"            MPV_FORMAT_FLAG
+                "selected"          MPV_FORMAT_FLAG
+                "main-selection"    MPV_FORMAT_INT64
+                "external"          MPV_FORMAT_FLAG
+                "external-filename" MPV_FORMAT_STRING
+                "codec"             MPV_FORMAT_STRING
+                "ff-index"          MPV_FORMAT_INT64
+                "decoder-desc"      MPV_FORMAT_STRING
+                "demux-w"           MPV_FORMAT_INT64
+                "demux-h"           MPV_FORMAT_INT64
+                "demux-crop-x"      MPV_FORMAT_INT64
+                "demux-crop-y"      MPV_FORMAT_INT64
+                "demux-crop-w"      MPV_FORMAT_INT64
+                "demux-crop-h"      MPV_FORMAT_INT64
+                "demux-channel-count" MPV_FORMAT_INT64
+                "demux-channels"    MPV_FORMAT_STRING
+                "demux-samplerate"  MPV_FORMAT_INT64
+                "demux-fps"         MPV_FORMAT_DOUBLE
+                "demux-bitrate"     MPV_FORMAT_INT64
+                "demux-rotation"    MPV_FORMAT_INT64
+                "demux-par"         MPV_FORMAT_DOUBLE
+                "audio-channels"    MPV_FORMAT_INT64
+                "replaygain-track-peak" MPV_FORMAT_DOUBLE
+                "replaygain-track-gain" MPV_FORMAT_DOUBLE
+                "replaygain-album-peak" MPV_FORMAT_DOUBLE
+                "replaygain-album-gain" MPV_FORMAT_DOUBLE
+
+``current-tracks/...``
+    This gives access to currently selected tracks. It redirects to the correct
+    entry in ``track-list``.
+
+    The following sub-entries are defined: ``video``, ``audio``, ``sub``,
+    ``sub2``
+
+    For example, ``current-tracks/audio/lang`` returns the current audio track's
+    language field (the same value as ``track-list/N/lang``).
+
+    If tracks of the requested type are selected via ``--lavfi-complex``, the
+    first one is returned.
+
+``chapter-list`` (RW)
+    List of chapters, current entry marked. Currently, the raw property value
+    is useless.
+
+    This has a number of sub-properties. Replace ``N`` with the 0-based chapter
+    index.
+
+    ``chapter-list/count``
+        Number of chapters.
+
+    ``chapter-list/N/title``
+        Chapter title as stored in the file. Not always available.
+
+    ``chapter-list/N/time``
+        Chapter start time in seconds as float.
+
+    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 (for each chapter)
+                "title" MPV_FORMAT_STRING
+                "time"  MPV_FORMAT_DOUBLE
+
+``af``, ``vf`` (RW)
+    See ``--vf``/``--af`` and the ``vf``/``af`` command.
+
+    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 (for each filter entry)
+                "name"      MPV_FORMAT_STRING
+                "label"     MPV_FORMAT_STRING [optional]
+                "enabled"   MPV_FORMAT_FLAG [optional]
+                "params"    MPV_FORMAT_NODE_MAP [optional]
+                    "key"   MPV_FORMAT_STRING
+                    "value" MPV_FORMAT_STRING
+
+    It's also possible to write the property using this format.
+
+``seekable``
+    Whether it's generally possible to seek in the current file.
+
+``partially-seekable``
+    Whether the current file is considered seekable, but only because the cache
+    is active. This means small relative seeks may be fine, but larger seeks
+    may fail anyway. Whether a seek will succeed or not is generally not known
+    in advance.
+
+    If this property returns ``yes``/true, so will ``seekable``.
+
+``playback-abort``
+    Whether playback is stopped or is to be stopped. (Useful in obscure
+    situations like during ``on_load`` hook processing, when the user can stop
+    playback, but the script has to explicitly end processing.)
+
+``cursor-autohide`` (RW)
+    See ``--cursor-autohide``. Setting this to a new value will always update
+    the cursor, and reset the internal timer.
+
+``osd-sym-cc``
+    Inserts the current OSD symbol as opaque OSD control code (cc). This makes
+    sense only with the ``show-text`` command or options which set OSD messages.
+    The control code is implementation specific and is useless for anything else.
+
+``osd-ass-cc``
+    ``${osd-ass-cc/0}`` disables escaping ASS sequences of text in OSD,
+    ``${osd-ass-cc/1}`` enables it again. By default, ASS sequences are
+    escaped to avoid accidental formatting, and this property can disable
+    this behavior. Note that the properties return an opaque OSD control
+    code, which only makes sense for the ``show-text`` command or options
+    which set OSD messages.
+
+    .. admonition:: Example
+
+        - ``--osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'``
+        - ``show-text "This is ${osd-ass-cc/0}{\\b1}bold text"``
+
+    Any ASS override tags as understood by libass can be used.
+
+    Note that you need to escape the ``\`` character, because the string is
+    processed for C escape sequences before passing it to the OSD code. See
+    `Flat command syntax`_ for details.
+
+    A list of tags can be found here:
+    https://aegisub.org/docs/latest/ass_tags/
+
+``vo-configured``
+    Whether the VO is configured right now. Usually this corresponds to whether
+    the video window is visible. If the ``--force-window`` option is used, this
+    usually always returns ``yes``/true.
+
+``vo-passes``
+    Contains introspection about the VO's active render passes and their
+    execution times. Not implemented by all VOs.
+
+    This is further subdivided into two frame types, ``vo-passes/fresh`` for
+    fresh frames (which have to be uploaded, scaled, etc.) and
+    ``vo-passes/redraw`` for redrawn frames (which only have to be re-painted).
+    The number of passes for any given subtype can change from frame to frame,
+    and should not be relied upon.
+
+    Each frame type has a number of further sub-properties. Replace ``TYPE``
+    with the frame type, ``N`` with the 0-based pass index, and ``M`` with the
+    0-based sample index.
+
+    ``vo-passes/TYPE/count``
+        Number of passes.
+
+    ``vo-passes/TYPE/N/desc``
+        Human-friendy description of the pass.
+
+    ``vo-passes/TYPE/N/last``
+        Last measured execution time, in nanoseconds.
+
+    ``vo-passes/TYPE/N/avg``
+        Average execution time of this pass, in nanoseconds. The exact
+        timeframe varies, but it should generally be a handful of seconds.
+
+    ``vo-passes/TYPE/N/peak``
+        The peak execution time (highest value) within this averaging range, in
+        nanoseconds.
+
+    ``vo-passes/TYPE/N/count``
+        The number of samples for this pass.
+
+    ``vo-passes/TYPE/N/samples/M``
+        The raw execution time of a specific sample for this pass, in
+        nanoseconds.
+
+    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_MAP
+        "TYPE" MPV_FORMAT_NODE_ARRAY
+            MPV_FORMAT_NODE_MAP
+                "desc"    MPV_FORMAT_STRING
+                "last"    MPV_FORMAT_INT64
+                "avg"     MPV_FORMAT_INT64
+                "peak"    MPV_FORMAT_INT64
+                "count"   MPV_FORMAT_INT64
+                "samples" MPV_FORMAT_NODE_ARRAY
+                     MP_FORMAT_INT64
+
+    Note that directly accessing this structure via subkeys is not supported,
+    the only access is through aforementioned ``MPV_FORMAT_NODE``.
+
+``perf-info``
+    Further performance data. Querying this property triggers internal
+    collection of some data, and may slow down the player. Each query will reset
+    some internal state. Property change notification doesn't and won't work.
+    All of this may change in the future, so don't use this. The builtin
+    ``stats`` script is supposed to be the only user; since it's bundled and
+    built with the source code, it can use knowledge of mpv internal to render
+    the information properly. See ``stats`` script description for some details.
+
+``video-bitrate``, ``audio-bitrate``, ``sub-bitrate``
+    Bitrate values calculated on the packet level. This works by dividing the
+    bit size of all packets between two keyframes by their presentation
+    timestamp distance. (This uses the timestamps are stored in the file, so
+    e.g. playback speed does not influence the returned values.) In particular,
+    the video bitrate will update only per keyframe, and show the "past"
+    bitrate. To make the property more UI friendly, updates to these properties
+    are throttled in a certain way.
+
+    The unit is bits per second. OSD formatting turns these values in kilobits
+    (or megabits, if appropriate), which can be prevented by using the
+    raw property value, e.g. with ``${=video-bitrate}``.
+
+    Note that the accuracy of these properties is influenced by a few factors.
+    If the underlying demuxer rewrites the packets on demuxing (done for some
+    file formats), the bitrate might be slightly off. If timestamps are bad
+    or jittery (like in Matroska), even constant bitrate streams might show
+    fluctuating bitrate.
+
+    How exactly these values are calculated might change in the future.
+
+    In earlier versions of mpv, these properties returned a static (but bad)
+    guess using a completely different method.
+
+``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate``
+    Old and deprecated properties for ``video-bitrate``, ``audio-bitrate``,
+    ``sub-bitrate``. They behave exactly the same, but return a value in
+    kilobits. Also, they don't have any OSD formatting, though the same can be
+    achieved with e.g. ``${=video-bitrate}``.
+
+    These properties shouldn't be used anymore.
+
+``audio-device-list``
+    The list of discovered audio devices. This is mostly for use with the
+    client API, and reflects what ``--audio-device=help`` with the command line
+    player returns.
+
+    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 (for each device entry)
+                "name"          MPV_FORMAT_STRING
+                "description"   MPV_FORMAT_STRING
+
+    The ``name`` is what is to be passed to the ``--audio-device`` option (and
+    often a rather cryptic audio API-specific ID), while ``description`` is
+    human readable free form text. The description is set to the device name
+    (minus mpv-specific ``<driver>/`` prefix) if no description is available
+    or the description would have been an empty string.
+
+    The special entry with the name set to ``auto`` selects the default audio
+    output driver and the default device.
+
+    The property can be watched with the property observation mechanism in
+    the client API and in Lua scripts. (Technically, change notification is
+    enabled the first time this property is read.)
+
+``audio-device`` (RW)
+    Set the audio device. This directly reads/writes the ``--audio-device``
+    option, but on write accesses, the audio output will be scheduled for
+    reloading.
+
+    Writing this property while no audio output is active will not automatically
+    enable audio. (This is also true in the case when audio was disabled due to
+    reinitialization failure after a previous write access to ``audio-device``.)
+
+    This property also doesn't tell you which audio device is actually in use.
+
+    How these details are handled may change in the future.
+
+``current-vo``
+    Current video output driver (name as used with ``--vo``).
+
+``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.
+
+    The top-level object itself cannot be written directly; write to sub-paths instead.
+
+    Converting this property or its sub-properties to strings will give a JSON
+    representation. If converting a leaf-level object (i.e. not a map or array)
+    and not using raw mode, the underlying content will be given (e.g. strings will be
+    printed directly, rather than quoted and JSON-escaped).
+
+``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.
+
+``protocol-list``
+    List of protocol prefixes potentially recognized by the player. They are
+    returned without trailing ``://`` suffix (which is still always required).
+    In some cases, the protocol will not actually be supported (consider
+    ``https`` if ffmpeg is not compiled with TLS support).
+
+``decoder-list``
+    List of decoders supported. This lists decoders which can be passed to
+    ``--vd`` and ``--ad``.
+
+    ``codec``
+        Canonical codec name, which identifies the format the decoder can
+        handle.
+
+    ``driver``
+        The name of the decoder itself. Often, this is the same as ``codec``.
+        Sometimes it can be different. It is used to distinguish multiple
+        decoders for the same codec.
+
+    ``description``
+        Human readable description of the decoder and codec.
+
+    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 (for each decoder entry)
+                "codec"         MPV_FORMAT_STRING
+                "driver"        MPV_FORMAT_STRING
+                "description"   MPV_FORMAT_STRING
+
+``encoder-list``
+    List of libavcodec encoders. This has the same format as ``decoder-list``.
+    The encoder names (``driver`` entries) can be passed to ``--ovc`` and
+    ``--oac`` (without the ``lavc:`` prefix required by ``--vd`` and ``--ad``).
+
+``demuxer-lavf-list``
+    List of available libavformat demuxers' names. This can be used to check
+    for support for a specific format or use with ``--demuxer-lavf-format``.
+
+``input-key-list``
+    List of `Key names`_, same as output by ``--input-keylist``.
+
+``mpv-version``
+    The mpv version/copyright string. Depending on how the binary was built, it
+    might contain either a release version, or just a git hash.
+
+``mpv-configuration``
+    The configuration arguments that were passed to the build system. If the
+    meson version used to compile mpv is older than 1.1.0, then a hardcoded
+    string of a few, arbitrary options is displayed instead.
+
+``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.
+
+``libass-version``
+    The value of ``ass_library_version()``. This is an integer, encoded in a
+    somewhat weird form (apparently "hex BCD"), indicating the release version
+    of the libass library linked to mpv.
+
+``platform``
+    Returns a string describing what target platform mpv was built for. The value
+    of this is dependent on what the underlying build system detects. Some of the
+    most common values are: ``windows``, ``darwin`` (macos or ios), ``linux``,
+    ``android``, and ``freebsd``. Note that this is not a complete listing.
+
+``options/<name>`` (RW)
+    The value of option ``--<name>``. Most options can be changed at runtime by
+    writing to this property. Note that many options require reloading the file
+    for changes to take effect. If there is an equivalent property, prefer
+    setting the property instead.
+
+    There shouldn't be any reason to access ``options/<name>`` instead of
+    ``<name>``, except in situations in which the properties have different
+    behavior or conflicting semantics.
+
+``file-local-options/<name>`` (RW)
+    Similar to ``options/<name>``, but when setting an option through this
+    property, the option is reset to its old value once the current file has
+    stopped playing. Trying to write an option while no file is playing (or
+    is being loaded) results in an error.
+
+    (Note that if an option is marked as file-local, even ``options/`` will
+    access the local value, and the ``old`` value, which will be restored on
+    end of playback, cannot be read or written until end of playback.)
+
+``option-info/<name>``
+    Additional per-option information.
+
+    This has a number of sub-properties. Replace ``<name>`` with the name of
+    a top-level option. No guarantee of stability is given to any of these
+    sub-properties - they may change radically in the feature.
+
+    ``option-info/<name>/name``
+        The name of the option.
+
+    ``option-info/<name>/type``
+        The name of the option type, like ``String`` or ``Integer``. For many
+        complex types, this isn't very accurate.
+
+    ``option-info/<name>/set-from-commandline``
+        Whether the option was set from the mpv command line. What this is set
+        to if the option is e.g. changed at runtime is left undefined (meaning
+        it could change in the future).
+
+    ``option-info/<name>/set-locally``
+        Whether the option was set per-file. This is the case with
+        automatically loaded profiles, file-dir configs, and other cases. It
+        means the option value will be restored to the value before playback
+        start when playback ends.
+
+    ``option-info/<name>/default-value``
+        The default value of the option. May not always be available.
+
+    ``option-info/<name>/min``, ``option-info/<name>/max``
+        Integer minimum and maximum values allowed for the option. Only
+        available if the options are numeric, and the minimum/maximum has been
+        set internally. It's also possible that only one of these is set.
+
+    ``option-info/<name>/choices``
+        If the option is a choice option, the possible choices. Choices that
+        are integers may or may not be included (they can be implied by ``min``
+        and ``max``). Note that options which behave like choice options, but
+        are not actual choice options internally, may not have this info
+        available.
+
+``property-list``
+    The list of top-level properties.
+
+``profile-list``
+    The list of profiles and their contents. This is highly
+    implementation-specific, and may change any time. Currently, it returns an
+    array of options for each profile. Each option has a name and a value, with
+    the value currently always being a string. Note that the options array is
+    not a map, as order matters and duplicate entries are possible. Recursive
+    profiles are not expanded, and show up as special ``profile`` options.
+
+    The ``profile-restore`` field is currently missing if it holds the default
+    value (either because it was not set, or set explicitly to ``default``),
+    but in the future it might hold the value ``default``.
+
+``command-list``
+    The list of input commands. This returns an array of maps, where each map
+    node represents a command. This map currently only has a single entry:
+    ``name`` for the name of the command. (This property is supposed to be a
+    replacement for ``--input-cmdlist``. The option dumps some more
+    information, but it's a valid feature request to extend this property if
+    needed.)
+
+``input-bindings``
+    The list of current input key bindings. This returns an array of maps,
+    where each map node represents a binding for a single key/command. This map
+    has the following entries:
+
+    ``key``
+        The key name. This is normalized and may look slightly different from
+        how it was specified in the source (e.g. in input.conf).
+
+    ``cmd``
+        The command mapped to the key. (Currently, this is exactly the same
+        string as specified in the source, other than stripping whitespace and
+        comments. It's possible that it will be normalized in the future.)
+
+    ``is_weak``
+        If set to true, any existing and active user bindings will take priority.
+
+    ``owner``
+        If this entry exists, the name of the script (or similar) which added
+        this binding.
+
+    ``section``
+        Name of the section this binding is part of. This is a rarely used
+        mechanism. This entry may be removed or change meaning in the future.
+
+    ``priority``
+        A number. Bindings with a higher value are preferred over bindings
+        with a lower value. If the value is negative, this binding is inactive
+        and will not be triggered by input. Note that mpv does not use this
+        value internally, and matching of bindings may work slightly differently
+        in some cases. In addition, this value is dynamic and can change around
+        at runtime.
+
+    ``comment``
+        If available, the comment following the command on the same line. (For
+        example, the input.conf entry ``f cycle bla # toggle bla`` would
+        result in an entry with ``comment = "toggle bla", cmd = "cycle bla"``.)
+
+    This property is read-only, and change notification is not supported.
+    Currently, there is no mechanism to change key bindings at runtime, other
+    than scripts adding or removing their own bindings.
+
+Inconsistencies between options and properties
+----------------------------------------------
+
+You can access (almost) all options as properties, though there are some
+caveats with some properties (due to historical reasons):
+
+``vid``, ``aid``, ``sid``
+    While playback is active, these return the actually active tracks. For
+    example, if you set ``aid=5``, and the currently played file contains no
+    audio track with ID 5, the ``aid`` property will return ``no``.
+
+    Before mpv 0.31.0, you could set existing tracks at runtime only.
+
+``display-fps``
+    This inconsistent behavior is deprecated. Post-deprecation, the reported
+    value and the option value are cleanly separated (``override-display-fps``
+    for the option value).
+
+``vf``, ``af``
+    If you set the properties during playback, and the filter chain fails to
+    reinitialize, the option will be set, but the runtime filter chain does not
+    change. On the other hand, the next video to be played will fail, because
+    the initial filter chain cannot be created.
+
+    This behavior changed in mpv 0.31.0. Before this, the new value was rejected
+    *iff* a video (for ``vf``) or an audio (for ``af``) track was active. If
+    playback was not active, the behavior was the same as the current one.
+
+``playlist``
+    The property is read-only and returns the current internal playlist. The
+    option is for loading playlist during command line parsing. For client API
+    uses, you should use the ``loadlist`` command instead.
+
+``profile``, ``include``
+    These are write-only, and will perform actions as they are written to,
+    exactly as if they were used on the mpv CLI commandline. Their only use is
+    when using libmpv before ``mpv_initialize()``, which in turn is probably
+    only useful in encoding mode. Normal libmpv users should use other
+    mechanisms, such as the ``apply-profile`` command, and the
+    ``mpv_load_config_file`` API function. Avoid these properties.
+
+Property Expansion
+------------------
+
+All string arguments to input commands as well as certain options (like
+``--term-playing-msg``) are subject to property expansion. Note that property
+expansion does not work in places where e.g. numeric parameters are expected.
+(For example, the ``add`` command does not do property expansion. The ``set``
+command is an exception and not a general rule.)
+
+.. admonition:: Example for input.conf
+
+    ``i show-text "Filename: ${filename}"``
+        shows the filename of the current file when pressing the ``i`` key
+
+Whether property expansion is enabled by default depends on which API is used
+(see `Flat command syntax`_, `Commands specified as arrays`_ and `Named
+arguments`_), but it can always be enabled with the ``expand-properties``
+prefix or disabled with the ``raw`` prefix, as described in `Input Command
+Prefixes`_.
+
+The following expansions are supported:
+
+``${NAME}``
+    Expands to the value of the property ``NAME``. If retrieving the property
+    fails, expand to an error string. (Use ``${NAME:}`` with a trailing
+    ``:`` to expand to an empty string instead.)
+    If ``NAME`` is prefixed with ``=``, expand to the raw value of the property
+    (see section below).
+``${NAME:STR}``
+    Expands to the value of the property ``NAME``, or ``STR`` if the
+    property cannot be retrieved. ``STR`` is expanded recursively.
+``${?NAME:STR}``
+    Expands to ``STR`` (recursively) if the property ``NAME`` is available.
+``${!NAME:STR}``
+    Expands to ``STR`` (recursively) if the property ``NAME`` cannot be
+    retrieved.
+``${?NAME==VALUE:STR}``
+    Expands to ``STR`` (recursively) if the property ``NAME`` expands to a
+    string equal to ``VALUE``. You can prefix ``NAME`` with ``=`` in order to
+    compare the raw value of a property (see section below). If the property
+    is unavailable, or other errors happen when retrieving it, the value is
+    never considered equal.
+    Note that ``VALUE`` can't contain any of the characters ``:`` or ``}``.
+    Also, it is possible that escaping with ``"`` or ``%`` might be added in
+    the future, should the need arise.
+``${!NAME==VALUE:STR}``
+    Same as with the ``?`` variant, but ``STR`` is expanded if the value is
+    not equal. (Using the same semantics as with ``?``.)
+``$$``
+    Expands to ``$``.
+``$}``
+    Expands to ``}``. (To produce this character inside recursive
+    expansion.)
+``$>``
+    Disable property expansion and special handling of ``$`` for the rest
+    of the string.
+
+In places where property expansion is allowed, C-style escapes are often
+accepted as well. Example:
+
+    - ``\n`` becomes a newline character
+    - ``\\`` expands to ``\``
+
+Raw and Formatted Properties
+----------------------------
+
+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.
+
+.. admonition:: Examples
+
+    - ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14
+      minutes 23 seconds)
+    - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds -
+      milliseconds are normally not shown in the formatted case)
+
+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
+it is the other way around, e.g. ``aid`` shows track title and language in the
+formatted case, but only the track number if it is raw.