Adding upstream version 0.37.0.upstream/0.37.0

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

26 files changed, 21281 insertions, 0 deletions

diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
new file mode 100644
index 0000000..f092647
--- /dev/null
+++ b/DOCS/client-api-changes.rst
@@ -0,0 +1,279 @@
+Introduction
+============
+
+This file lists all changes that can cause compatibility issues when using
+mpv through the client API (libmpv and ``client.h``). Since the client API
+interfaces to input handling (commands, properties) as well as command line
+options, you should also look at ``interface-changes.rst``.
+
+Normally, changes to the C API that are incompatible to previous iterations
+receive a major version bump (i.e. the first version number is increased),
+while C API additions bump the minor version (i.e. the second number is
+increased). Changes to properties/commands/options may also lead to a minor
+version bump, in particular if they are incompatible.
+
+The version number is the same as used for MPV_CLIENT_API_VERSION (see
+``client.h`` how to convert between major/minor version numbers and the flat
+32 bit integer).
+
+Also, read the section ``Compatibility`` in ``client.h``, and compatibility.rst.
+
+Options, commands, properties
+=============================
+
+Changes to these are not listed here, but in ``interface-changes.rst``. (Before
+client API version 1.17, they were listed here partially.)
+
+This listing includes changes to the bare C API and behavior only, not what
+you can access with them.
+
+API changes
+===========
+
+::
+
+ --- mpv 0.37.0 ---
+ 2.2    - add mpv_time_ns()
+ --- mpv 0.36.0 ---
+ 2.1    - add mpv_del_property()
+ --- mpv 0.35.0 ---
+ 2.0    - remove headers/functions of the obsolete opengl_cb API
+        - remove mpv_opengl_init_params.extra_exts field
+        - remove deprecated mpv_detach_destroy. Use mpv_destroy instead.
+        - remove obsolete mpv_suspend and mpv_resume
+        - remove deprecated SCRIPT_INPUT_DISPATCH, PAUSE and UNPAUSE, TRACKS_CHANGED
+          TRACK_SWITCHED, METADATA_UPDATE, CHAPTER_CHANGE events
+ --- mpv 0.33.0 ---
+ 1.109  - add MPV_RENDER_API_TYPE_SW and related (software rendering API)
+        - inactivate the opengl_cb API (always fails to initialize now)
+          The opengl_cb API was deprecated over 2 years ago. Use the render API
+          instead.
+ 1.108  - Deprecate MPV_EVENT_IDLE
+        - add mpv_event_start_file
+        - add the following fields to mpv_event_end_file: playlist_entry_id,
+          playlist_insert_id, playlist_insert_num_entries
+        - add mpv_event_to_node()
+        - add mpv_client_id()
+ 1.107  - Remove the deprecated qthelper.hpp. This was obviously not part of the
+          libmpv API, only an "additionally" provided helper, thus this is not
+          considered an API change. If you are maintaining a project that relies
+          on this header, you can simply download this file and adjust the
+          include statement to use it instead:
+
+            https://raw.githubusercontent.com/mpv-player/mpv/v0.32.0/libmpv/qthelper.hpp
+
+          It is a good idea to write better wrappers for your use, though.
+ --- mpv 0.31.0 ---
+ 1.107  - Deprecate MPV_EVENT_TICK
+ --- mpv 0.30.0 ---
+ 1.106  - Add cancel_fn to mpv_stream_cb_info
+ 1.105  - Fix deadlock problems with MPV_RENDER_PARAM_ADVANCED_CONTROL and if
+          the "vd-lavc-dr" option is enabled (which it is by default).
+          There were no actual API changes.
+          API users on older API versions and mpv releases should set
+          "vd-lavc-dr" to "no" to avoid these issues.
+          API users must still adhere to the tricky rules documented in render.h
+          to avoid other deadlocks.
+ 1.104  - Deprecate struct mpv_opengl_drm_params. Replaced by mpv_opengl_drm_params_v2
+        - Deprecate MPV_RENDER_PARAM_DRM_DISPLAY. Replaced by MPV_RENDER_PARAM_DRM_DISPLAY_V2.
+ 1.103  - redo handling of async commands
+        - add mpv_event_command and make it possible to return values from
+          commands issued with mpv_command_async() or mpv_command_node_async()
+        - add mpv_abort_async_command()
+ 1.102  - rename struct mpv_opengl_drm_osd_size to mpv_opengl_drm_draw_surface_size
+        - rename MPV_RENDER_PARAM_DRM_OSD_SIZE to MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE
+ --- mpv 0.29.0 ---
+ 1.101  - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API
+        - add MPV_RENDER_PARAM_NEXT_FRAME_INFO and related symbols
+        - add MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME
+        - add MPV_RENDER_PARAM_SKIP_RENDERING
+        - add mpv_render_context_get_info()
+ 1.100  - bump API number to avoid confusion with mpv release versions
+        - actually apply the GL_MP_MPGetNativeDisplay change for the new render
+          API. This also means compatibility for anything but x11 and wayland
+          through the old opengl-cb GL_MP_MPGetNativeDisplay method is now
+          unsupported.
+        - deprecate mpv_get_wakeup_pipe(). It's complex, but easy to replace
+          using normal API (just set a wakeup callback to a function which
+          writes to a pipe).
+        - add a 1st class hook API, which replaces the hacky mpv_command()
+          based one. The old API is deprecated and will be removed soon. The
+          old API was never meant to be stable, while the new API is.
+ 1.29   - the behavior of mpv_terminate_destroy() and mpv_detach_destroy()
+          changes subtly (see documentation in the header file). In particular,
+          mpv_detach_destroy() will not leave the player running in all
+          situations anymore (it gets closer to refcounting).
+        - rename mpv_detach_destroy() to mpv_destroy() (the old function will
+          remain valid as deprecated alias)
+        - add mpv_create_weak_client(), which makes use of above changes
+        - MPV_EVENT_SHUTDOWN is now returned exactly once if a mpv_handle
+          should terminate, instead of spamming the event queue with this event
+ 1.28   - deprecate the render opengl_cb API, and replace it with render.h
+          and render_gl.h. The goal is allowing support for APIs other than
+          OpenGL. The old API is emulated with the new API.
+          Likewise, the "opengl-cb" VO is renamed to "libmpv".
+          mpv_get_sub_api() is deprecated along the opengl_cb API.
+          The new API is relatively similar, but not the same. The rough
+          equivalents are:
+            mpv_opengl_cb_init_gl => mpv_render_context_create
+            mpv_opengl_cb_set_update_callback => mpv_render_context_set_update_callback
+            mpv_opengl_cb_draw => mpv_render_context_render
+            mpv_opengl_cb_report_flip => mpv_render_context_report_swap
+            mpv_opengl_cb_uninit_gl => mpv_render_context_free
+          The VO opengl-cb is also renamed to "libmpv".
+          Also, the GL_MP_MPGetNativeDisplay pseudo extension is not used by the
+          render API anymore, and the old opengl-cb API only handles the "x11"
+          and "wl" names anymore. Support for everything else has been removed.
+          The new render API uses proper API parameters, e.g. for X11 you pass
+          MPV_RENDER_PARAM_X11_DISPLAY directly.
+        - deprecate the qthelper.hpp header file. This provided some C++ helper
+          utility functions for Qt with use of libmpv. There is no reason to
+          keep this in the mpv git repository, nor to make it part of the libmpv
+          API. If you're using this header, you can safely copy it into your
+          project - it uses only libmpv public API. Alternatively, it could be
+          maintained in a separate repository by interested parties.
+ 1.27   - make opengl-cb the default VO. This causes a subtle behavior change
+          if the API user called mpv_opengl_cb_init_gl(), but does not set
+          the "vo" option. Before, it would still have used another VO (like
+          on the CLI, e.g. vo=gpu). Now it'll behave as if vo=opengl-cb was
+          used.
+ --- mpv 0.28.0 ---
+ 1.26   - remove glMPGetNativeDisplay("drm") support
+        - add mpv_opengl_cb_window_pos and mpv_opengl_cb_drm_params and
+          support via glMPGetNativeDisplay() for using it
+        - make --stop-playback-on-init-failure=no the default in libmpv (just
+          like in mpv CLI)
+ --- mpv 0.27.0 ---
+ 1.25   - remove setting "no-" options via mpv_set_option*(). (See corresponding
+          deprecation in 0.23.0.)
+ --- mpv 0.25.0 ---
+ 1.24   - add a MPV_ENABLE_DEPRECATED preprocessor symbol, which can be defined
+          by the user to exclude deprecated API symbols from the C headers
+ --- mpv 0.23.0 ---
+ 1.24   - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing.
+ --- mpv 0.22.0 ---
+ 1.23   - deprecate setting "no-" options via mpv_set_option*(). For example,
+          instead of "no-video=" you should set "video=no".
+        - do not override the SIGPIPE signal handler anymore. This was done as
+          workaround for the FFmpeg TLS code, which has been fixed long ago.
+        - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out
+          in mpv 0.23.0.
+        - make mpv_set_property() work to some degree before mpv_initialize().
+          It can now be used instead of mpv_set_option().
+        - semi-deprecate mpv_set_option()/mpv_set_option_string(). You should
+          use mpv_set_property() instead. There are some deprecated properties
+          which conflict with some options (see client.h remarks on
+          mpv_set_option()), for which mpv_set_option() might still be required.
+          In future mpv releases, the conflicting deprecated options/properties
+          will be removed, and mpv_set_option() will internally translate API
+          calls to mpv_set_property().
+        - qthelper.hpp: deprecate get_property_variant, set_property_variant,
+          set_option_variant, command_variant, and replace them with
+          get_property, set_property, command.
+ --- mpv 0.19.0 ---
+ 1.22   - add stream_cb API for custom protocols
+ --- mpv 0.18.1 ---
+ ----   - remove "status" log level from mpv_request_log_messages() docs. This
+          is 100% equivalent to "v". The behavior is still the same, thus no
+          actual API change.
+ --- mpv 0.18.0 ---
+ 1.21   - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this
+          change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the
+          property was not a string or did not have special mechanisms in place
+          the function failed. Now it always invokes the option string parser,
+          and mpv_node with a basic data type works exactly as if the function
+          is invoked with that type directly. This new behavior is equivalent
+          to mpv_set_option().
+          This also affects the mp.set_property_native() Lua function.
+        - generally, setting choice options/properties with "yes"/"no" options
+          can now be set as MPV_FORMAT_FLAG
+        - reading a choice property as MPV_FORMAT_NODE will now return a
+          MPV_FORMAT_FLAG value if the choice is "yes" (true) or "no" (false)
+          This implicitly affects Lua and JSON IPC interfaces as well.
+        - big changes to vo-cmdline on vo_opengl and vo_opengl_hq (but not
+          vo_opengl_cb): options are now normally not reset, but applied on top
+          of the current options. The special undocumented value "-" still
+          works, but now resets all options to before any vo-cmdline command
+          has been called.
+ --- mpv 0.12.0 ---
+ 1.20   - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce
+          "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a
+          backwards-compatible rename)
+ --- mpv 0.11.0 ---
+ --- mpv 0.10.0 ---
+ 1.19   - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to
+          use DXVA2 in OpenGL fullscreen mode in some situations
+        - mpv_request_log_messages() now accepts "terminal-default" as parameter
+ 1.18   - add MPV_END_FILE_REASON_REDIRECT, and change behavior of
+          MPV_EVENT_END_FILE accordingly
+        - a bunch of interface-changes.rst changes
+ 1.17   - mpv_initialize() now blocks SIGPIPE (details see client.h)
+ --- mpv 0.9.0 ---
+ 1.16   - add mpv_opengl_cb_report_flip()
+        - introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render()
+        - add MPV_FORMAT_BYTE_ARRAY
+ 1.15   - mpv_initialize() will now load config files. This requires setting
+          the "config" and "config-dir" options. In particular, it will load
+          mpv.conf.
+        - minor backwards-compatible change to the "seek" and "screenshot"
+          commands (new flag syntax, old additional args deprecated)
+ --- mpv 0.8.0 ---
+ 1.14   - add mpv_wait_async_requests()
+        - the --msg-level option changes its native type from a flat string to
+          a key-value list (setting/reading the option as string still works)
+ 1.13   - add MPV_EVENT_QUEUE_OVERFLOW
+ 1.12   - add class Handle to qthelper.hpp
+        - improve opengl_cb.h API uninitialization behavior, and fix the qml
+          example
+        - add mpv_create_client() function
+ 1.11   - add OpenGL rendering interop API - allows an application to combine
+          its own and mpv's OpenGL rendering
+          Warning: this API is not stable yet - anything in opengl_cb.h might
+                   be changed in completely incompatible ways in minor API bumps
+ --- mpv 0.7.0 ---
+ 1.10   - deprecate/disable everything directly related to script_dispatch
+          (most likely affects nobody)
+ 1.9    - add enum mpv_end_file_reason for mpv_event_end_file.reason
+        - add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field
+          for slightly better error reporting on playback failure
+        - add --stop-playback-on-init-failure option, and make it the default
+          behavior for libmpv only
+        - add qthelper.hpp set_option_variant()
+        - mark the following events as deprecated:
+            MPV_EVENT_TRACKS_CHANGED
+            MPV_EVENT_TRACK_SWITCHED
+            MPV_EVENT_PAUSE
+            MPV_EVENT_UNPAUSE
+            MPV_EVENT_METADATA_UPDATE
+            MPV_EVENT_CHAPTER_CHANGE
+          They are handled better with mpv_observe_property() as mentioned in
+          the documentation comments. They are not removed and still work.
+ 1.8    - add qthelper.hpp
+ 1.7    - add mpv_command_node(), mpv_command_node_async()
+ 1.6    - modify "core-idle" property behavior
+        - MPV_EVENT_LOG_MESSAGE now always sends complete lines
+        - introduce numeric log levels (mpv_log_level)
+ --- mpv 0.6.0 ---
+ 1.5    - change in X11 and "--wid" behavior again. The previous change didn't
+          work as expected, and now the behavior can be explicitly controlled
+          with the "input-x11-keyboard" option. This is only a temporary
+          measure until XEmbed is implemented and confirmed working.
+          Note: in 1.6, "input-x11-keyboard" was renamed to "input-vo-keyboard",
+          although the old option name still works.
+ 1.4    - subtle change in X11 and "--wid" behavior
+          (this change was added to 0.5.2, and broke some things, see #1090)
+ --- mpv 0.5.0 ---
+ 1.3    - add MPV_MAKE_VERSION()
+ 1.2    - remove "stream-time-pos" property (no replacement)
+ 1.1    - remap dvdnav:// to dvd://
+        - add "--cache-file", "--cache-file-size"
+        - add "--colormatrix-primaries" (and property)
+        - add "primaries" sub-field to image format properties
+        - add "playback-time" property
+        - extend the "--start" option; a leading "+", which was previously
+          insignificant is now significant
+        - add "cache-free" and "cache-used" properties
+        - OSX: the "coreaudio" AO spdif code is split into a separate AO
+ --- mpv 0.4.0 ---
+ 1.0    - the API is declared stable
+
diff --git a/DOCS/compatibility.rst b/DOCS/compatibility.rst
new file mode 100644
index 0000000..3d6ec2c
--- /dev/null
+++ b/DOCS/compatibility.rst
@@ -0,0 +1,177 @@
+CLI and API compatibility policy
+================================
+
+Human users and API users rely on the mpv/libmpv/scripting/IPC interface not
+breaking their use case. On the other hand, active development occasionally
+requires breaking things, such as removing old options or changing options in
+a way that may break.
+
+This document lists rules when, what, and how incompatible changes can be made.
+It's interesting both for mpv developers, who want to change user-visible parts,
+and mpv users, who want to know what is guaranteed to remain stable.
+
+Any of the rules below may be overridden by statements in more specific
+documentation (for example, if the manpage says that a particular option may be
+removed any time, it means that, and the option probably won't even go through
+deprecation).
+
+Additions
+---------
+
+Additions are basically always allowed. API users etc. are supposed to deal with
+the possibility that for example new API functions are added. Some parts of the
+API may document how they are extended.
+
+Options, commands, properties, events, hooks (command interface)
+----------------------------------------------------------------
+
+All of these are important for interfacing both with end users and API users
+(which include Lua scripts, libmpv, and the JSON IPC). As such, they constitute
+a large part of the user interface and APIs.
+
+All incompatible changes to this must be declared in interface-changes.rst.
+(This may also list compatible additions, but it's not a requirement.)
+
+Degrees of importance and compatibility preservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Critical and central parts of the command interface have the strictest
+requirements. It may not be reasonable to break them, and other means to achieve
+some change have to be found. For example, the "seek" command is a bit of a
+mess, but since changing it would likely affect almost every user, it may be
+impossible to break at least the commonly used syntax. If changed anyway, there
+should be a deprecation period of at least 1 year, during which the command
+still works, and possibly a warning should remain even after this.
+
+Important/often used parts must be deprecated for at least 2 releases before
+they can be broken. There must be at least 1 release where the deprecated
+functionality still works, and a replacement is available (if technically
+reasonable). For example, a feature deprecated in mpv 0.30.0 may be removed in
+mpv 0.32.0. Minor releases do not count towards this.
+
+Less useful parts can be broken immediately, but must come with some sort of
+removal warning-
+
+Parts for debugging and testing may be removed any time, potentially even
+without any sort of documentation.
+
+Currently, the importance of a part is not documented and not even well-defined,
+which is probably a mistake.
+
+Renaming or removing options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Typically, renaming an option can be done in a compatible way with OPT_REPLACED.
+You may need to check whether the corresponding properties still work (including
+messy details like observing properties for changes).
+
+OPT_REMOVED can be used to inform the user of alternatives or reasons for the
+removal, which is better than an option not found error. Likewise,
+m_option.deprecation_message should be set to something helpful.
+
+Both OPT_REPLACED and OPT_REMOVED can remain in the code for a long time, since
+they're unintrusive and hopefully make incompatible changes less painful for
+users.
+
+Scripting APIs
+--------------
+
+This affects internal scripting APIs (currently Lua and JavaScript).
+
+Vaguely the same rules as with the command interface apply. Since there is a
+large number of scripts, an effort should be made to provide compatibility
+for old scripts, but it does not need to be stronger than that of the command
+interface.
+
+Undocumented parts of the scripting APIs are _not_ guaranteed for compatibility.
+This applies especially for internals. Languages like Lua do not have strict
+access control (nor does the mpv code try to emulate any), so if a script
+accesses private parts, and breaks on the next mpv release, it's not mpv's
+problem.
+
+JSON IPC
+--------
+
+The JSON IPC is a thin protocol wrapping the libmpv API and the command
+interface. Compatibility-wise, it's about the same as the scripting APIs.
+The JSON protocol commands should remain as compatible as possible, and it
+should probably accept the current way commands are delimited (line breaks)
+forever.
+
+The protocol may accept non-standard JSON extensions, but only standard JSON
+(possibly with restrictions) is guaranteed for compatibility. Clients which want
+to remain compatible should not use any extensions.
+
+CLI
+---
+
+Things such as default key bindings do not necessarily require compatibility.
+However, the release notes should be extremely clear on changes to "important"
+key bindings. Bindings which restore the old behavior should be added to
+restore-old-bindings.conf.
+
+Some option parsing is CLI-only and not available from libmpv or scripting. No
+compatibility guarantees come with them. However, the rules which mpv uses to
+distinguish between options and filenames must remain consistent (if the
+non-deprecated options syntax is used).
+
+Terminal and log output
+-----------------------
+
+There are no compatibility guarantees for the terminal output, or the text
+logged via ``MPV_EVENT_LOG_MESSAGE`` and similar APIs. In particular, scripts
+invoking mpv CLI are extremely discouraged from trying to parse text output,
+and should use other mechanisms such as the JSON IPC.
+
+Protocols, filters, demuxers, etc.
+----------------------------------
+
+Which of these are present is generally not guaranteed, and can even depend
+on compile time settings.
+
+The filter list and their sub-options are considered part of the
+command-interface.
+
+libmpv C API
+------------
+
+The libmpv client API (such as ``<libmpv/client.h>``) mostly gives access to
+the command interface. The API itself (if looked at as a component separate
+from the command interface) is intended to be extremely stable.
+
+All API changes are documented in client-api-changes.rst.
+
+API compatibility
+^^^^^^^^^^^^^^^^^
+
+The API is *always* compatible. Incompatible changes are only allowed on major
+API version changes (see ``MPV_CLIENT_API_VERSION``). A major version change is
+an extremely rare event, which means usually no API symbols are ever removed.
+
+Essentially removing API functions by making them always return an error, or
+making it do nothing is allowed in cases where it is unlikely to break most
+clients, but requires a deprecation period of 2 releases. (This has happened to
+``mpv_suspend()`` for example.)
+
+API symbols can be deprecated. This should be clearly marked in the doxygen
+with ``@deprecated``, and if possible, the affected API symbols should not be
+visible if the API user defines ``MPV_ENABLE_DEPRECATED`` to 0.
+
+ABI compatibility
+^^^^^^^^^^^^^^^^^
+
+The ABI must never be broken, except on major API version changes. For example,
+constants don't change their values.
+
+Structs are tricky. If a struct can be allocated by a user (such as ``mpv_node``),
+no fields can be added. (Unless it's an union, and the addition does not change
+the offset or alignment of any of the fields or the struct itself. This has
+happened to ``mpv_node`` in the past.) If a struct is allocated by libmpv only,
+new fields can be appended to the end (for example ``mpv_event``).
+
+The ABI is only backward compatible. This means if a host application is linked
+to an older libmpv, and libmpv is updated to a newer version, it will still
+work (as in not causing any undefined behavior).
+
+Forward compatibility (an application would work with an older libmpv than it
+was linked to) is not required.
diff --git a/DOCS/compile-windows.md b/DOCS/compile-windows.md
new file mode 100644
index 0000000..04bc200
--- /dev/null
+++ b/DOCS/compile-windows.md
@@ -0,0 +1,214 @@
+Compiling for Windows
+=====================
+
+Compiling for Windows is supported with MinGW-w64. This can be used to produce
+both 32-bit and 64-bit executables, and it works for building on Windows and
+cross-compiling from Linux and Cygwin. MinGW-w64 is available from:
+https://www.mingw-w64.org/
+
+While building a complete MinGW-w64 toolchain yourself is possible, there are a
+few build environments and scripts to help ease the process, such as MSYS2 and
+MXE. Note that MinGW environments included in Linux distributions are often
+broken, outdated and useless, and usually don't use MinGW-w64.
+
+**Warning**: the original MinGW (https://osdn.net/projects/mingw/) is unsupported.
+
+Cross-compilation
+=================
+
+When cross-compiling, it is recommended to use a meson crossfile to setup
+the cross compiling environment. A minimal example is included below:
+
+```ini
+[binaries]
+c = 'x86_64-w64-mingw32-gcc'
+cpp = 'x86_64-w64-mingw32-g++'
+ar = 'x86_64-w64-mingw32-ar'
+strip = 'x86_64-w64-mingw32-strip'
+exe_wrapper = 'wine64'
+
+[host_machine]
+system = 'windows'
+cpu_family = 'x86_64'
+cpu = 'x86_64'
+endian = 'little'
+```
+
+See [meson's documentation](https://mesonbuild.com/Cross-compilation.html) for
+more information.
+
+[MXE](https://mxe.cc) makes it very easy to bootstrap a complete MingGW-w64
+environment from a Linux machine. See a working example below.
+
+Alternatively, you can try [mpv-winbuild-cmake](https://github.com/shinchiro/mpv-winbuild-cmake),
+which bootstraps a MinGW-w64 environment and builds mpv and dependencies.
+
+Example with MXE
+----------------
+
+```bash
+# Before starting, make sure you install MXE prerequisites. MXE will download
+# and build all target dependencies, but no host dependencies. For example,
+# you need a working compiler, or MXE can't build the crosscompiler.
+#
+# Refer to
+#
+#    https://mxe.cc/#requirements
+#
+# Scroll down for disto/OS-specific instructions to install them.
+
+# Download MXE. Note that compiling the required packages requires about 1.4 GB
+# or more!
+
+cd /opt
+git clone https://github.com/mxe/mxe mxe
+cd mxe
+
+# Set build options.
+
+# The JOBS environment variable controls threads to use when building. DO NOT
+# use the regular `make -j4` option with MXE as it will slow down the build.
+# Alternatively, you can set this in the make command by appending "JOBS=4"
+# to the end of command:
+echo "JOBS := 4" >> settings.mk
+
+# The MXE_TARGET environment variable builds MinGW-w64 for 32 bit targets.
+# Alternatively, you can specify this in the make command by appending
+# "MXE_TARGETS=i686-w64-mingw32" to the end of command:
+echo "MXE_TARGETS := i686-w64-mingw32.static" >> settings.mk
+
+# If you want to build 64 bit version, use this:
+# echo "MXE_TARGETS := x86_64-w64-mingw32.static" >> settings.mk
+
+# Build required packages. The following provide a minimum required to build
+# a reasonable mpv binary (though not an absolute minimum).
+
+make gcc ffmpeg libass jpeg lua luajit
+
+# Add MXE binaries to $PATH
+export PATH=/opt/mxe/usr/bin/:$PATH
+
+# Build mpv. The target will be used to automatically select the name of the
+# build tools involved (e.g. it will use i686-w64-mingw32.static-gcc).
+
+cd ..
+git clone https://github.com/mpv-player/mpv.git
+cd mpv
+meson setup build --crossfile crossfile
+meson compile -C build
+```
+
+Native compilation with MSYS2
+=============================
+
+For Windows developers looking to get started quickly, MSYS2 can be used to
+compile mpv natively on a Windows machine. The MSYS2 repositories have binary
+packages for most of mpv's dependencies, so the process should only involve
+building mpv itself.
+
+To build 64-bit mpv on Windows:
+
+Installing MSYS2
+----------------
+
+1. Download an installer from https://www.msys2.org/
+
+   Both the i686 and the x86_64 version of MSYS2 can build 32-bit and 64-bit
+   mpv binaries when running on a 64-bit version of Windows, but the x86_64
+   version is preferred since the larger address space makes it less prone to
+   fork() errors.
+
+2. Start a MinGW-w64 shell (``mingw64.exe``). **Note:** This is different from
+   the MSYS2 shell that is started from the final installation dialog. You must
+   close that shell and open a new one.
+
+   For a 32-bit build, use ``mingw32.exe``.
+
+Updating MSYS2
+--------------
+
+To prevent errors during post-install, the MSYS2 core runtime must be updated
+separately.
+
+```bash
+# Check for core updates. If instructed, close the shell window and reopen it
+# before continuing.
+pacman -Syu
+
+# Update everything else
+pacman -Su
+```
+
+Installing mpv dependencies
+---------------------------
+
+```bash
+# Install MSYS2 build dependencies and a MinGW-w64 compiler
+pacman -S git $MINGW_PACKAGE_PREFIX-{python,pkgconf,gcc,meson}
+
+# Install the most important MinGW-w64 dependencies. libass and lcms2 are also
+# pulled in as dependencies of ffmpeg.
+pacman -S $MINGW_PACKAGE_PREFIX-{ffmpeg,libjpeg-turbo,luajit}
+```
+
+Building mpv
+------------
+
+Finally, compile and install mpv. Binaries will be installed to
+``/mingw64/bin`` or ``/mingw32/bin``.
+
+```bash
+meson setup build --prefix=$MSYSTEM_PREFIX
+meson compile -C build
+```
+
+Or, compile and install both libmpv and mpv:
+
+```bash
+meson setup build -Dlibmpv=true --prefix=$MSYSTEM_PREFIX
+meson compile -C build
+meson install -C build
+```
+
+Linking libmpv with MSVC programs
+---------------------------------
+
+mpv/libmpv cannot be built with Visual Studio (Microsoft is too incompetent to
+support C99/C11 properly and/or hates open source and Linux too much to
+seriously do it). But you can build C++ programs in Visual Studio and link them
+with a libmpv built with MinGW.
+
+To do this, you need a Visual Studio which supports ``stdint.h`` (recent ones do),
+and you need to create a import library for the mpv DLL:
+
+```bash
+lib /name:mpv-1.dll /out:mpv.lib /MACHINE:X64
+```
+
+The string in the ``/name:`` parameter must match the filename of the DLL (this
+is simply the filename the MSVC linker will use).
+
+Static linking is not possible.
+
+Running mpv
+-----------
+
+If you want to run mpv from the MinGW-w64 shell, you will find the experience
+much more pleasant if you use the ``winpty`` utility
+
+```bash
+pacman -S winpty
+winpty mpv.com ToS-4k-1920.mov
+```
+
+If you want to move / copy ``mpv.exe`` and ``mpv.com`` to somewhere other than
+``/mingw64/bin/`` for use outside the MinGW-w64 shell, they will still depend on
+DLLs in that folder. The simplest solution is to add ``C:\msys64\mingw64\bin``
+to the windows system ``%PATH%``. Beware though that this can cause problems or
+confusion in Cygwin if that is also installed on the machine.
+
+Use of the ANGLE OpenGL backend requires a copy of the D3D compiler DLL that
+matches the version of the D3D SDK that ANGLE was built with
+(``d3dcompiler_43.dll`` in case of MinGW-built ANGLE) in the path or in the
+same folder as mpv. It must be of the same architecture (x86_64 / i686) as the
+mpv you compiled.
diff --git a/DOCS/contribute.md b/DOCS/contribute.md
new file mode 100644
index 0000000..91422a7
--- /dev/null
+++ b/DOCS/contribute.md
@@ -0,0 +1,281 @@
+How to contribute
+=================
+
+General
+-------
+
+The main contact for mpv development is IRC, specifically #mpv
+and #mpv-devel on Libera.chat. Github is used for code review and
+long term discussions.
+
+Sending patches
+---------------
+
+- Make a github pull request, or send a link to a plaintext patch created with
+  ``git format-patch``.
+- Plain diffs posted as pastebins are not acceptable! (Especially if the http
+  link returns HTML.) They only cause extra work for everyone, because they lack
+  commit message and authorship information.
+- Never send patches to any of the developers email addresses.
+- If your changes are not supposed to be merged immediately, mark them as
+  "[RFC]" in the commit message or the pull request title.
+- Be sure to test your changes. If you didn't, please say so in the commit
+  message and the pull request text.
+
+Copyright of contributions
+--------------------------
+
+- The copyright belongs to contributors. The project is a collaborative work. By
+  sending your changes, you agree to license your contributions according to the
+  requirements of this project.
+- All new code must be LGPLv2.1+ licensed, or come with the implicit agreement
+  that it will be relicensed to LGPLv2.1+ later (see ``Copyright`` in the
+  repository root directory).
+- 100% compatible licenses are allowed too.
+- Changes in files with more liberal licenses (such as BSD, MIT, or ISC) are
+  assumed to be dual-licensed under LGPLv2.1+ and the license indicated in the
+  file header.
+- You must be either the exclusive author of the patch, or acknowledge all
+  authors involved in the commit message. If you take 3rd party code, authorship
+  and copyright must be properly acknowledged. If you're making changes on
+  behalf of your employer, and the employer owns the copyright, you must mention
+  this. If the license of the code is not LGPLv2.1+, you must mention this.
+- These license statements are legally binding.
+- Don't use fake names (something that looks like an actual name, and may be
+  someone else's name, but is not your legal name). Using a pseudonyms is
+  allowed if it can be used to identify or contact you, even if whatever
+  account you used to submit the patch dies.
+- Do not add your name to the license header. This convention is not used by
+  this project, and neither copyright law nor any of the used licenses require
+  it.
+
+Write good commit messages
+--------------------------
+
+- Write informative commit messages. Use present tense to describe the
+  situation with the patch applied, and past tense for the situation before
+  the change.
+- The subject line (the first line in a commit message) must contain a
+  prefix identifying the sub system, followed by a short description what
+  impact this commit has. This subject line and the commit message body
+  must not be longer than 72 characters per line, because it messes up the
+  output of many git tools otherwise.
+
+  For example, you fixed a crash in af_volume.c:
+
+  - Bad: ``fixed the bug (wtf?)``
+  - Good: ``af_volume: fix crash due to null pointer access``
+
+  Having a prefix gives context, and is especially useful when trying to find
+  a specific change by looking at the history, or when running ``git blame``.
+
+  Sample prefixes: ``vo_gpu: ...``, ``command: ...``, ``DOCS/input: ...``,
+  ``TOOLS/osxbundle: ...``, ``osc.lua: ...``, etc. You can always check the git
+  log for commits which modify specific files to see which prefixes are used.
+
+- The first word after the ``:`` is lower case.
+- Don't end the subject line with a ``.``.
+- Put an empty line between the subject line and the commit message.
+  If this is missing, it will break display in common git tools.
+- The body of the commit message (everything else after the subject line) must
+  be as informative as possible and contain everything that isn't obvious. Don't
+  hesitate to dump as much information as you can - it doesn't cost you
+  anything. Put some effort into it. If someone finds a bug months or years
+  later, and finds that it's caused by your commit (even though your commit was
+  supposed to fix another bug), it would be bad if there wasn't enough
+  information to test the original bug. The old bug might be reintroduced while
+  fixing the new bug.
+
+  The commit message must be wrapped on 72 characters per line, because git
+  tools usually do not break text automatically. On the other hand, you do not
+  need to break text that would be unnatural to break (like data for test cases,
+  or long URLs).
+- Another summary of good conventions: https://chris.beams.io/posts/git-commit/
+
+Split changes into multiple commits
+-----------------------------------
+
+- Follow git good practices, and split independent changes into several commits.
+  It's usually OK to put them into a single pull request.
+- Try to separate cosmetic and functional changes. It's ok to make a few
+  additional cosmetic changes in the same file you're working on. But don't do
+  something like reformatting a whole file, and hiding an actual functional
+  change in the same commit.
+- Splitting changes does _not_ mean that you should make them as fine-grained
+  as possible. Commits should form logical steps in development. The way you
+  split changes is important for code review and analyzing bugs.
+
+Always squash fixup commits when making changes to pull requests
+----------------------------------------------------------------
+
+- If you make fixup commits to your pull request, you should generally squash
+  them with "git rebase -i". We prefer to have pull requests in a merge
+  ready state.
+- We don't squash-merge (nor do we use github's feature that does this) because
+  pull requests with multiple commits are perfectly legitimate, and the only
+  thing that makes sense in non-trivial cases.
+- With complex pull requests, it *may* make sense to keep them separate, but
+  they should be clearly marked as such. Reviewing commits is generally easier
+  with fixups squashed.
+- Reviewers are encouraged to look at individual commits instead of github's
+  "changes from all commits" view (which just encourages bad git and review
+  practices).
+
+Touching user-visible parts may require updating the mpv docs
+-------------------------------------------------------------
+
+- Most user-visible things are normally documented in DOCS/man/. If your commit
+  touches documented behavior, list of sub-options, etc., you need to adjust the
+  documentation.
+- These changes usually go into the same commit that changes the code.
+- Changes to command line options (addition/modification/removal) must be
+  documented in options.rst.
+- Changes to input properties or input commands must be documented in input.rst.
+- All incompatible changes to the user interface (options, properties, commands)
+  must be documented with a small note in interface-changes.rst. (Additions may
+  be documented there as well, but this isn't required.)
+- Changes to the libmpv API must be reflected in the libmpv's headers doxygen,
+  and in client-api-changes.rst.
+
+Code formatting
+---------------
+
+mpv uses C11 with K&R formatting, with some exceptions.
+
+- Use the K&R indent style.
+- Use 4 spaces of indentation, never use tabs (except in Makefiles).
+- Add a single space between keywords and binary operators. There are some other
+  cases where spaces must be added. Example:
+
+    ```C
+    if ((a * b) > c) {
+        // code
+        some_function(a, b, c);
+    }
+    ```
+- Break lines on 80 columns. There is a hard limit of 100 columns. You may ignore
+  this limit if there's a strong case that not breaking the line will increase
+  readability. Going over 100 columns might provoke endless discussions about
+  whether such a limit is needed or not, so avoid it.
+- If the body of an if/for/while statement has more than 1 physical lines, then
+  always add braces, even if they're technically redundant.
+
+  Bad:
+
+    ```C
+    if (a)
+        // do something if b
+        if (b)
+            do_something();
+    ```
+
+  Good:
+
+    ```C
+    if (a) {
+        // do something if b
+        if (b)
+            do_something();
+    }
+    ```
+- If the if has an else branch, both branches must use braces, even if they're
+  technically redundant.
+
+  Example:
+
+    ```C
+    if (a) {
+        one_line();
+    } else {
+        one_other_line();
+    }
+    ```
+- If an if condition spans multiple physical lines, then put the opening brace
+  for the if body on the next physical line. (Also, preferably always add a
+  brace, even if technically none is needed.)
+
+  Example:
+
+    ```C
+    if (very_long_condition_a &&
+        very_long_condition_b)
+    {
+        code();
+    } else {
+        ...
+    }
+    ```
+
+  (If the if body is simple enough, this rule can be skipped.)
+- Remove any trailing whitespace.
+- Do not make stray whitespaces changes.
+
+Header #include statement order
+-------------------------------
+
+The order of ``#include`` statements in the source code is not very consistent.
+New code must follow the following conventions:
+
+- Put standard includes (``#include <stdlib.h>`` etc.) on the top,
+- then after a blank line, add library includes (``#include <zlib.h>`` etc.)
+- then after a blank line, add internal includes (``#include "player/core.h"``)
+- sort them alphabetically within these sections
+
+General coding
+--------------
+
+- Use C11. Also freely make use of C11 features if it's appropriate, but do not
+  use VLA and complex number types.
+- Don't use non-standard language (such as GNU C-only features). In some cases
+  they may be warranted, if they are optional (such as attributes enabling
+  printf-like format string checks). "#pragma once" is allowed as an exception.
+  But in general, standard C11 must be used.
+- The same applies to libc functions. We have to be Windows-compatible too. Use
+  functions guaranteed by C11 or POSIX only, unless your use is guarded by a
+  configure check. Be mindful of MinGW-specifics since C11 support is not always
+  guaranteed.
+- Prefer fusing declaration and initialization, rather than putting declarations
+  on the top of a block. Obvious data flow is more important than avoiding
+  mixing declarations and statements, which is just a C90 artifact.
+- If you add features that require intrusive changes, discuss them on the dev
+  channel first. There might be a better way to add a feature and it can avoid
+  wasted work.
+
+Code of Conduct
+---------------
+
+Please note that this project is released with a Contributor Code of Conduct.
+By participating in this project you agree to abide by its terms.
+The Contributor Code of Conduct can be found here:
+https://www.contributor-covenant.org/version/2/0/code_of_conduct/
+
+Rules for git push access
+-------------------------
+
+Push access to the main git repository is handed out on an arbitrary basis. If
+you got access, the following rules must be followed:
+
+- You are expected to follow the general development rules as outlined in this
+  whole document.
+- You must be present on the IRC dev channel when you push something.
+- Anyone can push small fixes: typo corrections, small/obvious/uncontroversial
+  bug fixes, edits to the user documentation or code comments, and so on.
+- You can freely make changes to parts of the code which you maintain. For
+  larger changes, it's recommended to let others review the changes first.
+- You automatically maintain code if you wrote or modified most of it before
+  (e.g. you made larger changes to it before, did partial or full rewrites, did
+  major bug fixes, or you're the original author of the code). If there is more
+  than one maintainer, you may need to come to an agreement with the others how
+  to handle this to avoid conflict.
+- If you make a pull requests (especially if it's to code you maintain), and you
+  want reviews, explicitly ping the people from which you expect reviews.
+- As a maintainer, you can approve pull requests by others to "your" code.
+- If you approve or merge 3rd party changes, make sure they follow the general
+  development rules.
+- Changes to user interface and public API must always be approved by the
+  project leader.
+- Seasoned project members are allowed to revert commits that broke the build,
+  or broke basic functionality in a catastrophic way, and the developer who
+  broke it is unavailable. (Depending on severity.)
+- Adhere to the CoC.
+- The project leader is not bound by these rules.
diff --git a/DOCS/edl-mpv.rst b/DOCS/edl-mpv.rst
new file mode 100644
index 0000000..0e4d2b4
--- /dev/null
+++ b/DOCS/edl-mpv.rst
@@ -0,0 +1,396 @@
+EDL files
+=========
+
+EDL files basically concatenate ranges of video/audio from multiple source
+files into a single continuous virtual file. Each such range is called a
+segment, and consists of source file, source offset, and segment length.
+
+For example::
+
+    # mpv EDL v0
+    f1.mkv,10,20
+    f2.mkv
+    f1.mkv,40,10
+
+This would skip the first 10 seconds of the file f1.mkv, then play the next
+20 seconds, then switch to the file f2.mkv and play all of it, then switch
+back to f1.mkv, skip to the 40 second mark, and play 10 seconds, and then
+stop playback. The difference to specifying the files directly on command
+line (and using ``--{ --start=10 --length=20 f1.mkv --}`` etc.) is that the
+virtual EDL file appears as a virtual timeline (like a single file), instead
+as a playlist.
+
+The general simplified syntax is::
+
+    # mpv EDL v0
+    <filename>
+    <filename>,<start in seconds>,<length in seconds>
+
+If the start time is omitted, 0 is used. If the length is omitted, the
+estimated remaining duration of the source file is used.
+
+Note::
+
+    Usage of relative or absolute paths as well as any protocol prefixes may be
+    prevented for security reasons.
+
+
+Syntax of mpv EDL files
+=======================
+
+Generally, the format is relatively strict. No superfluous whitespace (except
+empty lines and commented lines) are allowed. You must use UNIX line breaks.
+
+The first line in the file must be ``# mpv EDL v0``. This designates that the
+file uses format version 0, which is not frozen yet and may change any time.
+(If you need a stable EDL file format, make a feature request. Likewise, if
+you have suggestions for improvements, it's not too late yet.)
+
+The rest of the lines belong to one of these classes:
+
+1) An empty or commented line. A comment starts with ``#``, which must be the
+   first character in the line. The rest of the line (up until the next line
+   break) is ignored. An empty line has 0 bytes between two line feed bytes.
+2) A header entry if the line starts with ``!``.
+3) A segment entry in all other cases.
+
+Each segment entry consists of a list of named or unnamed parameters.
+Parameters are separated with ``,``. Named parameters consist of a name,
+followed by ``=``, followed by the value. Unnamed parameters have only a
+value, and the name is implicit from the parameter position.
+
+Syntax::
+
+    segment_entry ::= <param> ( <param> ',' )*
+    param         ::= [ <name> '=' ] ( <value> | '%' <number> '%' <valuebytes> )
+
+The ``name`` string can consist of any characters, except ``=%,;\n!``. The
+``value`` string can consist of any characters except of ``,;\n!``.
+
+The construct starting with ``%`` allows defining any value with arbitrary
+contents inline, where ``number`` is an integer giving the number of bytes in
+``valuebytes``. If a parameter value contains disallowed characters, it has to
+be guarded by a length specifier using this syntax.
+
+The parameter name defines the meaning of the parameter:
+
+1) ``file``, the source file to use for this segment.
+2) ``start``, a time value that specifies the start offset into the source file.
+3) ``length``, a time value that specifies the length of the segment.
+
+See the section below for the format of timestamps.
+
+Unnamed parameters carry implicit names. The parameter position determines
+which of the parameters listed above is set. For example, the second parameter
+implicitly uses the name ``start``.
+
+Example::
+
+    # mpv EDL v0
+    %18%filename,with,.mkv,10,length=20,param3=%13%value,escaped,param4=value2
+
+this sets ``file`` to ``filename,with,.mkv``, ``start`` to ``10``, ``length``
+to ``20``, ``param3`` to ``value,escaped``, ``param4`` to ``value2``.
+
+Instead of line breaks, the character ``;`` can be used. Line feed bytes and
+``;`` are treated equally.
+
+Header entries start with ``!`` as first character after a line break. Header
+entries affect all other file entries in the EDL file. Their format is highly
+implementation specific. They should generally follow the file header, and come
+before any file entries.
+
+Disabling chapter generation and copying
+========================================
+
+By default, chapters from the source ranges are copied to the virtual file's
+chapters. Also, a chapter is inserted after each range. This can be disabled
+with the ``no_chapters`` header.
+
+Example::
+
+    !no_chapters
+
+
+MP4 DASH
+========
+
+This is a header that helps implementing DASH, although it only provides a low
+level mechanism.
+
+If this header is set, the given url designates an mp4 init fragment. It's
+downloaded, and every URL in the EDL is prefixed with the init fragment on the
+byte stream level. This is mostly for use by mpv's internal ytdl support. The
+ytdl script will call youtube-dl, which in turn actually processes DASH
+manifests. It may work only for this very specific purpose and fail to be
+useful in other scenarios. It can be removed or changed in incompatible ways
+at any times.
+
+Example::
+
+    !mp4_dash,init=url
+
+The ``url`` is encoded as parameter value as defined in the general EDL syntax.
+It's expected to point to an "initialization fragment", which will be prefixed
+to every entry in the EDL on the byte stream level.
+
+The current implementation will
+
+- ignore stream start times
+- use durations as hint for seeking only
+- not adjust source timestamps
+- open and close segments (i.e. fragments) as needed
+- not add segment boundaries as chapter points
+- require full compatibility between all segments (same codec etc.)
+
+Another header part of this mechanism is ``no_clip``. This header is similar
+to ``mp4_dash``, but does not include on-demand opening/closing of segments,
+and does not support init segments. It also exists solely to support internal
+ytdl requirements. Using ``no_clip`` with segments is not recommended and
+probably breaks. ``mp4_dash`` already implicitly does a variant of ``no_clip``.
+
+The ``mp4_dash`` and ``no_clip`` headers are not part of the core EDL format.
+They may be changed or removed at any time, depending on mpv's internal
+requirements.
+
+Separate files for tracks
+=========================
+
+The special ``new_stream`` header lets you specify separate parts and time
+offsets for separate tracks. This can for example be used to source audio and
+video track from separate files.
+
+Example::
+
+    # mpv EDL v0
+    video.mkv
+    !new_stream
+    audio.mkv
+
+This adds all tracks from both files to the virtual track list. Upon playback,
+the tracks will be played at the same time, instead of appending them. The files
+can contain more than 1 stream; the apparent effect is the same as if the second
+part after the ``!new_stream`` part were in a separate ``.edl`` file and added
+with ``--external-file``.
+
+Note that all metadata between the stream sets created by ``new_stream`` is
+disjoint. Global metadata is taken from the first part only.
+
+In context of mpv, this is redundant to the ``--audio-file`` and
+``--external-file`` options, but (as of this writing) has the advantage that
+this will use a unified cache for all streams.
+
+The ``new_stream`` header is not part of the core EDL format. It may be changed
+or removed at any time, depending on mpv's internal requirements.
+
+If the first ``!new_stream`` is redundant, it is ignored. This is the same
+example as above::
+
+    # mpv EDL v0
+    !new_stream
+    video.mkv
+    !new_stream
+    audio.mkv
+
+Note that ``!new_stream`` must be the first header. Whether the parser accepts
+(i.e. ignores) or rejects other headers before that is implementation specific.
+
+Track metadata
+==============
+
+The special ``track_meta`` header can set some specific metadata fields of the
+current ``!new_stream`` partition. The tags are applied to all tracks within
+the partition. It is not possible to set the metadata for individual tracks (the
+feature was needed only for single-track media).
+
+It provides following parameters change track metadata:
+
+``lang``
+    Set the language tag.
+
+``title``
+    Set the title tag.
+
+``byterate``
+    Number of bytes per second this stream uses. (Purely informational.)
+
+``index``
+    The numeric index of the track this should map to (default: -1). This is
+    the 0-based index of the virtual stream as seen by the player, enumerating
+    all audio/video/subtitle streams. If nothing matches, this is silently
+    discarded. The special index -1 (the default) has two meanings: if there
+    was a previous meta data entry (either ``!track_meta`` or ``!delay_open``
+    element since the last ``!new_stream``), then this element manipulates
+    the previous meta data entry. If there was no previous entry, a new meta
+    data entry that matches all streams is created.
+
+Example::
+
+    # mpv EDL v0
+    !track_meta,lang=bla,title=blabla
+    file.mkv
+    !new_stream
+    !track_meta,title=ducks
+    sub.srt
+
+If ``file.mkv`` has an audio and a video stream, both will use ``blabla`` as
+title. The subtitle stream will use ``ducks`` as title.
+
+The ``track_meta`` header is not part of the core EDL format. It may be changed
+or removed at any time, depending on mpv's internal requirements.
+
+Global metadata
+===============
+
+The special ``global_tags`` header can set metadata fields (aka tags) of the EDL
+file. This metadata is supposed to be informational, much like for example ID3
+tags in audio files. Due to lack of separation of different kinds of metadata it
+is unspecified what names are allowed, how they are interpreted, and whether
+some of them affect playback functionally. (Much of this is unfortunately
+inherited from FFmpeg. Another consequence of this is that FFmpeg "normalized"
+tags are recognized, or stuff like replaygain tags.)
+
+Example::
+
+    !global_tags,title=bla,something_arbitrary=even_more_arbitrary
+
+Any parameter names are allowed. Repeated use of this adds to the tag list. If
+``!new_stream`` is used, the location doesn't matter.
+
+May possibly be ignored in some cases, such as delayed media opening.
+
+Delayed media opening
+=====================
+
+The special ``delay_open`` header can be used to open the media URL of the
+stream only when the track is selected for the first time. This is supposed to
+be an optimization to speed up opening of a remote stream if there are many
+tracks for whatever reasons.
+
+This has various tricky restrictions, and also will defer failure to open a
+stream to "later". By design, it's supposed to be used for single-track streams.
+
+Using multiple segments requires you to specify all offsets and durations (also
+it was never tested whether it works at all). Interaction with ``mp4_dash`` may
+be strange.
+
+You can describe multiple sub-tracks by using multiple ``delay_open`` headers
+before the same source URL. (If there are multiple sub-tracks of the same media
+type, then the mapping to the real stream is probably rather arbitrary.) If the
+source contains tracks not described, a warning is logged when the delayed
+opening happens, and the track is hidden.
+
+This has the following parameters:
+
+``media_type``
+    Required. Must be set to ``video``, ``audio``, or ``sub``. (Other tracks in
+    the opened URL are ignored.)
+
+``codec``
+    The mpv codec name that is expected. Although mpv tries to initialize a
+    decoder with it currently (and will fail track selection if it does not
+    initialize successfully), it is not used for decoding - decoding still uses
+    the information retrieved from opening the actual media information, and may
+    be a different codec (you should try to avoid this, of course). Defaults to
+    ``null``.
+
+    Above also applies for similar fields such as ``w``.  These fields are
+    mostly to help with user track pre-selection.
+
+``flags``
+    A ``+`` separated list of boolean flags. Currently defined flags:
+
+        ``default``
+            Set the default track flag.
+
+        ``forced``
+            Set the forced track flag.
+
+    Other values are ignored after triggering a warning.
+
+``w``, ``h``
+    For video codecs: expected video size. See ``codec`` for details.
+
+``fps``
+    For video codecs: expected video framerate, as integer. (The rate is usually
+    only crudely reported, and it makes no sense to expect exact values.)
+
+``samplerate``
+    For audio codecs: expected sample rate, as integer.
+
+The ``delay_open`` header is not part of the core EDL format. It may be changed
+or removed at any time, depending on mpv's internal requirements.
+
+Timestamp format
+================
+
+Currently, time values are floating point values in seconds.
+
+As an extension, you can set the ``timestamps=chapters`` option. If this option
+is set, timestamps have to be integers, and refer to chapter numbers, starting
+with 0. The default value for this parameter is ``seconds``, which means the
+time is as described in the previous paragraph.
+
+Example::
+
+    # mpv EDL v0
+    file.mkv,2,4,timestamps=chapters
+
+Plays chapter 3 and ends with the start of chapter 7 (4 chapters later).
+
+Implicit chapters
+=================
+
+mpv will add one chapter per segment entry to the virtual timeline.
+
+By default, the chapter's titles will match the entries' filenames.
+You can override set the ``title`` option to override the chapter title for
+that segment.
+
+Example::
+
+    # mpv EDL v0
+    cap.ts,5,240
+    OP.mkv,0,90,title=Show Opening
+
+The virtual timeline will have two chapters, one called "cap.ts" from 0-240s
+and a second one called "Show Opening" from 240-330s.
+
+Entry which defines the track layout
+====================================
+
+Normally, you're supposed to put only files with compatible layouts into an EDL
+file. However, at least the mpv implementation accepts entries that use
+different codecs, or even have a different number of audio/video/subtitle
+tracks. In this case, it's not obvious, which virtual tracks the EDL show should
+expose when being played.
+
+Currently, mpv will apply an arbitrary heuristic which tracks the EDL file
+should expose. (Before mpv 0.30.0, it always used the first source file in the
+segment list.)
+
+You can set the ``layout`` option to ``this`` to make a specific entry define
+the track layout.
+
+Example::
+
+    # mpv EDL v0
+    file_with_2_streams.ts,5,240
+    file_with_5_streams.mkv,0,90,layout=this
+
+The way the different virtual EDL tracks are associated with the per-segment
+ones is highly implementation-defined, and uses a heuristic. If a segment is
+missing a track, there will be a "hole", and bad behavior may result. Improving
+this is subject to further development (due to being fringe cases, they don't
+have a high priority).
+
+If future versions of mpv change this again, this option may be ignored.
+
+Syntax of EDL URIs
+==================
+
+mpv accepts inline EDL data in form of ``edl://`` URIs. Other than the
+header, the syntax is exactly the same. It's far more convenient to use ``;``
+instead of line breaks, but that is orthogonal.
+
+Example: ``edl://f1.mkv,length=5,start=10;f2.mkv,30,20;f3.mkv``
diff --git a/DOCS/encoding.rst b/DOCS/encoding.rst
new file mode 100644
index 0000000..9c6c067
--- /dev/null
+++ b/DOCS/encoding.rst
@@ -0,0 +1,155 @@
+General usage
+=============
+
+::
+
+  mpv infile --o=outfile [--of=outfileformat] [--ofopts=formatoptions] [--orawts] \
+    [(any other mpv options)] \
+    --ovc=outvideocodec [--ovcopts=outvideocodecoptions] \
+    --oac=outaudiocodec [--oacopts=outaudiocodecoptions]
+
+Help for these options is provided if giving help as parameter, as in::
+
+  mpv --ovc=help
+
+The suboptions of these generally are identical to ffmpeg's (as option parsing
+is simply delegated to ffmpeg). The option --ocopyts enables copying timestamps
+from the source as-is, instead of fixing them to match audio playback time
+(note: this doesn't work with all output container formats); --orawts even turns
+off discontinuity fixing.
+
+Note that if neither --ofps nor --oautofps is specified, VFR encoding is assumed
+and the time base is 24000fps. --oautofps sets --ofps to a guessed fps number
+from the input video. Note that not all codecs and not all formats support VFR
+encoding, and some which do have bugs when a target bitrate is specified - use
+--ofps or --oautofps to force CFR encoding in these cases.
+
+Of course, the options can be stored in a profile, like this .config/mpv/mpv.conf
+section::
+
+  [myencprofile]
+  vf-add = scale=480:-2
+  ovc = libx264
+  ovcopts-add = preset=medium
+  ovcopts-add = tune=fastdecode
+  ovcopts-add = crf=23
+  ovcopts-add = maxrate=1500k
+  ovcopts-add = bufsize=1000k
+  ovcopts-add = rc_init_occupancy=900k
+  ovcopts-add = refs=2
+  ovcopts-add = profile=baseline
+  oac = aac
+  oacopts-add = b=96k
+
+It's also possible to define default encoding options by putting them into
+the section named ``[encoding]``. (This behavior changed after mpv 0.3.x. In
+mpv 0.3.x, config options in the default section / no section were applied
+to encoding. This is not the case anymore.)
+
+One can then encode using this profile using the command::
+
+  mpv infile --o=outfile.mp4 --profile=myencprofile
+
+Some example profiles are provided in a file
+etc/encoding-profiles.conf; as for this, see below.
+
+
+Encoding examples
+=================
+
+These are some examples of encoding targets this code has been used and tested
+for.
+
+Typical MPEG-4 Part 2 ("ASP", "DivX") encoding, AVI container::
+
+  mpv infile --o=outfile.avi \
+    --vf=fps=25 \
+    --ovc=mpeg4 --ovcopts=qscale=4 \
+    --oac=libmp3lame --oacopts=b=128k
+
+Note: AVI does not support variable frame rate, so the fps filter must be used.
+The frame rate should ideally match the input (25 for PAL, 24000/1001 or
+30000/1001 for NTSC)
+
+Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, Matroska (MKV) container::
+
+  mpv infile --o=outfile.mkv \
+    --ovc=libx264 --ovcopts=preset=medium,crf=23,profile=baseline \
+    --oac=libopus --oacopts=qscale=3
+
+Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, MPEG-4 (MP4) container::
+
+  mpv infile --o=outfile.mp4 \
+    --ovc=libx264 --ovcopts=preset=medium,crf=23,profile=baseline \
+    --oac=aac --oacopts=b=128k
+
+Typical VP8 encoding, WebM (restricted Matroska) container::
+
+  mpv infile -o outfile.mkv \
+    --of=webm \
+    --ovc=libvpx --ovcopts=qmin=6,b=1000000k \
+    --oac=libopus --oacopts=qscale=3
+
+
+Device targets
+==============
+
+As the options for various devices can get complex, profiles can be used.
+
+An example profile file for encoding is provided in
+etc/encoding-profiles.conf in the source tree. This file is installed and loaded
+by default. If you want to modify it, you can replace and it with your own copy
+by doing::
+
+  mkdir -p ~/.mpv
+  cp /etc/mpv/encoding-profiles.conf ~/.mpv/encoding-profiles.conf
+
+Keep in mind that the default profile is the playback one. If you want to add
+options that apply only in encoding mode, put them into a ``[encoding]``
+section.
+
+Refer to the top of that file for more comments - in a nutshell, the following
+options are added by it::
+
+  --profile=enc-to-dvdpal      # DVD-Video PAL, use dvdauthor -v pal+4:3 -a ac3+en
+  --profile=enc-to-dvdntsc     # DVD-Video NTSC, use dvdauthor -v ntsc+4:3 -a ac3+en
+  --profile=enc-to-bb-9000     # MP4 for Blackberry Bold 9000
+  --profile=enc-to-nok-6300    # 3GP for Nokia 6300
+  --profile=enc-to-psp         # MP4 for PlayStation Portable
+  --profile=enc-to-iphone      # MP4 for iPhone
+  --profile=enc-to-iphone-4    # MP4 for iPhone 4 (double res)
+  --profile=enc-to-iphone-5    # MP4 for iPhone 5 (even larger res)
+
+You can encode using these with a command line like::
+
+  mpv infile --o=outfile.mp4 --profile=enc-to-bb-9000
+
+Of course, you are free to override options set by these profiles by specifying
+them after the -profile option.
+
+
+What works
+==========
+
+* Encoding at variable frame rate (default)
+* Encoding at constant frame rate using --vf=fps=RATE
+* 2-pass encoding (specify flags=+pass1 in the first pass's --ovcopts, specify
+  flags=+pass2 in the second pass)
+* Hardcoding subtitles using vobsub, ass or srt subtitle rendering (just
+  configure mpv for the subtitles as usual)
+* Hardcoding any other mpv OSD (e.g. time codes, using --osdlevel=3 and
+  --vf=expand=::::1)
+* Encoding directly from a DVD, network stream, webcam, or any other source
+  mpv supports
+* Using x264 presets/tunings/profiles (by using profile=, tune=, preset= in the
+  --ovcopts)
+* Deinterlacing/Inverse Telecine with any of mpv's filters for that
+* Audio file converting: mpv --o=outfile.m4a infile.flac --no-video
+  --oac=aac --oacopts=b=320k
+
+What does not work yet
+======================
+
+* 3-pass encoding (ensuring constant total size and bitrate constraints while
+  having VBR audio; mencoder calls this "frameno")
+* Direct stream copy
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
new file mode 100644
index 0000000..f59f890
--- /dev/null
+++ b/DOCS/interface-changes.rst
@@ -0,0 +1,982 @@
+Introduction
+============
+
+mpv provides access to its internals via the following means:
+
+- options
+- commands
+- properties
+- events
+- hooks
+
+The sum of these mechanisms is sometimes called command interface.
+
+All of these are important for interfacing both with end users and API users
+(which include Lua scripts, libmpv, and the JSON IPC). As such, they constitute
+a large part of the user interface and APIs.
+
+Also see compatibility.rst.
+
+This document lists changes to them. New changes are added to the top. Usually,
+only incompatible or important changes are mentioned. New options/commands/etc.
+are not always listed.
+
+Interface changes
+=================
+
+::
+
+ --- mpv 0.37.0 ---
+    - `--save-position-on-quit` and its associated commands now store state files
+      in %LOCALAPPDATA% instead of %APPDATA% directory by default on Windows.
+    - change `--subs-with-matching-audio` default from `no` to `yes`
+    - change `--subs-fallback` default from `no` to `default`
+    - add the `--hdr-peak-percentile` option
+    - include `--hdr-peak-percentile` in the `gpu-hq` profile
+    - change `--audiotrack-pcm-float` default from `no` to `yes`
+    - add video-params/aspect-name
+    - change type of `--sub-pos` to float
+    - The remaining time printed in the terminal is now adjusted for speed by default.
+      You can disable this with `--no-term-remaining-playtime`.
+    - add `playlist-path` and `playlist/N/playlist-path` properties
+    - add `--x11-wid-title` option
+    - add `--libplacebo-opts` option
+    - add `--audio-file-exts`, `--cover-art-auto-exts`, and `--sub-auto-exts`
+    - change `slang` default back to NULL
+    - remove special handling of the `auto` value from `--alang/slang/vlang` options
+    - add `--subs-match-os-language` as a replacement for `--slang=auto`
+    - add `always` option to `--subs-fallback-forced`
+    - remove `auto` choice from `--sub-forced-only`
+    - remove `auto-forced-only` property
+    - rename `--sub-forced-only` to `--sub-forced-events-only`
+    - remove `sub-forced-only-cur` property (`--sub-forced-events-only` is a replacement)
+    - remove deprecated `video-aspect` property
+    - add `--video-crop`
+    - add `video-params/crop-[w,h,x,y]`
+    - remove `--tone-mapping-mode`
+    - change `--subs-fallback-forced` so that it works alongside `--slang`
+    - add `--icc-3dlut-size=auto` and make it the default
+    - add `--scale=ewa_lanczos4sharpest`
+    - remove `--scale-wblur`, `--cscale-wblur`, `--dscale-wblur`, `--tscale-wblur`
+    - remove `bcspline` filter (`bicubic` is now the same as `bcspline`)
+    - rename `--cache-dir` and `--cache-unlink-files` to `--demuxer-cache-dir` and
+      `--demuxer-cache-unlink-files`
+    - enable `--correct-downscaling`, `--linear-downscaling`, `--sigmoid-upscaling`
+    - `--cscale` defaults to `--scale` if not defined
+    - change `--tscale` default to `oversample`
+    - change `--dither-depth` to `auto`
+    - deprecate `--profile=gpu-hq`, add `--profile=<fast|high-quality>`
+    - change `--dscale` default to `hermite`
+    - update defaults to `--hdr-peak-decay-rate=20`, `--hdr-scene-threshold-low=1.0`,
+      `--hdr-scene-threshold-high=3.0`
+    - update defaults to `--deband-threshold=48`, `--deband-grain=32`
+    - add `--directory-mode=auto` and make it the default
+    - remove deprecated `--profile=opengl-hq`
+    - remove several legacy fallbacks for old deprecated options (now they will just
+      error out like normal)
+    - remove deprecated `drop-frame-count` and `vo-drop-frame-count` property aliases
+    - remove the ability to write to the `display-fps` property (use `override-display-fps`
+      instead)
+    - writing the current value to playlist-pos will no longer restart playback (use
+      `playlist-play-index` instead)
+    - remove deprecated `--oaoffset`, `--oafirst`, `--ovoffset`, `--ovfirst`,
+      `--demuxer-force-retry-on-eof`, `--fit-border` options
+    - remove deprecated `--record-file` option
+    - remove deprecated `--vf-defaults` and `--af-defaults` options
+    - `--drm-connector` no longer allows selecting the card number (use `--drm-device`
+      instead)
+    - add `--title-bar` option
+    - add `--window-corners` option
+    - rename `--cdrom-device` to `--cdda-device`
+    - remove `--scale-cutoff`, `--cscale-cutoff`, `--dscale-cutoff`, `--tscale-cutoff`
+    - remove `--scaler-lut-size`
+    - deprecate shared-script-properties (user-data is a replacement)
+    - add `--backdrop-type` option
+    - add `--window-affinity` option
+    - `--config-dir` no longer forces cache and state files to also reside in there
+    - deprecate `--demuxer-cue-codepage` in favor of `--metadata-codepage`
+    - change the default of `metadata-codepage` to `auto`
+    - add `playlist-next-playlist` and `playlist-prev-playlist` commands
+    - change `video-codec` to show description or name, not both
+    - deprecate `--cdda-toc-bias` option, offsets are always checked now
+    - disable `--allow-delayed-peak-detect` by default
+    - rename `--fps` to `--container-fps-override`
+    - rename `--override-display-fps` to `--display-fps-override`
+    - rename `--sub-ass-force-style` to `--sub-ass-style-overrides`
+    - alias `--screenshot-directory` to `--screenshot-dir`
+    - alias `--watch-later-directory` to `--watch-later-dir`
+    - rename `--play-dir` to `--play-direction`
+    - `--js-memory-report` is now used for enabling memory reporting for javascript
+      scripts
+    - drop support for `-del` syntax for list options
+    - `--demuxer-hysteresis-secs` now respects `--cache-secs` and/or
+      `--demuxer-readahead-secs` as well
+    - add hdr metadata to `video-params` property
+    - add `--target-gamut`
+    - change the way display names are retrieved on macOS, usage of options and properties
+      `--fs-screen-name`, `--screen-name` and `display-names` needs to be adjusted
+    - remove OpenGL cocoa backend that was deprecated in 0.29
+    - remove `border`, `fullscreen`, `ontop`, `osd-level` and `pause`
+      from default `--watch-later-options`
+    - add `video-*` and `secondary-sub-visibility` to default `--watch-later-options`
+ --- mpv 0.36.0 ---
+    - add `--target-contrast`
+    - Target luminance value is now also applied when ICC profile is used.
+      `--icc-use-luma` has been added to use ICC profile luminance value.
+      If target luminance and ICC luminance is not used, old behavior apply,
+      defaulting to 203 nits. (Only applies for `--vo=gpu-next`)
+    - `playlist/N/title` gets set upon opening the file if it wasn't already set
+      and a title is available.
+    - add the `--vo=kitty` video output driver, as well as the options
+      `--vo-kitty-cols`, `--vo-kitty-rows`, `--vo-kitty-width`,
+      `--vo-kitty-height`, `--vo-kitty-left`, `--vo-kitty-top`,
+      `--vo-kitty-config-clear`, `--vo-kitty-alt-screen` and
+      `--vo-kitty-use-shm`
+    - add `--force-render`
+    - add `--vo-sixel-config-clear`, `--vo-sixel-alt-screen` and
+      `--vo-sixel-buffered`
+    - add `--wayland-content-type`
+    - deprecate `--vo-sixel-exit-clear` and alias it to
+      `--vo-sixel-alt-screen`
+    - deprecate `--drm-atomic`
+    - add `--demuxer-hysteresis-secs`
+    - add `--video-sync=display-tempo`
+    - the `start` option is no longer unconditionally written by
+      watch-later. It is still written by default but you may
+      need to explicitly add `start` depending on how you have
+      `--watch-later-options` configured.
+    - add `--vd-lavc-dr=auto` and make it the default
+    - add support for the fractional scale protocol in wayland
+    - in wayland, hidpi window scaling now scales the window by the compositor's
+      dpi scale factor by default (can be disabled with --no-hidpi-window-scale
+      if fractional scaling support exists).
+    - change --screenshot-tag-colorspace default value from `no` to `yes`
+    - undeprecate vf_sub
+    - add `--tone-mapping=st2094-40` and `--tone-mapping=st2094-10`
+    - change `--screenshot-jxl-effort` default from `3` to `4`.
+    - add `--tone-mapping-visualize`
+    - change type of `--brightness`, `--saturation`, `--contrast`, `--hue` and
+      `--gamma` to float.
+    - add `platform` property
+    - add `--auto-window-resize`
+    - `--save-position-on-quit` and its associated commands now store state files in
+      the XDG_STATE_HOME directory by default. This only has an effect on linux/bsd
+      systems.
+    - mpv now implictly saves cache files in XDG_CACHE_HOME by default. This only has
+      an effect if the user enables options that would lead to cache being stored and
+      only makes a difference on linux/bsd systems.
+    - `--cache-on-disk` no longer requires explictly setting the `--cache-dir` option
+    - add `--icc-cache` and `--gpu-shader-cache` options to control whether or not to
+      save cache files for these features; explictly setting `--icc-cache-dir` and
+      `--gpu-shader-cache` is no longer required
+    - remove the `--tone-mapping-crosstalk` option
+    - add `--gamut-mapping-mode=perceptual|relative|saturation|absolute|linear`
+    - add `--corner-rounding` option
+    - change `--subs-with-matching-audio` default from `yes` to `no`
+    - change `--slang` default from blank to `auto`
+    - add `--input-cursor-passthrough` option to allow pointer events to completely
+      passthrough the mpv window
+    - icc and gpu-shader cache are now saved by default (use --no-icc-shader-cache and
+      --no-gpu-shader-cache to disable)
+    - add `--directory-mode=recursive|lazy|ignore`
+    - `--hwdec=yes` is now mapped to `auto-safe` rather than `auto` (also used
+      by ctrl+h keybind)
+    - add `--hdr-contrast-recovery` and `--hdr-contrast-smoothness`
+    - include `--hdr-contrast-recovery` in the `gpu-hq` profile
+ --- mpv 0.35.0 ---
+    - add the `--vo=gpu-next` video output driver, as well as the options
+      `--allow-delayed-peak-detect`, `--builtin-scalers`,
+      `--interpolation-preserve` `--lut`, `--lut-type`, `--image-lut`,
+      `--image-lut-type` and `--target-lut` along with it.
+    - add `--target-colorspace-hint`
+    - add `--tone-mapping-crosstalk`
+    - add `--tone-mapping` options `auto`, `spline` and `bt.2446a`
+    - add `--inverse-tone-mapping`
+    - add `--gamut-mapping-mode`, replacing `--gamut-clipping` and `--gamut-warning`
+    - add `--tone-mapping-mode`, replacing `--tone-mapping-desaturate` and
+      `--tone-mapping-desaturate-exponent`.
+    - add `dolbyvision` sub-parameter to `format` video filter
+    - `--sub-visibility` no longer has any effect on secondary subtitles
+    - add `film-grain` sub-parameter to `format` video filter
+    - add experimental `--vo=dmabuf-wayland` video output driver
+    - add `--x11-present` for controlling whether to use xorg's present extension
+    - add `engine` option to the `rubberband` audio filter to support the new
+      engine introduced in rubberband 3.0.0. Defaults to `finer` (new engine).
+    - add `--wayland-configure-bounds` option
+    - deprecate `--gamma-factor`
+    - deprecate `--gamma-auto`
+    - remove `--vulkan-disable-events`
+    - add `--glsl-shader-opts`
+ --- mpv 0.34.0 ---
+    - deprecate selecting by card number with `--drm-connector`, add
+      `--drm-device` which can be used instead
+    - add `--screen-name` and `--fs-screen-name` flags to allow selecting the
+      screen by its name instead of the index
+    - add `--macos-geometry-calculation` to change the rectangle used for screen
+      position and size calculation. the old behavior used the whole screen,
+      which didn't take the menu bar and Dock into account. The new default
+      behaviour includes both. To revert to the old behavior set this to
+      `whole`.
+    - add an additional optional `albumart` argument to the `video-add` command,
+      which tells mpv to load the given video as album art.
+    - undeprecate `--cache-secs` option
+    - remove `--icc-contrast` and introduce `--icc-force-contrast`. The latter
+      defaults to the equivalent of the old `--icc-contrast=inf`, and can
+      instead be used to specifically set the contrast to any value.
+    - add a `--watch-later-options` option to allow configuring which
+      options quit-watch-later saves
+    - make `current-window-scale` writeable and use it in the default input.conf
+    - add `--input-builtin-bindings` flag to control loading of built-in key
+      bindings during start-up (default: yes).
+    - add ``track-list/N/image`` sub-property
+    - remove `--opengl-restrict` option
+    - js custom-init: use filename ~~/init.js instead of ~~/.init.js (dot)
+ --- mpv 0.33.0 ---
+    - add `--d3d11-exclusive-fs` flag to enable D3D11 exclusive fullscreen mode
+      when the player enters fullscreen.
+    - directories in ~/.mpv/scripts/ (or equivalent) now have special semantics
+      (see mpv Lua scripting docs)
+    - names starting with "." in ~/.mpv/scripts/ (or equivalent) are now ignored
+    - js modules: ~~/scripts/modules.js/ is no longer used, global paths can be
+      set with custom init (see docs), dir-scripts first look at <dir>/modules/
+    - the OSX bundle now logs to "~/Library/Logs/mpv.log" by default
+    - deprecate the --cache-secs option (once removed, the cache cannot be
+      limited by time anymore)
+    - remove deprecated legacy hook API ("hook-add", "hook-ack"). Use either the
+      libmpv API (mpv_hook_add(), mpv_hook_continue()), or the Lua scripting
+      wrappers (mp.add_hook()).
+    - improve how property change notifications are delivered on events and on
+      hooks. In particular, a hook event is only returned to a client after all
+      changes initiated before the hook point were delivered to the same client.
+      In addition, it should no longer happen that events and property change
+      notifications were interleaved in bad ways (it could happen that a
+      property notification delivered after an event contained a value that was
+      valid only before the event happened).
+    - the playlist-pos and playlist-pos-1 properties now can return and accept
+      -1, and are never unavailable. Out of range indexes are now accepted, but
+      behave like writing -1.
+    - the playlist-pos and playlist-pos-1 properties deprecate the current
+      behavior when writing back the current value to the property: currently,
+      this restarts playback, but in the future, it will do nothing.
+      Using the "playlist-play-index" command is recommended instead.
+    - add "playlist-play-index" command
+    - add playlist-current-pos, playlist-playing-pos properties
+    - Lua end-file events set the "error" field; this is deprecated; use the
+      "file_error" instead for this specific event. Scripts relying on the
+      "error" field for end-file will silently break at some point in the
+      future.
+    - remove deprecated --input-file option, add --input-ipc-client, which is
+      vaguely a replacement of the removed option, but not the same
+    - change another detail for track selection options (see --aid manpage
+      entry)
+    - reading loop-file property as native property or mpv_node will now return
+      "inf" instead of boolean true (also affects loop option)
+    - remove some --vo-direct3d-... options (it got dumbed down; use --vo=gpu)
+    - remove video-params/plane-depth property (was too vaguely defined)
+    - remove --video-sync-adrop-size option (implementation was changed, no
+      replacement for what this option did)
+    - undeprecate --video-sync=display-adrop
+    - deprecate legacy auto profiles (profiles starting with "extension." and
+      "protocol."). Use conditional auto profiles instead.
+    - the "subprocess" command does not connect spawned processes' stdin to
+      mpv's stdin anymore. Instead, stdin is connected to /dev/null by default.
+      To get the old behavior, set the "passthrough_stdin" argument to true.
+    - key/value list options do not accept ":" as item separator anymore,
+      only ",". This means ":" is always considered part of the value.
+    - remove deprecated --vo-vdpau-deint option
+    - add `delete-watch-later-config` command to complement
+      `write-watch-later-config`
+ --- mpv 0.32.0 ---
+    - change behavior when using legacy option syntax with options that start
+      with two dashes (``--`` instead of a ``-``). Now, using the recommended
+      syntax is required for options starting with ``--``, which means an option
+      value must be strictly passed after a ``=``, instead of as separate
+      argument. For example, ``--log-file f.txt`` was previously accepted and
+      behaved like ``--log-file=f.txt``, but now causes an error. Use of legacy
+      syntax that is still supported now prints a deprecation warning.
+ --- mpv 0.31.0 ---
+    - add `--resume-playback-check-mtime` to check consistent mtime when
+      restoring playback state.
+    - add `--d3d11-output-csp` to enable explicit selection of a D3D11
+      swap chain color space.
+    - the --sws- options and similar now affect vo_image and screenshot
+      conversion (does not matter as much for vo_gpu, which does most of this
+      with shaders)
+    - add a builtin "sw-fast" profile, which restores performance settings
+      for software video conversion. These were switched to higher quality since
+      mpv 0.30.0 (related to the previous changelog entry). This affects video
+      outputs like vo_x11 and vo_drm, and screenshots, but not much else.
+    - deprecate --input-file (there are no plans to remove this short-term,
+      but it will probably eventually go away <- that was a lie)
+    - deprecate --video-sync=display-adrop (might be removed if it's in the way;
+      undeprecated or readded if it's not too much of a problem)
+    - deprecate all input section commands (these will be changed/removed, as
+      soon as mpv internals do not require them anymore)
+    - remove deprecated --playlist-pos alias (use --playlist-start)
+    - deprecate --display-fps, introduce --override-display-fps. The display-fps
+      property now is unavailable if no VO exists (or the VO did not return a
+      display FPS), instead of returning the option value in this case. The
+      property will keep existing, but writing to it is deprecated.
+    - the vf/af properties now do not reject the set value anymore, even if
+      filter chain initialization fails. Instead, the vf/af options are always
+      set to the user's value, even if it does not reflect the "runtime" vf/af
+      chain.
+    - the vid/aid/sid/secondary-sid properties (and their aliases: "audio",
+      "video", "sub") will now allow setting any track ID; before this change,
+      only IDs of actually existing tracks could be set (the restriction was
+      active the MPV_EVENT_FILE_LOADED/"file-loaded" event was sent). Setting
+      an ID for which no track exists is equivalent to disabling it. Note that
+      setting the properties to non-existing tracks may report it as selected
+      track for a small time window, until it's forced back to "no". The exact
+      details how this is handled may change in the future.
+    - remove old Apple Remote support, including --input-appleremote
+    - add MediaPlayer support and remove the old Media Key event tap on macOS.
+      this possibly also re-adds the Apple Remote support
+    - the "edition" property now strictly returns the value of the option,
+      instead of the runtime value. The new "current-edition" property needs to
+      be queried to read the runtime-chosen edition. This is a breaking change
+      for any users which expected "edition" to return the runtime-chosen
+      edition at default settings (--edition=auto).
+    - the "window-scale" property now strictly returns the value of the option,
+      instead of the actual size of the window. The new "current-window-scale"
+      property needs to be queried to read the value as indicated by the current
+      window size. This is a breaking change.
+    - explicitly deprecate passing more than 1 item to "-add" suffix in key/value
+      options (for example --script-opts-add). This was actually always
+      deprecated, like with other list options, but the option parser did not
+      print a warning in this particular case.
+    - deprecate -del for list options (use -remove instead, which is by content
+      instead of by integer index)
+    - if `--fs` is used but `--fs-screen` is not set, mpv will now use `--screen`
+      instead.
+    - change the default of --hwdec to "no" on RPI. The default used to be "mmal"
+      specifically if 'Raspberry Pi support' was enabled at configure time
+      (equivalent to --enable-rpi). Use --hwdec=mmal to get the old behavior.
+ --- mpv 0.30.0 ---
+    - add `--d3d11-output-format` to enable explicit selection of a D3D11
+      swap chain format.
+    - rewrite DVB channel switching to use an integer value
+      `--dvbin-channel-switch-offset` for switching instead of the old
+      stream controls which are now gone. Cycling this property up or down will
+      change the offset to the channel which was initially tuned to.
+      Example for `input.conf`: `H cycle dvbin-channel-switch-offset up`,
+      `K cycle dvbin-channel-switch-offset down`.
+    - adapt `stream_dvb` to support writing to `dvbin-prog` at runtime
+      and also to consistently use dvbin-configuration over URI parameters
+      when provided
+    - add `--d3d11-adapter` to enable explicit selection of a D3D11 rendering
+      adapter by name.
+    - rename `--drm-osd-plane-id` to `--drm-draw-plane`, `--drm-video-plane-id` to
+      `--drm-drmprime-video-plane` and `--drm-osd-size` to `--drm-draw-surface-size`
+      to better reflect what the options actually control, that the values they
+      accept aren't actually internal DRM ID's (like with similar options in
+      ffmpeg's KMS support), and that the video plane is only used when the drmprime
+      overlay hwdec interop is active, with the video being drawn to the draw plane
+      otherwise.
+    - in addition to the above, the `--drm-draw-plane` and `--drm-drmprime-video-plane`
+      options now accept either an integer index, or the values primary or overlay.
+      `--drm-draw-plane` now defaults to primary and `--drm-drmprime-video-plane`
+      defaults to overlay. This should be similar to previous behavior on most drivers
+      due to how planes are usually sorted.
+    - rename --opensles-frames-per-buffer to --opensles-frames-per-enqueue to
+      better reflect its purpose. In the past it overrides the buffer size the AO
+      requests (but not the default/value of the generic --audio-buffer option).
+      Now it only guarantees that the soft buffer size will not be smaller than
+      itself while setting the size per Enqueue.
+    - add --opensles-buffer-size-in-ms, allowing user to tune the soft buffer size.
+      It overrides the --audio-buffer option unless it's set to 0 (with the default
+      being 250).
+    - remove `--linear-scaling`, replaced by `--linear-upscaling` and
+      `--linear-downscaling`. This means that `--sigmoid-upscaling` no longer
+      implies linear light downscaling as well, which was confusing.
+    - the built-in `gpu-hq` profile now includes` --linear-downscaling`.
+    - support for `--spirv-compiler=nvidia` has been removed, leaving `shaderc`
+      as the only option. The `--spirv-compiler` option itself has been marked
+      as deprecated, and may be removed in the future.
+    - split up `--tone-mapping-desaturate`` into strength + exponent, instead of
+      only using a single value (which previously just controlled the exponent).
+      The strength now linearly blends between the linear and nonlinear tone
+      mapped versions of a color.
+    - add --hdr-peak-decay-rate and --hdr-scene-threshold-low/high
+    - add --tone-mapping-max-boost
+    - ipc: require that "request_id" fields are integers. Other types are still
+      accepted for compatibility, but this will stop in the future. Also, if no
+      request_id is provided, 0 will be assumed.
+    - mpv_command_node() and mp.command_native() now support named arguments
+      (see manpage). If you want to use them, use a new version of the manpage
+      as reference, which lists the definitive names.
+    - edition and disc title switching will now fully reload playback (may have
+      consequences for scripts, client API, or when using file-local options)
+    - with the removal of the stream cache, the following properties and options were
+      dropped: `cache`, `cache-size`, `cache-free`, `cache-used`, `--cache-default`,
+      `--cache-initial`, `--cache-seek-min`, `--cache-backbuffer`, `--cache-file`,
+      `--cache-file-size`
+    - the --cache option does not take a number value anymore
+    - remove async playback abort hack. This may make it impossible to abort
+      playback if --demuxer-thread=no is forced.
+    - remove `--macos-title-bar-style`, replaced by `--macos-title-bar-material`
+      and `--macos-title-bar-appearance`.
+    - The default for `--vulkan-async-compute` has changed to `yes` from `no`
+      with the move to libplacebo as the back-end for vulkan rendering.
+    - Remove "disc-titles", "disc-title", "disc-title-list", and "angle"
+      properties. dvd:// does not support title ranges anymore.
+    - Remove all "tv-..." options and properties, along with the classic Linux
+      analog TV support.
+    - remove "program" property (no replacement)
+    - always prefer EGL over GLX, which helps with AMD/vaapi, but will break
+      vdpau with --vo=gpu - use --gpu-context=x11 to be able to use vdpau. This
+      does not affect --vo=vdpau or --hwdec=vdpau-copy.
+    - remove deprecated --chapter option
+    - deprecate --record-file
+    - add `--demuxer-cue-codepage`
+    - add ``track-list/N/demux-bitrate``, ``track-list/N/demux-rotation`` and
+      ``track-list/N/demux-par`` property
+    - Deprecate ``--video-aspect`` and add ``--video-aspect-override`` to
+      replace it. (The `video-aspect` option remains unchanged.)
+ --- mpv 0.29.0 ---
+    - drop --opensles-sample-rate, as --audio-samplerate should be used if desired
+    - drop deprecated --videotoolbox-format, --ff-aid, --ff-vid, --ff-sid,
+      --ad-spdif-dtshd, --softvol options
+    - fix --external-files: strictly never select any tracks from them, unless
+      explicitly selected (this may or may not be expected)
+    - --ytdl is now always enabled, even for libmpv
+    - add a number of --audio-resample-* options, which should from now on be
+      used instead of --af-defaults=lavrresample:...
+    - deprecate --vf-defaults and --af-defaults. These didn't work with the
+      lavfi bridge, so they have very little use left. The only potential use
+      is with af_lavrresample (going to be deprecated, --audio-resample-... set
+      its defaults), and various hw deinterlacing filters (like vf_vavpp), for
+      which you will have to stop using --deinterlace=yes, and instead use the
+      vf toggle commands and the filter enable/disable flag to customize it.
+    - deprecate --af=lavrresample. Use the ``--audio-resample-...`` options to
+      customize resampling, or the libavfilter ``--af=aresample`` filter.
+    - add --osd-on-seek
+    - remove outfmt sub-parameter from "format" video filter (no replacement)
+    - some behavior changes in the video filter chain, including:
+        - before, using an incompatible filter with hwdec would disable hwdec;
+          now it disables the filter at runtime instead
+        - inserting an incompatible filter with hwdec at runtime would refuse
+          to insert the filter; now it will add it successfully, but disables
+          the filter slightly later
+    - some behavior changes in the audio filter chain, including:
+        - a manually inserted lavrresample filter is not necessarily used for
+          sample format conversion anymore, so it's pretty useless
+        - changing playback speed will not respect --af-defaults anymore
+        - having libavfilter based filters after the scaletempo or rubberband
+          filters is not supported anymore, and may desync if playback speed is
+          changed (libavfilter does not support the metadata for playback speed)
+        - the lavcac3enc filter does not auto detach itself anymore; instead it
+          passes through the data after converting it to the sample rate and
+          channel configuration the ac3 encoder expects; also, if the audio
+          format changes midstream in a way that causes the filter to switch
+          between PCM and AC3 output, the audio output won't be reconfigured,
+          and audio playback will fail due to libswresample being unable to
+          convert between PCM and AC3 (Note: the responsible developer didn't
+          give a shit. Later changes might have improved or worsened this.)
+        - inserting a filter that changes the output sample format will not
+          reconfigure the AO - you need to run an additional "ao-reload"
+          command to force this if you want that
+        - using "strong" gapless audio (--gapless-audio=yes) can fail if the
+          audio formats are not convertible (such as switching between PCM and
+          AC3 passthrough)
+        - if filters do not pass through PTS values correctly, A/V sync can
+          result over time. Some libavfilter filters are known to be affected by
+          this, such as af_loudnorm, which can desync over time, depending on
+          how the audio track was muxed (af_lavfi's fix-pts suboption can help).
+    - remove out-format sub-parameter from "format" audio filter (no replacement)
+    - --lavfi-complex now requires uniquely named filter pads. In addition,
+      unconnected filter pads are not allowed anymore (that means every filter
+      pad must be connected either to another filter, or to a video/audio track
+      or video/audio output). If they are disconnected at runtime, the stream
+      will probably stall.
+    - rename --vo=opengl-cb to --vo=libmpv (goes in hand with the opengl-cb
+      API deprecation, see client-api-changes.rst)
+    - deprecate the OpenGL cocoa backend, option choice --gpu-context=cocoa
+      when used with --gpu-api=opengl (use --vo=libmpv)
+    - make --deinterlace=yes always deinterlace, instead of trying to check
+      certain unreliable video metadata. Also flip the defaults of all builtin
+      HW deinterlace filters to always deinterlace.
+    - change vf_vavpp default to use the best deinterlace algorithm by default
+    - remove a compatibility hack that allowed CLI aliases to be set as property
+      (such as "sub-file"), deprecated in mpv 0.26.0
+    - deprecate the old command based hook API, and introduce a proper C API
+      (the high level Lua API for this does not change)
+    - rename the the lua-settings/ config directory to script-opts/
+    - the way the player waits for scripts getting loaded changes slightly. Now
+      scripts are loaded in parallel, and block the player from continuing
+      playback only in the player initialization phase. It could change again in
+      the future. (This kind of waiting was always a feature to prevent that
+      playback is started while scripts are only half-loaded.)
+    - deprecate --ovoffset, --oaoffset, --ovfirst, --oafirst
+    - remove the following encoding options: --ocopyts (now the default, old
+      timestamp handling is gone), --oneverdrop (now default), --oharddup (you
+      need to use --vf=fps=VALUE), --ofps, --oautofps, --omaxfps
+    - remove --video-stereo-mode. This option was broken out of laziness, and
+      nobody wants to fix it. Automatic 3D down-conversion to 2D is also broken,
+      although you can just insert the stereo3d filter manually. The obscurity
+      of 3D content doesn't justify such an option anyway.
+    - change cycle-values command to use the current value, instead of an
+      internal counter that remembered the current position.
+    - remove deprecated ao/vo auto profiles. Consider using scripts like
+      auto-profiles.lua instead.
+    - --[c]scale-[w]param[1|2] and --tone-mapping-param now accept "default",
+      and if set to that value, reading them as property will also return
+      "default", instead of float nan as in previous versions
+ --- mpv 0.28.0 ---
+    - rename --hwdec=mediacodec option to mediacodec-copy, to reflect
+      conventions followed by other hardware video decoding APIs
+    - drop previously deprecated --heartbeat-cmd and --heartbeat--interval
+      options
+    - rename --vo=opengl to --vo=gpu
+    - rename --opengl-backend to --gpu-context
+    - rename --opengl-shaders to --glsl-shaders
+    - rename --opengl-shader-cache-dir to --gpu-shader-cache-dir
+    - rename --opengl-tex-pad-x/y to --gpu-tex-pad-x/y
+    - rename --opengl-fbo-format to --fbo-format
+    - rename --opengl-gamma to --gamma-factor
+    - rename --opengl-debug to --gpu-debug
+    - rename --opengl-sw to --gpu-sw
+    - rename --opengl-vsync-fences to --swapchain-depth, and the interpretation
+      slightly changed. Now defaults to 3.
+    - rename the built-in profile `opengl-hq` to `gpu-hq`
+    - the semantics of --opengl-es=yes are slightly changed -> now requires GLES
+    - remove the (deprecated) alias --gpu-context=drm-egl
+    - remove the (deprecated) --vo=opengl-hq
+    - remove --opengl-es=force2 (use --opengl-es=yes --opengl-restrict=300)
+    - the --msg-level option now affects --log-file
+    - drop "audio-out-detected-device" property - this was unavailable on all
+      audio output drivers for quite a while (coreaudio used to provide it)
+    - deprecate --videotoolbox-format (use --hwdec-image-format, which affects
+      most other hwaccels)
+    - remove deprecated --demuxer-max-packets
+    - remove most of the deprecated audio and video filters
+    - remove the deprecated --balance option/property
+    - rename the --opengl-hwdec-interop option to --gpu-hwdec-interop, and
+      change some of its semantics: extend it take the strings "auto" and
+      "all". "all" loads all backends. "auto" behaves like "all" for
+      vo_opengl_cb, while on vo_gpu it loads nothing, but allows on demand
+      loading by the decoder. The empty string as option value behaves like
+      "auto". Old --hwdec values do not work anymore.
+      This option is hereby declared as unstable and may change any time - its
+      old use is deprecated, and it has very little use outside of debugging
+      now.
+    - change the --hwdec option from a choice to a plain string (affects
+      introspection of the option/property), also affects some properties
+    - rename --hwdec=rpi to --hwdec=mmal, same for the -copy variant (no
+      backwards compatibility)
+    - deprecate the --ff-aid, --ff-vid, --ff-sid options and properties (there is
+      no replacement, but you can manually query the track property and use the
+      "ff-index" field to find the mpv track ID to imitate this behavior)
+    - rename --no-ometadata to --no-ocopy-metadata
+ --- mpv 0.27.0 ---
+    - drop previously deprecated --field-dominance option
+    - drop previously deprecated "osd" command
+    - remove client API compatibility handling for "script", "sub-file",
+      "audio-file", "external-file" (these cases used to log a deprecation
+      warning)
+    - drop deprecated --video-aspect-method=hybrid option choice
+    - rename --hdr-tone-mapping to --tone-mapping (and generalize it)
+    - --opengl-fbo-format changes from a choice to a string. Also, its value
+      will be checked only on renderer initialization, rather than when the
+      option is set.
+    - Using opengl-cb now always assumes 8 bit per component depth, and dithers
+      to this size. Before, it tried to figure out the depth of the first
+      framebuffer that was ever passed to the renderer. Having GL framebuffers
+      with a size larger than 8 bit per component is quite rare. If you need
+      it, set the --dither-depth option instead.
+    - --lavfi-complex can now be set during runtime. If you set this in
+      expectation it would be applied only after a reload, you might observe
+      weird behavior.
+    - add --track-auto-selection to help with scripts/applications that
+      make exclusive use of --lavfi-complex.
+    - undeprecate --loop, and map it from --loop-playlist to --loop-file (the
+      deprecation was to make sure no API user gets broken by a sudden behavior
+      change)
+    - remove previously deprecated vf_eq
+    - remove that hardware deinterlace filters (vavpp, d3d11vpp, vdpaupp)
+      changed their deinterlacing-enabled setting depending on what the
+      --deinterlace option or property was set to. Now, a filter always does
+      what its filter options and defaults imply. The --deinterlace option and
+      property strictly add/remove its own filters. For example, if you run
+      "mpv --vf=vavpp --deinterlace=yes", this will insert another, redundant
+      filter, which is probably not what you want. For toggling a deinterlace
+      filter manually, use the "vf toggle" command, and do not set the
+      deinterlace option/property. To customize the filter that will be
+      inserted automatically, use --vf-defaults. Details how this works will
+      probably change in the future.
+    - remove deinterlace=auto (this was not deprecated, but had only a very
+      obscure use that stopped working with the change above. It was also
+      prone to be confused with a feature not implemented by it: auto did _not_
+      mean that deinterlacing was enabled on demand.)
+    - add shortened mnemonic names for mouse button bindings, eg. mbtn_left
+      the old numeric names (mouse_btn0) are deprecated
+    - remove mouse_btn3_dbl and up, since they are only generated for buttons
+      0-2 (these now print an error when sent from the 'mouse' command)
+    - rename the axis bindings to wheel_up/down/etc. axis scrolling and mouse
+      wheel scrolling are now conceptually the same thing
+      the old axis_up/down names remain as deprecated aliases
+ --- mpv 0.26.0 ---
+    - remove remaining deprecated audio device options, like --alsa-device
+      Some of them were removed in earlier releases.
+    - introduce --replaygain... options, which replace the same functionality
+      provided by the deprecated --af=volume:replaygain... mechanism.
+    - drop the internal "mp-rawvideo" codec (used by --demuxer=rawvideo)
+    - rename --sub-ass-style-override to --sub-ass-override, and rename the
+      `--sub-ass-override=signfs` setting to `--sub-ass-override=scale`.
+    - change default of --video-aspect-method to "bitstream". The "hybrid"
+      method (old default) is deprecated.
+    - remove property "video-params/nom-peak"
+    - remove option --target-brightness
+    - replace vf_format's `peak` suboption by `sig-peak`, which is relative to
+      the reference white level instead of in cd/m^2
+    - renamed the TRCs `st2084` and `std-b67` to `pq` and `hlg` respectively
+    - the "osd" command is deprecated (use "cycle osd-level")
+    - --field-dominance is deprecated (use --vf=setfield=bff or tff)
+    - --really-quiet subtle behavior change
+    - the deprecated handling of setting "no-" options via client API is dropped
+    - the following options change to append-by-default (and possibly separator):
+        --script
+      also, the following options are deprecated:
+        --sub-paths => --sub-file-paths
+      the following options are deprecated for setting via API:
+        "script" (use "scripts")
+        "sub-file" (use "sub-files")
+        "audio-file" (use "audio-files")
+        "external-file" (use "external-files")
+        (the compatibility hacks for this will be removed after this release)
+    - remove property `vo-performance`, and add `vo-passes` as a more general
+      replacement
+    - deprecate passing multiple arguments to -add/-pre options (affects the
+      vf/af commands too)
+    - remove --demuxer-lavf-cryptokey. Use --demux-lavf-o=cryptokey=<hex> or
+      --demux-lavf-o=decryption_key=<hex> instead (whatever fits your situation).
+    - rename --opengl-dumb-mode=no to --opengl-dumb-mode=auto, and make `no`
+      always disable it (unless forced on by hardware limitation).
+    - generalize --scale-clamp, --cscale-clamp etc. to accept a float between
+      0.0 and 1.0 instead of just being a flag. A value of 1.0 corresponds to
+      the old `yes`, and a value of 0.0 corresponds to the old `no`.
+ --- mpv 0.25.0 ---
+    - remove opengl-cb dxva2 dummy hwdec interop
+      (see git "vo_opengl: remove dxva2 dummy hwdec backend")
+    - remove ppm, pgm, pgmyuv, tga choices from the --screenshot-format and
+      --vo-image-format options
+    - the "jpeg" choice in the option above now leads to a ".jpg" file extension
+    - --af=drc is gone (you can use e.g. lavfi/acompressor instead)
+    - remove image_size predefined uniform from OpenGL user shaders. Use
+      input_size instead
+    - add --sub-filter-sdh
+    - add --sub-filter-sdh-harder
+    - remove --input-app-events option (macOS)
+    - deprecate most --vf and --af filters. Only some filters not in libavfilter
+      will be kept.
+      Also, you can use libavfilter filters directly (e.g. you can use
+      --vf=name=opts instead of --vf=lavfi=[name=opts]), as long as the
+      libavfilter filter's name doesn't clash with a mpv builtin filter.
+      In the long term, --vf/--af syntax might change again, but if it does, it
+      will switch to libavfilter's native syntax. (The above mentioned direct
+      support for lavfi filters still has some differences, such as how strings
+      are escaped.) If this happens, the non-deprecated builtin filters might be
+      moved to "somewhere else" syntax-wise.
+    - deprecate --loop - after a deprecation period, it will be undeprecated,
+      but changed to alias --loop-file
+    - add --keep-open-pause=no
+    - deprecate --demuxer-max-packets
+    - change --audio-file-auto default from "exact" to "no" (mpv won't load
+      files with the same filename as the video, but different extension, as
+      audio track anymore)
+ --- mpv 0.24.0 ---
+    - deprecate --hwdec-api and replace it with --opengl-hwdec-interop.
+      The new option accepts both --hwdec values, as well as named backends.
+      A minor difference is that --hwdec-api=no (which used to be the default)
+      now actually does not preload any interop layer, while the new default
+      ("") uses the value of --hwdec.
+    - drop deprecated --ad/--vd features
+    - drop deprecated --sub-codepage syntax
+    - rename properties:
+        - "drop-frame-count" to "decoder-frame-drop-count"
+        - "vo-drop-frame-count" to "frame-drop-count"
+      The old names still work, but are deprecated.
+    - remove the --stream-capture option and property. No replacement.
+      (--record-file might serve as alternative)
+    - add --sub-justify
+    - add --sub-ass-justify
+    - internally there's a different way to enable the demuxer cache now
+      it can be auto-enabled even if the stream cache remains disabled
+ --- mpv 0.23.0 ---
+    - remove deprecated vf_vdpaurb (use "--hwdec=vdpau-copy" instead)
+    - the following properties now have new semantics:
+        - "demuxer" (use "current-demuxer")
+        - "fps" (use "container-fps")
+        - "idle" (use "idle-active")
+        - "cache" (use "cache-percent")
+        - "audio-samplerate" (use "audio-params/samplerate")
+        - "audio-channels" (use "audio-params/channel-count")
+        - "audio-format" (use "audio-codec-name")
+      (the properties equivalent to the old semantics are in parentheses)
+    - remove deprecated --vo and --ao sub-options (like --vo=opengl:...), and
+      replace them with global options. A somewhat complete list can be found
+      here: https://github.com/mpv-player/mpv/wiki/Option-replacement-list#mpv-0210
+    - remove --vo-defaults and --ao-defaults as well
+    - remove deprecated global sub-options (like -demuxer-rawaudio format=...),
+      use flat options (like --demuxer-rawaudio-format=...)
+    - the --sub-codepage option changes in incompatible ways:
+        - detector-selection and fallback syntax is deprecated
+        - enca/libguess are removed and deprecated (behaves as if they hadn't
+          been compiled-in)
+        - --sub-codepage=<codepage> does not force the codepage anymore
+          (this requires different and new syntax)
+    - remove --fs-black-out-screens option for macOS
+    - change how spdif codecs are selected. You can't enable spdif passthrough
+      with --ad anymore. This was deprecated; use --audio-spdif instead.
+    - deprecate the "family" selection with --ad/--vd
+      forcing/excluding codecs with "+", "-", "-" is deprecated as well
+    - explicitly mark --ad-spdif-dtshd as deprecated (it was done so a long time
+      ago, but it didn't complain when using the option)
+ --- mpv 0.22.0 ---
+    - the "audio-device-list" property now sets empty device description to the
+      device name as a fallback
+    - add --hidpi-window-scale option for macOS
+    - add audiounit audio output for iOS
+    - make --start-time work with --rebase-start-time=no
+    - add --opengl-early-flush=auto mode
+    - add --hwdec=vdpau-copy, deprecate vf_vdpaurb
+    - add tct video output for true-color and 256-color terminals
+ --- mpv 0.21.0 ---
+    - unlike in older versions, setting options at runtime will now take effect
+      immediately (see for example issue #3281). On the other hand, it will also
+      do runtime verification and reject option changes that do not work
+      (example: setting the "vf" option to a filter during playback, which fails
+      to initialize - the option value will remain at its old value). In general,
+      "set name value" should be mostly equivalent to "set options/name value"
+      in cases where the "name" property is not deprecated and "options/name"
+      exists - deviations from this are either bugs, or documented as caveats
+      in the "Inconsistencies between options and properties" manpage section.
+    - deprecate _all_ --vo and --ao suboptions. Generally, all suboptions are
+      replaced by global options, which do exactly the same. For example,
+      "--vo=opengl:scale=nearest" turns into "--scale=nearest". In some cases,
+      the global option is prefixed, e.g. "--vo=opengl:pbo" turns into
+      "--opengl-pbo".
+      Most of the exact replacements are documented here:
+        https://github.com/mpv-player/mpv/wiki/Option-replacement-list
+    - remove --vo=opengl-hq. Set --profile=opengl-hq instead. Note that this
+      profile does not force the VO. This means if you use the --vo option to
+      set another VO, it won't work. But this also means it can be used with
+      opengl-cb.
+    - remove the --vo=opengl "pre-shaders", "post-shaders" and "scale-shader"
+      sub-options: they were deprecated in favor of "user-shaders"
+    - deprecate --vo-defaults (no replacement)
+    - remove the vo-cmdline command. You can set OpenGL renderer options
+      directly via properties instead.
+    - deprecate the device/sink options on all AOs. Use --audio-device instead.
+    - deprecate "--ao=wasapi:exclusive" and "--ao=coreaudio:exclusive",
+      use --audio-exclusive instead.
+    - subtle changes in how "--no-..." options are treated mean that they are
+      not accessible under "options/..." anymore (instead, these are resolved
+      at parsing time). This does not affect options which start with "--no-",
+      but do not use the mechanism for negation options.
+      (Also see client API change for API version 1.23.)
+    - rename the following properties
+        - "demuxer" -> "current-demuxer"
+        - "fps" -> "container-fps"
+        - "idle" -> "idle-active"
+        - "cache" -> "cache-percent"
+      the old names are deprecated and will change behavior in mpv 0.23.0.
+    - remove deprecated "hwdec-active" and "hwdec-detected" properties
+    - deprecate the ao and vo auto-profiles (they never made any sense)
+    - deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead.
+      Change "--vo=direct3d" to always use shaders by default.
+    - deprecate --playlist-pos option, renamed to --playlist-start
+    - deprecate the --chapter option, as it is redundant with --start/--end,
+      and conflicts with the semantics of the "chapter" property
+    - rename --sub-text-* to --sub-* and --ass-* to --sub-ass-* (old options
+      deprecated)
+    - incompatible change to cdda:// protocol options: the part after cdda://
+      now always sets the device, not the span or speed to be played. No
+      separating extra "/" is needed. The hidden --cdda-device options is also
+      deleted (it was redundant with the documented --cdrom-device).
+    - deprecate --vo=rpi. It will be removed in mpv 0.23.0. Its functionality
+      was folded into --vo=opengl, which now uses RPI hardware decoding by
+      treating it as a hardware overlay (without applying GL filtering). Also
+      to be changed in 0.23.0: the --fs flag will be reset to "no" by default
+      (like on the other platforms).
+    - deprecate --mute=auto (informally has been since 0.18.1)
+    - deprecate "resume" and "suspend" IPC commands. They will be completely
+      removed in 0.23.0.
+    - deprecate mp.suspend(), mp.resume(), mp.resume_all() Lua scripting
+      commands, as well as setting mp.use_suspend. They will be completely
+      removed in 0.23.0.
+    - the "seek" command's absolute seek mode will now interpret negative
+      seek times as relative from the end of the file (and clamps seeks that
+      still go before 0)
+    - add almost all options to the property list, meaning you can change
+      options without adding "options/" to the property name (a new section
+      has been added to the manpage describing some conflicting behavior
+      between options and properties)
+    - implement changing sub-speed during playback
+    - make many previously fixed options changeable at runtime (for example
+      --terminal, --osc, --ytdl, can all be enable/disabled after
+      mpv_initialize() - this can be extended to other still fixed options
+      on user requests)
+ --- mpv 0.20.0 ---
+    - add --image-display-duration option - this also means that image duration
+      is not influenced by --mf-fps anymore in the general case (this is an
+      incompatible change)
+ --- mpv 0.19.0 ---
+    - deprecate "balance" option/property (no replacement)
+ --- mpv 0.18.1 ---
+    - deprecate --heartbeat-cmd
+    - remove --softvol=no capability:
+        - deprecate --softvol, it now does nothing
+        - --volume, --mute, and the corresponding properties now always control
+          softvol, and behave as expected without surprises (e.g. you can set
+          them normally while no audio is initialized)
+        - rename --softvol-max to --volume-max (deprecated alias is added)
+        - the --volume-restore-data option and property are removed without
+          replacement. They were _always_ internal, and used for watch-later
+          resume/restore. Now --volume/--mute are saved directly instead.
+        - the previous point means resuming files with older watch-later configs
+          will print an error about missing --volume-restore-data (which you can
+          ignore), and will not restore the previous value
+        - as a consequence, volume controls will no longer control PulseAudio
+          per-application value, or use the system mixer's per-application
+          volume processing
+        - system or per-application volume can still be controlled with the
+          ao-volume and ao-mute properties (there are no command line options)
+ --- mpv 0.18.0 ---
+    - now ab-loops are active even if one of the "ab-loop-a"/"-b" properties is
+      unset ("no"), in which case the start of the file is used if the A loop
+      point is unset, and the end of the file for an unset B loop point
+    - deprecate --sub-ass=no option by --ass-style-override=strip
+      (also needs --embeddedfonts=no)
+    - add "hwdec-interop" and "hwdec-current" properties
+    - deprecated "hwdec-active" and "hwdec-detected" properties (to be removed
+      in mpv 0.20.0)
+    - choice option/property values that are "yes" or "no" will now be returned
+      as booleans when using the mpv_node functions in the client API, the
+      "native" property accessors in Lua, and the JSON API. They can be set as
+      such as well.
+    - the VO opengl fbo-format sub-option does not accept "rgb" or "rgba"
+      anymore
+    - all VO opengl prescalers have been removed (replaced by user scripts)
+ --- mpv 0.17.0 ---
+    - deprecate "track-list/N/audio-channels" property (use
+      "track-list/N/demux-channel-count" instead)
+    - remove write access to "stream-pos", and change semantics for read access
+    - Lua scripts now don't suspend mpv by default while script code is run
+    - add "cache-speed" property
+    - rename --input-unix-socket to --input-ipc-server, and make it work on
+      Windows too
+    - change the exact behavior of the "video-zoom" property
+    - --video-unscaled no longer disables --video-zoom and --video-aspect
+      To force the old behavior, set --video-zoom=0 and --video-aspect=0
+ --- mpv 0.16.0 ---
+    - change --audio-channels default to stereo (use --audio-channels=auto to
+      get the old default)
+    - add --audio-normalize-downmix
+    - change the default downmix behavior (--audio-normalize-downmix=yes to get
+      the old default)
+    - VO opengl custom shaders must now use "sample_pixel" as function name,
+      instead of "sample"
+    - change VO opengl scaler-resizes-only default to enabled
+    - add VO opengl "interpolation-threshold" suboption (introduces new default
+      behavior, which can change e.g. ``--video-sync=display-vdrop`` to the
+      worse, but is usually what you want)
+    - make "volume" and "mute" properties changeable even if no audio output is
+      active (this gives not-ideal behavior if --softvol=no is used)
+    - add "volume-max" and "mixer-active" properties
+    - ignore --input-cursor option for events injected by input commands like
+      "mouse", "keydown", etc.
+ --- mpv 0.15.0 ---
+    - change "yadif" video filter defaults
+ --- mpv 0.14.0 ---
+    - vo_opengl interpolation now requires --video-sync=display-... to be set
+    - change some vo_opengl defaults (including changing tscale)
+    - add "vsync-ratio", "estimated-display-fps" properties
+    - add --rebase-start-time option
+      This is a breaking change to start time handling. Instead of making start
+      time handling an aspect of different options and properties (like
+      "time-pos" vs. "playback-time"), make it dependent on the new option. For
+      compatibility, the "time-start" property now always returns 0, so code
+      which attempted to handle rebasing manually will not break.
+ --- mpv 0.13.0 ---
+    - remove VO opengl-cb frame queue suboptions (no replacement)
+ --- mpv 0.12.0 ---
+    - remove --use-text-osd (useless; fontconfig isn't a requirement anymore,
+      and text rendering is also lazily initialized)
+    - some time properties (at least "playback-time", "time-pos",
+      "time-remaining", "playtime-remaining") now are unavailable if the time
+      is unknown, instead of just assuming that the internal playback position
+      is 0
+    - add --audio-fallback-to-null option
+    - replace vf_format outputlevels suboption with "video-output-levels" global
+      property/option; also remove "colormatrix-output-range" property
+    - vo_opengl: remove sharpen3/sharpen5 scale filters, add sharpen sub-option
+ --- mpv 0.11.0 ---
+    - add "af-metadata" property
+ --- mpv 0.10.0 ---
+    - add --video-aspect-method option
+    - add --playlist-pos option
+    - add --video-sync* options
+      "display-sync-active" property
+      "vo-missed-frame-count" property
+      "audio-speed-correction" and "video-speed-correction" properties
+    - remove --demuxer-readahead-packets and --demuxer-readahead-bytes
+      add --demuxer-max-packets and --demuxer-max-bytes
+      (the new options are not replacement and have very different semantics)
+    - change "video-aspect" property: always settable, even if no video is
+      running; always return the override - if no override is set, return
+      the video's aspect ratio
+    - remove disc-nav (DVD, BD) related properties and commands
+    - add "option-info/<name>/set-locally" property
+    - add --cache-backbuffer; change --cache-default default to 75MB
+      the new total cache size is the sum of backbuffer and the cache size
+      specified by --cache-default or --cache
+    - add ``track-list/N/audio-channels`` property
+    - change --screenshot-tag-colorspace default value
+    - add --stretch-image-subs-to-screen
+    - add "playlist/N/title" property
+    - add --video-stereo-mode=no to disable auto-conversions
+    - add --force-seekable, and change default seekability in some cases
+    - add vf yadif/vavpp/vdpaupp interlaced-only suboptions
+      Also, the option is enabled by default (Except vf_yadif, which has
+      it enabled only if it's inserted by the deinterlace property.)
+    - add --hwdec-preload
+    - add ao coreaudio exclusive suboption
+    - add ``track-list/N/forced`` property
+    - add audio-params/channel-count and ``audio-params-out/channel-count props.
+    - add af volume replaygain-fallback suboption
+    - add video-params/stereo-in property
+    - add "keypress", "keydown", and "keyup" commands
+    - deprecate --ad-spdif-dtshd and enabling passthrough via --ad
+      add --audio-spdif as replacement
+    - remove "get_property" command
+    - remove --slave-broken
+    - add vo opengl custom shader suboptions (source-shader, scale-shader,
+      pre-shaders, post-shaders)
+    - completely change how the hwdec properties work:
+        - "hwdec" now reflects the --hwdec option
+        - "hwdec-detected" does partially what the old "hwdec" property did
+          (and also, "detected-hwdec" is removed)
+        - "hwdec-active" is added
+    - add protocol-list property
+    - deprecate audio-samplerate and audio-channels properties
+      (audio-params sub-properties are the replacement)
+    - add audio-params and audio-out-params properties
+    - deprecate "audio-format" property, replaced with "audio-codec-name"
+    - deprecate --media-title, replaced with --force-media-title
+    - deprecate "length" property, replaced with "duration"
+    - change volume property:
+        - the value 100 is now always "unchanged volume" - with softvol, the
+          range is 0 to --softvol-max, without it is 0-100
+        - the minimum value of --softvol-max is raised to 100
+    - remove vo opengl npot suboption
+    - add relative seeking by percentage to "seek" command
+    - add playlist_shuffle command
+    - add --force-window=immediate
+    - add ao coreaudio change-physical-format suboption
+    - remove vo opengl icc-cache suboption, add icc-cache-dir suboption
+    - add --screenshot-directory
+    - add --screenshot-high-bit-depth
+    - add --screenshot-jpeg-source-chroma
+    - default action for "rescan_external_files" command changes
+ --- mpv 0.9.0 ---
diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst
new file mode 100644
index 0000000..98f9a95
--- /dev/null
+++ b/DOCS/man/af.rst
@@ -0,0 +1,267 @@
+AUDIO FILTERS
+=============
+
+Audio filters allow you to modify the audio stream and its properties. The
+syntax is:
+
+``--af=...``
+    Setup a chain of audio filters. See ``--vf`` (`VIDEO FILTERS`_) for the
+    full syntax.
+
+.. note::
+
+    To get a full list of available audio filters, see ``--af=help``.
+
+    Also, keep in mind that most actual filters are available via the ``lavfi``
+    wrapper, which gives you access to most of libavfilter's filters. This
+    includes all filters that have been ported from MPlayer to libavfilter.
+
+    The ``--vf`` description describes how libavfilter can be used and how to
+    workaround deprecated mpv filters.
+
+See ``--vf`` group of options for info on how ``--af-add``, ``--af-pre``,
+``--af-clr``, and possibly others work.
+
+Available filters are:
+
+``lavcac3enc[=options]``
+    Encode multi-channel audio to AC-3 at runtime using libavcodec. Supports
+    16-bit native-endian input format, maximum 6 channels. The output is
+    big-endian when outputting a raw AC-3 stream, native-endian when
+    outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or
+    32 kHz, it will be resampled to 48 kHz.
+
+    ``tospdif=<yes|no>``
+        Output raw AC-3 stream if ``no``, output to S/PDIF for
+        pass-through if ``yes`` (default).
+
+    ``bitrate=<rate>``
+        The bitrate use for the AC-3 stream. Set it to 384 to get 384 kbps.
+
+        The default is 640. Some receivers might not be able to handle this.
+
+        Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
+        160, 192, 224, 256, 320, 384, 448, 512, 576, 640.
+
+        The special value ``auto`` selects a default bitrate based on the
+        input channel number:
+
+        :1ch: 96
+        :2ch: 192
+        :3ch: 224
+        :4ch: 384
+        :5ch: 448
+        :6ch: 448
+
+    ``minch=<n>``
+        If the input channel number is less than ``<minch>``, the filter will
+        detach itself (default: 3).
+
+    ``encoder=<name>``
+        Select the libavcodec encoder used. Currently, this should be an AC-3
+        encoder, and using another codec will fail horribly.
+
+``format=format:srate:channels:out-srate:out-channels``
+    Does not do any format conversion itself. Rather, it may cause the
+    filter system to insert necessary conversion filters before or after this
+    filter if needed. It is primarily useful for controlling the audio format
+    going into other filters. To specify the format for audio output, see
+    ``--audio-format``, ``--audio-samplerate``, and ``--audio-channels``. This
+    filter is able to force a particular format, whereas ``--audio-*``
+    may be overridden by the ao based on output compatibility.
+
+    All parameters are optional. The first 3 parameters restrict what the filter
+    accepts as input. They will therefore cause conversion filters to be
+    inserted before this one.  The ``out-`` parameters tell the filters or audio
+    outputs following this filter how to interpret the data without actually
+    doing a conversion. Setting these will probably just break things unless you
+    really know you want this for some reason, such as testing or dealing with
+    broken media.
+
+    ``<format>``
+        Force conversion to this format. Use ``--af=format=format=help`` to get
+        a list of valid formats.
+
+    ``<srate>``
+        Force conversion to a specific sample rate. The rate is an integer,
+        48000 for example.
+
+    ``<channels>``
+        Force mixing to a specific channel layout. See ``--audio-channels`` option
+        for possible values.
+
+    ``<out-srate>``
+
+    ``<out-channels>``
+
+    *NOTE*: this filter used to be named ``force``. The old ``format`` filter
+    used to do conversion itself, unlike this one which lets the filter system
+    handle the conversion.
+
+``scaletempo[=option1:option2:...]``
+    Scales audio tempo without altering pitch, optionally synced to playback
+    speed.
+
+    This works by playing 'stride' ms of audio at normal speed then consuming
+    'stride*scale' ms of input audio. It pieces the strides together by
+    blending 'overlap'% of stride with audio following the previous stride. It
+    optionally performs a short statistical analysis on the next 'search' ms
+    of audio to determine the best overlap position.
+
+    ``scale=<amount>``
+        Nominal amount to scale tempo. Scales this amount in addition to
+        speed. (default: 1.0)
+    ``stride=<amount>``
+        Length in milliseconds to output each stride. Too high of a value will
+        cause noticeable skips at high scale amounts and an echo at low scale
+        amounts. Very low values will alter pitch. Increasing improves
+        performance. (default: 60)
+    ``overlap=<factor>``
+        Factor of stride to overlap. Decreasing improves performance.
+        (default: .20)
+    ``search=<amount>``
+        Length in milliseconds to search for best overlap position. Decreasing
+        improves performance greatly. On slow systems, you will probably want
+        to set this very low. (default: 14)
+    ``speed=<tempo|pitch|both|none>``
+        Set response to speed change.
+
+        tempo
+             Scale tempo in sync with speed (default).
+        pitch
+             Reverses effect of filter. Scales pitch without altering tempo.
+             Add this to your ``input.conf`` to step by musical semi-tones::
+
+                [ multiply speed 0.9438743126816935
+                ] multiply speed 1.059463094352953
+
+             .. warning::
+
+                Loses sync with video.
+        both
+            Scale both tempo and pitch.
+        none
+            Ignore speed changes.
+
+    .. admonition:: Examples
+
+        ``mpv --af=scaletempo --speed=1.2 media.ogg``
+            Would play media at 1.2x normal speed, with audio at normal
+            pitch. Changing playback speed would change audio tempo to match.
+
+        ``mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg``
+            Would play media at 1.2x normal speed, with audio at normal
+            pitch, but changing playback speed would have no effect on audio
+            tempo.
+
+        ``mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg``
+            Would tweak the quality and performance parameters.
+
+        ``mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg``
+            Would play media at 1.2x normal speed, with audio at normal pitch.
+            Changing playback speed would change pitch, leaving audio tempo at
+            1.2x.
+
+``scaletempo2[=option1:option2:...]``
+    Scales audio tempo without altering pitch.
+    The algorithm is ported from chromium and uses the
+    Waveform Similarity Overlap-and-add (WSOLA) method.
+    It seems to achieves higher audio quality than scaletempo, and rubberband R2
+    engine, or ``engine=faster``. This filter is inserted automatically if
+    ``audio-pitch-correction`` option is used (on by default) when the playback
+    speed is changed.
+
+    By default, the ``search-interval`` and ``window-size`` parameters
+    have the same values as in chromium.
+
+    ``min-speed=<speed>``
+        Mute audio if the playback speed is below ``<speed>``. (default: 0.25)
+
+    ``max-speed=<speed>``
+        Mute audio if the playback speed is above ``<speed>``
+        and ``<speed> != 0``. (default: 8.0)
+
+    ``search-interval=<amount>``
+        Length in milliseconds to search for best overlap position. (default: 40)
+
+    ``window-size=<amount>``
+        Length in milliseconds of the overlap-and-add window. (default: 12)
+
+``rubberband``
+    High quality pitch correction with librubberband. This can be used in place
+    of ``scaletempo`` and ``scaletempo2``, and will be used to adjust audio pitch
+    when playing at speed different from normal. It can also be used to adjust
+    audio pitch without changing playback speed.
+
+    ``pitch-scale=<amount>``
+        Sets the pitch scaling factor. Frequencies are multiplied by this value.
+        (default: 1.0)
+
+    ``engine=<faster|finer>``
+        Select the core Rubberband engine to be used. There are two available:
+
+        :Faster: This is the Rubberband R2 engine. It uses significantly less
+                 CPU than the Finer (R3) engine.
+        :Finer: This is the Rubberband R3 engine. This engine is only available
+                with librubberband version 3 or newer. This produces significantly
+                higher quality output, at the cost of higher CPU usage. (Default
+                if available)
+
+    This filter has a number of additional sub-options. You can list them with
+    ``mpv --af=rubberband=help``. This will also show the default values
+    for each option. The options are not documented here, because they are
+    merely passed to librubberband. Look at the librubberband documentation
+    to learn what each option does:
+    https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html
+    Do note that certain options are only applicable to one of R2 (faster) and
+    R3 (finer) engines.
+    (The mapping of the mpv rubberband filter sub-option names and values to
+    those of librubberband follows a simple pattern: ``"Option" + Name + Value``.)
+
+    This filter supports the following ``af-command`` commands:
+
+    ``set-pitch``
+        Set the ``<pitch-scale>`` argument dynamically. This can be used to
+        change the playback pitch at runtime. Note that speed is controlled
+        using the standard ``speed`` property, not ``af-command``.
+
+    ``multiply-pitch <factor>``
+        Multiply the current value of ``<pitch-scale>`` dynamically.  For
+        example: 0.5 to go down by an octave, 1.5 to go up by a perfect fifth.
+        If you want to go up or down by semi-tones, use 1.059463094352953 and
+        0.9438743126816935
+
+``lavfi=graph``
+    Filter audio using FFmpeg's libavfilter.
+
+    ``<graph>``
+        Libavfilter graph. See ``lavfi`` video filter for details - the graph
+        syntax is the same.
+
+        .. warning::
+
+            Don't forget to quote libavfilter graphs as described in the lavfi
+            video filter section.
+
+    ``o=<string>``
+        AVOptions.
+
+    ``fix-pts=<yes|no>``
+        Determine PTS based on sample count (default: no). If this is enabled,
+        the player won't rely on libavfilter passing through PTS accurately.
+        Instead, it pass a sample count as PTS to libavfilter, and compute the
+        PTS used by mpv based on that and the input PTS. This helps with filters
+        which output a recomputed PTS instead of the original PTS (including
+        filters which require the PTS to start at 0). mpv normally expects
+        filters to not touch the PTS (or only to the extent of changing frame
+        boundaries), so this is not the default, but it will be needed to use
+        broken filters. In practice, these broken filters will either cause slow
+        A/V desync over time (with some files), or break playback completely if
+        you seek or start playback from the middle of a file.
+
+``drop``
+    This filter drops or repeats audio frames to adapt to playback speed. It
+    always operates on full audio frames, because it was made to handle SPDIF
+    (compressed audio passthrough). This is used automatically if the
+    ``--video-sync=display-adrop`` option is used. Do not use this filter (or
+    the given option); they are extremely low quality.
diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
new file mode 100644
index 0000000..4e4e454
--- /dev/null
+++ b/DOCS/man/ao.rst
@@ -0,0 +1,249 @@
+AUDIO OUTPUT DRIVERS
+====================
+
+Audio output drivers are interfaces to different audio output facilities. The
+syntax is:
+
+``--ao=<driver1,driver2,...[,]>``
+    Specify a priority list of audio output drivers to be used.
+
+If the list has a trailing ',', mpv will fall back on drivers not contained
+in the list.
+
+.. note::
+
+    See ``--ao=help`` for a list of compiled-in audio output drivers. The
+    driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems
+    where PulseAudio is used. On BSD systems, ``--ao=oss`` is preferred.
+
+Available audio output drivers are:
+
+``alsa`` (Linux only)
+    ALSA audio output driver
+
+    See `ALSA audio output options`_ for options specific to this AO.
+
+    .. warning::
+
+        To get multichannel/surround audio, use ``--audio-channels=auto``. The
+        default for this option is ``auto-safe``, which makes this audio output
+        explicitly reject multichannel output, as there is no way to detect
+        whether a certain channel layout is actually supported.
+
+        You can also try `using the upmix plugin
+        <https://github.com/mpv-player/mpv/wiki/ALSA-Surround-Sound-and-Upmixing>`_.
+        This setup enables multichannel audio on the ``default`` device
+        with automatic upmixing with shared access, so playing stereo
+        and multichannel audio at the same time will work as expected.
+
+``oss``
+    OSS audio output driver
+
+``jack``
+    JACK (Jack Audio Connection Kit) audio output driver.
+
+    The following global options are supported by this audio output:
+
+    ``--jack-port=<name>``
+        Connects to the ports with the given name (default: physical ports).
+    ``--jack-name=<client>``
+        Client name that is passed to JACK (default: ``mpv``). Useful
+        if you want to have certain connections established automatically.
+    ``--jack-autostart=<yes|no>``
+        Automatically start jackd if necessary (default: disabled). Note that
+        this tends to be unreliable and will flood stdout with server messages.
+    ``--jack-connect=<yes|no>``
+        Automatically create connections to output ports (default: enabled).
+        When enabled, the maximum number of output channels will be limited to
+        the number of available output ports.
+    ``--jack-std-channel-layout=<waveext|any>``
+        Select the standard channel layout (default: waveext). JACK itself has no
+        notion of channel layouts (i.e. assigning which speaker a given
+        channel is supposed to map to) - it just takes whatever the application
+        outputs, and reroutes it to whatever the user defines. This means the
+        user and the application are in charge of dealing with the channel
+        layout. ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which, even
+        though it was defined by Microsoft, is the standard on many systems.
+        The value ``any`` makes JACK accept whatever comes from the audio
+        filter chain, regardless of channel layout and without reordering. This
+        mode is probably not very useful, other than for debugging or when used
+        with fixed setups.
+
+``coreaudio`` (macOS only)
+    Native macOS audio output driver using AudioUnits and the CoreAudio
+    sound server.
+
+    Automatically redirects to ``coreaudio_exclusive`` when playing compressed
+    formats.
+
+    The following global options are supported by this audio output:
+
+    ``--coreaudio-change-physical-format=<yes|no>``
+        Change the physical format to one similar to the requested audio format
+        (default: no). This has the advantage that multichannel audio output
+        will actually work. The disadvantage is that it will change the
+        system-wide audio settings. This is equivalent to changing the ``Format``
+        setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup``
+        utility. Note that this does not affect the selected speaker setup.
+
+    ``--coreaudio-spdif-hack=<yes|no>``
+        Try to pass through AC3/DTS data as PCM. This is useful for drivers
+        which do not report AC3 support. It converts the AC3 data to float,
+        and assumes the driver will do the inverse conversion, which means
+        a typical A/V receiver will pick it up as compressed IEC framed AC3
+        stream, ignoring that it's marked as PCM. This disables normal AC3
+        passthrough (even if the device reports it as supported). Use with
+        extreme care.
+
+
+``coreaudio_exclusive`` (macOS only)
+    Native macOS audio output driver using direct device access and
+    exclusive mode (bypasses the sound server).
+
+``openal``
+    OpenAL audio output driver.
+
+    ``--openal-num-buffers=<2-128>``
+        Specify the number of audio buffers to use. Lower values are better for
+        lower CPU usage. Default: 4.
+
+    ``--openal-num-samples=<256-32768>``
+        Specify the number of complete samples to use for each buffer. Higher
+        values are better for lower CPU usage. Default: 8192.
+
+    ``--openal-direct-channels=<yes|no>``
+        Enable OpenAL Soft's direct channel extension when available to avoid
+        tinting the sound with ambisonics or HRTF. Default: yes.
+
+``pulse``
+    PulseAudio audio output driver
+
+    The following global options are supported by this audio output:
+
+    ``--pulse-host=<host>``
+        Specify the host to use. An empty <host> string uses a local connection,
+        "localhost" uses network transfer (most likely not what you want).
+
+    ``--pulse-buffer=<1-2000|native>``
+        Set the audio buffer size in milliseconds. A higher value buffers
+        more data, and has a lower probability of buffer underruns. A smaller
+        value makes the audio stream react faster, e.g. to playback speed
+        changes. "native" lets the sound server determine buffers.
+
+    ``--pulse-latency-hacks=<yes|no>``
+        Enable hacks to workaround PulseAudio timing bugs (default: no). If
+        enabled, mpv will do elaborate latency calculations on its own. If
+        disabled, it will use PulseAudio automatically updated timing
+        information. Disabling this might help with e.g. networked audio or
+        some plugins, while enabling it might help in some unknown situations
+        (it used to be required to get good behavior on old PulseAudio versions).
+
+        If you have stuttering video when using pulse, try to enable this
+        option. (Or try to update PulseAudio.)
+
+    ``--pulse-allow-suspended=<yes|no>``
+        Allow mpv to use PulseAudio even if the sink is suspended (default: no).
+        Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink-input set to the one jack is using.
+
+``pipewire``
+    PipeWire audio output driver
+
+    The following global options are supported by this audio output:
+
+    ``--pipewire-buffer=<1-2000|native>``
+        Set the audio buffer size in milliseconds. A higher value buffers
+        more data, and has a lower probability of buffer underruns. A smaller
+        value makes the audio stream react faster, e.g. to playback speed
+        changes. "native" lets the sound server determine buffers.
+
+    ``--pipewire-remote=<remote>``
+        Specify the PipeWire remote daemon name to connect to via local UNIX
+        sockets.
+        An empty <remote> string uses the default remote named ``pipewire-0``.
+
+    ``--pipewire-volume-mode=<channel|global>``
+        Specify if the ``ao-volume`` property should apply to the channel
+        volumes or the global volume.
+        By default the channel volumes are used.
+
+``sdl``
+    SDL 1.2+ audio output driver. Should work on any platform supported by SDL
+    1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
+    appropriately for your system.
+
+    .. note:: This driver is for compatibility with extremely foreign
+              environments, such as systems where none of the other drivers
+              are available.
+
+    The following global options are supported by this audio output:
+
+    ``--sdl-buflen=<length>``
+        Sets the audio buffer length in seconds. Is used only as a hint by the
+        sound system. Playing a file with ``-v`` will show the requested and
+        obtained exact buffer size. A value of 0 selects the sound system
+        default.
+
+``null``
+    Produces no audio output but maintains video playback speed. You can use
+    ``--ao=null --ao-null-untimed`` for benchmarking.
+
+    The following global options are supported by this audio output:
+
+    ``--ao-null-untimed``
+        Do not simulate timing of a perfect audio device. This means audio
+        decoding will go as fast as possible, instead of timing it to the
+        system clock.
+
+    ``--ao-null-buffer``
+        Simulated buffer length in seconds.
+
+    ``--ao-null-outburst``
+        Simulated chunk size in samples.
+
+    ``--ao-null-speed``
+        Simulated audio playback speed as a multiplier. Usually, a real audio
+        device will not go exactly as fast as the system clock. It will deviate
+        just a little, and this option helps to simulate this.
+
+    ``--ao-null-latency``
+        Simulated device latency. This is additional to EOF.
+
+    ``--ao-null-broken-eof``
+        Simulate broken audio drivers, which always add the fixed device
+        latency to the reported audio playback position.
+
+    ``--ao-null-broken-delay``
+        Simulate broken audio drivers, which don't report latency correctly.
+
+    ``--ao-null-channel-layouts``
+        If not empty, this is a ``,`` separated list of channel layouts the
+        AO allows. This can be used to test channel layout selection.
+
+    ``--ao-null-format``
+        Force the audio output format the AO will accept. If unset accepts any.
+
+``pcm``
+    Raw PCM/WAVE file writer audio output
+
+    The following global options are supported by this audio output:
+
+    ``--ao-pcm-waveheader=<yes|no>``
+        Include or do not include the WAVE header (default: included). When
+        not included, raw PCM will be generated.
+    ``--ao-pcm-file=<filename>``
+        Write the sound to ``<filename>`` instead of the default
+        ``audiodump.wav``. If ``no-waveheader`` is specified, the default is
+        ``audiodump.pcm``.
+    ``--ao-pcm-append=<yes|no>``
+        Append to the file, instead of overwriting it. Always use this with the
+        ``no-waveheader`` option - with ``waveheader`` it's broken, because
+        it will write a WAVE header every time the file is opened.
+
+``sndio``
+    Audio output to the OpenBSD sndio sound system
+
+    (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel
+    layouts.)
+
+``wasapi``
+    Audio output to the Windows Audio Session API.
diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst
new file mode 100644
index 0000000..63de41c
--- /dev/null
+++ b/DOCS/man/changes.rst
@@ -0,0 +1,20 @@
+CHANGELOG
+=========
+
+There is no real changelog, but you can look at the following things:
+
+* The release changelog, which should contain most user-visible changes,
+  including new features and bug fixes:
+
+  https://github.com/mpv-player/mpv/releases
+* The git log, which is the "real" changelog
+* The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
+  documents changes to the command and user interface, such as options and
+  properties. (It usually documents breaking changes only, additions and
+  enhancements are often not listed.)
+* C API changes are listed in
+  https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
+* The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git
+  repository, which used to be in place of this section. It documents some
+  changes that happened since mplayer2 forked off MPlayer. (Not updated
+  anymore.)
diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst
new file mode 100644
index 0000000..49502b3
--- /dev/null
+++ b/DOCS/man/console.rst
@@ -0,0 +1,167 @@
+CONSOLE
+=======
+
+The console is a REPL for mpv input commands. It is displayed on the video
+window. It also shows log messages. It can be disabled entirely using the
+``--load-osd-console=no`` option.
+
+Keybindings
+-----------
+
+\`
+    Show the console.
+
+ESC and Ctrl+[
+    Hide the console.
+
+ENTER, Ctrl+j and Ctrl+m
+    Run the typed command.
+
+Shift+ENTER
+    Type a literal newline character.
+
+LEFT and Ctrl+b
+    Move the cursor to the previous character.
+
+RIGHT and Ctrl+f
+    Move the cursor to the next character.
+
+Ctrl+LEFT and Alt+b
+    Move the cursor to the beginning of the current word, or if between words,
+    to the beginning of the previous word.
+
+Ctrl+RIGHT and Alt+f
+    Move the cursor to the end of the current word, or if between words, to the
+    end of the next word.
+
+HOME and Ctrl+a
+    Move the cursor to the start of the current line.
+
+END and Ctrl+e
+    Move the cursor to the end of the current line.
+
+BACKSPACE and Ctrl+h
+    Delete the previous character.
+
+Ctrl+d
+    Hide the console if the current line is empty, otherwise delete the next
+    character.
+
+Ctrl+BACKSPACE and Ctrl+w
+    Delete text from the cursor to the beginning of the current word, or if
+    between words, to the beginning of the previous word.
+
+Ctrl+DEL and Alt+d
+    Delete text from the cursor to the end of the current word, or if between
+    words, to the end of the next word.
+
+Ctrl+u
+    Delete text from the cursor to the beginning of the current line.
+
+Ctrl+k
+    Delete text from the cursor to the end of the current line.
+
+Ctrl+c
+    Clear the current line.
+
+UP and Ctrl+p
+    Move back in the command history.
+
+DOWN and Ctrl+n
+    Move forward in the command history.
+
+PGUP
+    Go to the first command in the history.
+
+PGDN
+    Stop navigating the command history.
+
+INSERT
+    Toggle insert mode.
+
+Ctrl+v
+    Paste text (uses the clipboard on X11 and Wayland).
+
+Shift+INSERT
+    Paste text (uses the primary selection on X11 and Wayland).
+
+TAB and Ctrl+i
+    Complete the command or property name at the cursor.
+
+Ctrl+l
+    Clear all log messages from the console.
+
+Commands
+--------
+
+``script-message-to console type <text> [<cursor_pos>]``
+    Show the console and pre-fill it with the provided text, optionally
+    specifying the initial cursor position as a positive integer starting from
+    1.
+
+    .. admonition:: Examples for input.conf
+
+        ``% script-message-to console type "seek  absolute-percent; keypress ESC" 6``
+            Enter a percent position to seek to and close the console.
+
+        ``Ctrl+o script-message-to console type "loadfile ''; keypress ESC" 11``
+            Enter a file or URL to play. Tab completes paths in the filesystem.
+
+Known issues
+------------
+
+- Pasting text is slow on Windows
+- Non-ASCII keyboard input has restrictions
+- The cursor keys move between Unicode code-points, not grapheme clusters
+
+Configuration
+-------------
+
+This script can be customized through a config file ``script-opts/console.conf``
+placed in mpv's user directory and through the ``--script-opts`` command-line
+option. The configuration syntax is described in `ON SCREEN CONTROLLER`_.
+
+Key bindings can be changed in a standard way, see for example stats.lua
+documentation.
+
+Configurable Options
+~~~~~~~~~~~~~~~~~~~~
+
+``scale``
+    Default: 1
+
+    All drawing is scaled by this value, including the text borders and the
+    cursor.
+
+    If the VO backend in use has HiDPI scale reporting implemented, the option
+    value is scaled with the reported HiDPI scale.
+
+``font``
+    Default: unset (picks a hardcoded font depending on detected platform)
+
+    Set the font used for the REPL and the console.
+    This has to be a monospaced font for the completion suggestions to be
+    aligned correctly.
+
+``font_size``
+    Default: 16
+
+    Set the font size used for the REPL and the console. This will be
+    multiplied by "scale".
+
+``border_size``
+    Default: 1
+
+    Set the font border size used for the REPL and the console.
+
+``history_dedup``
+    Default: true
+
+    Remove duplicate entries in history as to only keep the latest one.
+    multiplied by "scale."
+
+``font_hw_ratio``
+    Default: 2.0
+
+    The ratio of font height to font width.
+    Adjusts table width of completion suggestions.
diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst
new file mode 100644
index 0000000..399eba2
--- /dev/null
+++ b/DOCS/man/encode.rst
@@ -0,0 +1,107 @@
+ENCODING
+========
+
+You can encode files from one format/codec to another using this facility.
+
+``--o=<filename>``
+    Enables encoding mode and specifies the output file name.
+
+``--of=<format>``
+    Specifies the output format (overrides autodetection by the file name
+    extension of the file specified by ``-o``). See ``--of=help`` for a full
+    list of supported formats.
+
+``--ofopts=<options>``
+    Specifies the output format options for libavformat.
+    See ``--ofopts=help`` for a full list of supported options.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    ``--ofopts-add=<option>``
+        Appends the option given as an argument to the options list. (Passing
+        multiple options is currently still possible, but deprecated.)
+
+    ``--ofopts=""``
+        Completely empties the options list.
+
+``--oac=<codec>``
+    Specifies the output audio codec. See ``--oac=help`` for a full list of
+    supported codecs.
+
+``--oacopts=<options>``
+    Specifies the output audio codec options for libavcodec.
+    See ``--oacopts=help`` for a full list of supported options.
+
+    .. admonition:: Example
+
+        "``--oac=libmp3lame --oacopts=b=128000``"
+            selects 128 kbps MP3 encoding.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    ``--oacopts-add=<option>``
+        Appends the option given as an argument to the options list. (Passing
+        multiple options is currently still possible, but deprecated.)
+
+    ``--oacopts=""``
+        Completely empties the options list.
+
+``--ovc=<codec>``
+    Specifies the output video codec. See ``--ovc=help`` for a full list of
+    supported codecs.
+
+``--ovcopts=<options>``
+    Specifies the output video codec options for libavcodec.
+    See --ovcopts=help for a full list of supported options.
+
+    .. admonition:: Examples
+
+        ``"--ovc=mpeg4 --ovcopts=qscale=5"``
+            selects constant quantizer scale 5 for MPEG-4 encoding.
+
+        ``"--ovc=libx264 --ovcopts=crf=23"``
+            selects VBR quality factor 23 for H.264 encoding.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    ``--ovcopts-add=<option>``
+        Appends the option given as an argument to the options list. (Passing
+        multiple options is currently still possible, but deprecated.)
+
+    ``--ovcopts=""``
+        Completely empties the options list.
+
+``--orawts``
+    Copies input pts to the output video (not supported by some output
+    container formats, e.g. AVI). In this mode, discontinuities are not fixed
+    and all pts are passed through as-is. Never seek backwards or use multiple
+    input files in this mode!
+
+``--no-ocopy-metadata``
+    Turns off copying of metadata from input files to output files when
+    encoding (which is enabled by default).
+
+``--oset-metadata=<metadata-tag[,metadata-tag,...]>``
+    Specifies metadata to include in the output file.
+    Supported keys vary between output formats. For example, Matroska (MKV) and
+    FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more
+    limited.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        "``--oset-metadata=title="Output title",comment="Another tag"``"
+            adds a title and a comment to the output file.
+
+``--oremove-metadata=<metadata-tag[,metadata-tag,...]>``
+    Specifies metadata to exclude from the output file when copying from the
+    input file.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        "``--oremove-metadata=comment,genre``"
+            excludes copying of the the comment and genre tags to the output
+            file.
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.
diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst
new file mode 100644
index 0000000..fbb0b01
--- /dev/null
+++ b/DOCS/man/ipc.rst
@@ -0,0 +1,387 @@
+JSON IPC
+========
+
+mpv can be controlled by external programs using the JSON-based IPC protocol.
+It can be enabled by specifying the path to a unix socket or a named pipe using
+the option ``--input-ipc-server``. Clients can connect to this socket and send
+commands to the player or receive events from it.
+
+.. warning::
+
+    This is not intended to be a secure network protocol. It is explicitly
+    insecure: there is no authentication, no encryption, and the commands
+    themselves are insecure too. For example, the ``run`` command is exposed,
+    which can run arbitrary system commands. The use-case is controlling the
+    player locally. This is not different from the MPlayer slave protocol.
+
+Socat example
+-------------
+
+You can use the ``socat`` tool to send commands (and receive replies) from the
+shell. Assuming mpv was started with:
+
+::
+
+    mpv file.mkv --input-ipc-server=/tmp/mpvsocket
+
+Then you can control it using socat:
+
+::
+
+    > echo '{ "command": ["get_property", "playback-time"] }' | socat - /tmp/mpvsocket
+    {"data":190.482000,"error":"success"}
+
+In this case, socat copies data between stdin/stdout and the mpv socket
+connection.
+
+See the ``--idle`` option how to make mpv start without exiting immediately or
+playing a file.
+
+It's also possible to send input.conf style text-only commands:
+
+::
+
+    > echo 'show-text ${playback-time}' | socat - /tmp/mpvsocket
+
+But you won't get a reply over the socket. (This particular command shows the
+playback time on the player's OSD.)
+
+Command Prompt example
+----------------------
+
+Unfortunately, it's not as easy to test the IPC protocol on Windows, since
+Windows ports of socat (in Cygwin and MSYS2) don't understand named pipes. In
+the absence of a simple tool to send and receive from bidirectional pipes, the
+``echo`` command can be used to send commands, but not receive replies from the
+command prompt.
+
+Assuming mpv was started with:
+
+::
+
+    mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket
+
+You can send commands from a command prompt:
+
+::
+
+    echo show-text ${playback-time} >\\.\pipe\mpvsocket
+
+To be able to simultaneously read and write from the IPC pipe, like on Linux,
+it's necessary to write an external program that uses overlapped file I/O (or
+some wrapper like .NET's NamedPipeClientStream.)
+
+You can open the pipe in PuTTY as "serial" device. This is not very
+comfortable, but gives a way to test interactively without having to write code.
+
+Protocol
+--------
+
+The protocol uses UTF-8-only JSON as defined by RFC-8259. Unlike standard JSON,
+"\u" escape sequences are not allowed to construct surrogate pairs. To avoid
+getting conflicts, encode all text characters including and above codepoint
+U+0020 as UTF-8. mpv might output broken UTF-8 in corner cases (see "UTF-8"
+section below).
+
+Clients can execute commands on the player by sending JSON messages of the
+following form:
+
+::
+
+    { "command": ["command_name", "param1", "param2", ...] }
+
+where ``command_name`` is the name of the command to be executed, followed by a
+list of parameters. Parameters must be formatted as native JSON values
+(integers, strings, booleans, ...). Every message **must** be terminated with
+``\n``. Additionally, ``\n`` must not appear anywhere inside the message. In
+practice this means that messages should be minified before being sent to mpv.
+
+mpv will then send back a reply indicating whether the command was run
+correctly, and an additional field holding the command-specific return data (it
+can also be null).
+
+::
+
+    { "error": "success", "data": null }
+
+mpv will also send events to clients with JSON messages of the following form:
+
+::
+
+    { "event": "event_name" }
+
+where ``event_name`` is the name of the event. Additional event-specific fields
+can also be present. See `List of events`_ for a list of all supported events.
+
+Because events can occur at any time, it may be difficult at times to determine
+which response goes with which command. Commands may optionally include a
+``request_id`` which, if provided in the command request, will be copied
+verbatim into the response. mpv does not interpret the ``request_id`` in any
+way; it is solely for the use of the requester. The only requirement is that
+the ``request_id`` field must be an integer (a number without fractional parts
+in the range ``-2^63..2^63-1``). Using other types is deprecated and will
+currently show a warning. In the future, this will raise an error.
+
+For example, this request:
+
+::
+
+    { "command": ["get_property", "time-pos"], "request_id": 100 }
+
+Would generate this response:
+
+::
+
+    { "error": "success", "data": 1.468135, "request_id": 100 }
+
+If you don't specify a ``request_id``, command replies will set it to 0.
+
+All commands, replies, and events are separated from each other with a line
+break character (``\n``).
+
+If the first character (after skipping whitespace) is not ``{``, the command
+will be interpreted as non-JSON text command, as they are used in input.conf
+(or ``mpv_command_string()`` in the client API). Additionally, lines starting
+with ``#`` and empty lines are ignored.
+
+Currently, embedded 0 bytes terminate the current line, but you should not
+rely on this.
+
+Data flow
+---------
+
+Currently, the mpv-side IPC implementation does not service the socket while a
+command is executed and the reply is written. It is for example not possible
+that other events, that happened during the execution of the command, are
+written to the socket before the reply is written.
+
+This might change in the future. The only guarantee is that replies to IPC
+messages are sent in sequence.
+
+Also, since socket I/O is inherently asynchronous, it is possible that you read
+unrelated event messages from the socket, before you read the reply to the
+previous command you sent. In this case, these events were queued by the mpv
+side before it read and started processing your command message.
+
+If the mpv-side IPC implementation switches away from blocking writes and
+blocking command execution, it may attempt to send events at any time.
+
+You can also use asynchronous commands, which can return in any order, and
+which do not block IPC protocol interaction at all while the command is
+executed in the background.
+
+Asynchronous commands
+---------------------
+
+Command can be run asynchronously. This behaves exactly as with normal command
+execution, except that execution is not blocking. Other commands can be sent
+while it's executing, and command completion can be arbitrarily reordered.
+
+The ``async`` field controls this. If present, it must be a boolean. If missing,
+``false`` is assumed.
+
+For example, this initiates an asynchronous command:
+
+::
+
+    { "command": ["screenshot"], "request_id": 123, "async": true }
+
+And this is the completion:
+
+::
+
+    {"request_id":123,"error":"success","data":null}
+
+By design, you will not get a confirmation that the command was started. If a
+command is long running, sending the message will not lead to any reply until
+much later when the command finishes.
+
+Some commands execute synchronously, but these will behave like asynchronous
+commands that finished execution immediately.
+
+Cancellation of asynchronous commands is available in the libmpv API, but has
+not yet been implemented in the IPC protocol.
+
+Commands with named arguments
+-----------------------------
+
+If the ``command`` field is a JSON object, named arguments are expected. This
+is described in the C API ``mpv_command_node()`` documentation (the
+``MPV_FORMAT_NODE_MAP`` case). In some cases, this may make commands more
+readable, while some obscure commands basically require using named arguments.
+
+Currently, only "proper" commands (as listed by `List of Input Commands`_)
+support named arguments.
+
+Commands
+--------
+
+In addition to the commands described in `List of Input Commands`_, a few
+extra commands can also be used as part of the protocol:
+
+``client_name``
+    Return the name of the client as string. This is the string ``ipc-N`` with
+    N being an integer number.
+
+``get_time_us``
+    Return the current mpv internal time in microseconds as a number. This is
+    basically the system time, with an arbitrary offset.
+
+``get_property``
+    Return the value of the given property. The value will be sent in the data
+    field of the replay message.
+
+    Example:
+
+    ::
+
+        { "command": ["get_property", "volume"] }
+        { "data": 50.0, "error": "success" }
+
+``get_property_string``
+    Like ``get_property``, but the resulting data will always be a string.
+
+    Example:
+
+    ::
+
+        { "command": ["get_property_string", "volume"] }
+        { "data": "50.000000", "error": "success" }
+
+``set_property``
+    Set the given property to the given value. See `Properties`_ for more
+    information about properties.
+
+    Example:
+
+    ::
+
+        { "command": ["set_property", "pause", true] }
+        { "error": "success" }
+
+``set_property_string``
+    Alias for ``set_property``. Both commands accept native values and strings.
+
+``observe_property``
+    Watch a property for changes. If the given property is changed, then an
+    event of type ``property-change`` will be generated
+
+    Example:
+
+    ::
+
+        { "command": ["observe_property", 1, "volume"] }
+        { "error": "success" }
+        { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }
+
+    .. warning::
+
+        If the connection is closed, the IPC client is destroyed internally,
+        and the observed properties are unregistered. This happens for example
+        when sending commands to a socket with separate ``socat`` invocations.
+        This can make it seem like property observation does not work. You must
+        keep the IPC connection open to make it work.
+
+``observe_property_string``
+    Like ``observe_property``, but the resulting data will always be a string.
+
+    Example:
+
+    ::
+
+        { "command": ["observe_property_string", 1, "volume"] }
+        { "error": "success" }
+        { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }
+
+``unobserve_property``
+    Undo ``observe_property`` or ``observe_property_string``. This requires the
+    numeric id passed to the observed command as argument.
+
+    Example:
+
+    ::
+
+        { "command": ["unobserve_property", 1] }
+        { "error": "success" }
+
+``request_log_messages``
+    Enable output of mpv log messages. They will be received as events. The
+    parameter to this command is the log-level (see ``mpv_request_log_messages``
+    C API function).
+
+    Log message output is meant for humans only (mostly for debugging).
+    Attempting to retrieve information by parsing these messages will just
+    lead to breakages with future mpv releases. Instead, make a feature request,
+    and ask for a proper event that returns the information you need.
+
+``enable_event``, ``disable_event``
+    Enables or disables the named event. Mirrors the ``mpv_request_event`` C
+    API function. If the string ``all`` is used instead of an event name, all
+    events are enabled or disabled.
+
+    By default, most events are enabled, and there is not much use for this
+    command.
+
+``get_version``
+    Returns the client API version the C API of the remote mpv instance
+    provides.
+
+    See also: ``DOCS/client-api-changes.rst``.
+
+UTF-8
+-----
+
+Normally, all strings are in UTF-8. Sometimes it can happen that strings are
+in some broken encoding (often happens with file tags and such, and filenames
+on many Unixes are not required to be in UTF-8 either). This means that mpv
+sometimes sends invalid JSON. If that is a problem for the client application's
+parser, it should filter the raw data for invalid UTF-8 sequences and perform
+the desired replacement, before feeding the data to its JSON parser.
+
+mpv will not attempt to construct invalid UTF-8 with broken "\u" escape
+sequences. This includes surrogate pairs.
+
+JSON extensions
+---------------
+
+The following non-standard extensions are supported:
+
+    - a list or object item can have a trailing ","
+    - object syntax accepts "=" in addition of ":"
+    - object keys can be unquoted, if they start with a character in "A-Za-z\_"
+      and contain only characters in "A-Za-z0-9\_"
+    - byte escapes with "\xAB" are allowed (with AB being a 2 digit hex number)
+
+Example:
+
+::
+
+    { objkey = "value\x0A" }
+
+Is equivalent to:
+
+::
+
+    { "objkey": "value\n" }
+
+Alternative ways of starting clients
+------------------------------------
+
+You can create an anonymous IPC connection without having to set
+``--input-ipc-server``. This is achieved through a mpv pseudo scripting backend
+that starts processes.
+
+You can put ``.run`` file extension in the mpv scripts directory in its  config
+directory (see the `FILES`_ section for details), or load them through other
+means (see `Script location`_). These scripts are simply executed with the OS
+native mechanism (as if you ran them in the shell). They must have a proper
+shebang and have the executable bit set.
+
+When executed, a socket (the IPC connection) is passed to them through file
+descriptor inheritance. The file descriptor is indicated as the special command
+line argument ``--mpv-ipc-fd=N``, where ``N`` is the numeric file descriptor.
+
+The rest is the same as with a normal ``--input-ipc-server`` IPC connection. mpv
+does not attempt to observe or other interact with the started script process.
+
+This does not work in Windows yet.
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
new file mode 100644
index 0000000..bdbb04b
--- /dev/null
+++ b/DOCS/man/javascript.rst
@@ -0,0 +1,398 @@
+JAVASCRIPT
+==========
+
+JavaScript support in mpv is near identical to its Lua support. Use this section
+as reference on differences and availability of APIs, but otherwise you should
+refer to the Lua documentation for API details and general scripting in mpv.
+
+Example
+-------
+
+JavaScript code which leaves fullscreen mode when the player is paused:
+
+::
+
+    function on_pause_change(name, value) {
+        if (value == true)
+            mp.set_property("fullscreen", "no");
+    }
+    mp.observe_property("pause", "bool", on_pause_change);
+
+
+Similarities with Lua
+---------------------
+
+mpv tries to load a script file as JavaScript if it has a ``.js`` extension, but
+otherwise, the documented Lua options, script directories, loading, etc apply to
+JavaScript files too.
+
+Script initialization and lifecycle is the same as with Lua, and most of the Lua
+functions at the modules ``mp``, ``mp.utils``, ``mp.msg`` and ``mp.options`` are
+available to JavaScript with identical APIs - including running commands,
+getting/setting properties, registering events/key-bindings/hooks, etc.
+
+Differences from Lua
+--------------------
+
+No need to load modules. ``mp``, ``mp.utils``,  ``mp.msg`` and ``mp.options``
+are preloaded, and you can use e.g. ``var cwd = mp.utils.getcwd();`` without
+prior setup.
+
+Errors are slightly different. Where the Lua APIs return ``nil`` for error,
+the JavaScript ones return ``undefined``. Where Lua returns ``something, error``
+JavaScript returns only ``something`` - and makes ``error`` available via
+``mp.last_error()``. Note that only some of the functions have this additional
+``error`` value - typically the same ones which have it in Lua.
+
+Standard APIs are preferred. For instance ``setTimeout`` and ``JSON.stringify``
+are available, but ``mp.add_timeout`` and ``mp.utils.format_json`` are not.
+
+No standard library. This means that interaction with anything outside of mpv is
+limited to the available APIs, typically via ``mp.utils``. However, some file
+functions were added, and CommonJS ``require`` is available too - where the
+loaded modules have the same privileges as normal scripts.
+
+Language features - ECMAScript 5
+--------------------------------
+
+The scripting backend which mpv currently uses is MuJS - a compatible minimal
+ES5 interpreter. As such, ``String.substring`` is implemented for instance,
+while the common but non-standard ``String.substr`` is not. Please consult the
+MuJS pages on language features and platform support - https://mujs.com .
+
+Unsupported Lua APIs and their JS alternatives
+----------------------------------------------
+
+``mp.add_timeout(seconds, fn)``  JS: ``id = setTimeout(fn, ms)``
+
+``mp.add_periodic_timer(seconds, fn)``  JS: ``id = setInterval(fn, ms)``
+
+``utils.parse_json(str [, trail])``  JS: ``JSON.parse(str)``
+
+``utils.format_json(v)``  JS: ``JSON.stringify(v)``
+
+``utils.to_string(v)``  see ``dump`` below.
+
+``mp.get_next_timeout()`` see event loop below.
+
+``mp.dispatch_events([allow_wait])`` see event loop below.
+
+Scripting APIs - identical to Lua
+---------------------------------
+
+(LE) - Last-Error, indicates that ``mp.last_error()`` can be used after the
+call to test for success (empty string) or failure (non empty reason string).
+Where the Lua APIs use ``nil`` to indicate error, JS APIs use ``undefined``.
+
+``mp.command(string)`` (LE)
+
+``mp.commandv(arg1, arg2, ...)`` (LE)
+
+``mp.command_native(table [,def])`` (LE)
+
+``id = mp.command_native_async(table [,fn])`` (LE) Notes: ``id`` is true-thy on
+success, ``error`` is empty string on success.
+
+``mp.abort_async_command(id)``
+
+``mp.del_property(name)`` (LE)
+
+``mp.get_property(name [,def])`` (LE)
+
+``mp.get_property_osd(name [,def])`` (LE)
+
+``mp.get_property_bool(name [,def])`` (LE)
+
+``mp.get_property_number(name [,def])`` (LE)
+
+``mp.get_property_native(name [,def])`` (LE)
+
+``mp.set_property(name, value)`` (LE)
+
+``mp.set_property_bool(name, value)`` (LE)
+
+``mp.set_property_number(name, value)`` (LE)
+
+``mp.set_property_native(name, value)`` (LE)
+
+``mp.get_time()``
+
+``mp.add_key_binding(key, name|fn [,fn [,flags]])``
+
+``mp.add_forced_key_binding(...)``
+
+``mp.remove_key_binding(name)``
+
+``mp.register_event(name, fn)``
+
+``mp.unregister_event(fn)``
+
+``mp.observe_property(name, type, fn)``
+
+``mp.unobserve_property(fn)``
+
+``mp.get_opt(key)``
+
+``mp.get_script_name()``
+
+``mp.get_script_directory()``
+
+``mp.osd_message(text [,duration])``
+
+``mp.get_wakeup_pipe()``
+
+``mp.register_idle(fn)``
+
+``mp.unregister_idle(fn)``
+
+``mp.enable_messages(level)``
+
+``mp.register_script_message(name, fn)``
+
+``mp.unregister_script_message(name)``
+
+``mp.create_osd_overlay(format)``
+
+``mp.get_osd_size()``  (returned object has properties: width, height, aspect)
+
+``mp.msg.log(level, ...)``
+
+``mp.msg.fatal(...)``
+
+``mp.msg.error(...)``
+
+``mp.msg.warn(...)``
+
+``mp.msg.info(...)``
+
+``mp.msg.verbose(...)``
+
+``mp.msg.debug(...)``
+
+``mp.msg.trace(...)``
+
+``mp.utils.getcwd()`` (LE)
+
+``mp.utils.readdir(path [, filter])`` (LE)
+
+``mp.utils.file_info(path)`` (LE) Note: like lua - this does NOT expand
+meta-paths like ``~~/foo`` (other JS file functions do expand meta paths).
+
+``mp.utils.split_path(path)``
+
+``mp.utils.join_path(p1, p2)``
+
+``mp.utils.subprocess(t)``
+
+``mp.utils.subprocess_detached(t)``
+
+``mp.utils.get_env_list()``
+
+``mp.utils.getpid()`` (LE)
+
+``mp.add_hook(type, priority, fn(hook))``
+
+``mp.options.read_options(obj [, identifier [, on_update]])`` (types:
+string/boolean/number)
+
+Additional utilities
+--------------------
+
+``mp.last_error()``
+    If used after an API call which updates last error, returns an empty string
+    if the API call succeeded, or a non-empty error reason string otherwise.
+
+``Error.stack`` (string)
+    When using ``try { ... } catch(e) { ... }``, then ``e.stack`` is the stack
+    trace of the error - if it was created using the ``Error(...)`` constructor.
+
+``print`` (global)
+    A convenient alias to ``mp.msg.info``.
+
+``dump`` (global)
+    Like ``print`` but also expands objects and arrays recursively.
+
+``mp.utils.getenv(name)``
+    Returns the value of the host environment variable ``name``, or
+    ``undefined`` if the variable is not defined.
+
+``mp.utils.get_user_path(path)``
+    Trivial wrapper of the ``expand-path`` mpv command, returns a string.
+    ``read_file``, ``write_file``, ``append_file`` and ``require`` already
+    expand the path internally and accept mpv meta-paths like ``~~desktop/foo``.
+
+``mp.utils.read_file(fname [,max])``
+    Returns the content of file ``fname`` as string. If ``max`` is provided and
+    not negative, limit the read to ``max`` bytes.
+
+``mp.utils.write_file(fname, str)``
+    (Over)write file ``fname`` with text content ``str``. ``fname`` must be
+    prefixed with ``file://`` as simple protection against accidental arguments
+    switch, e.g. ``mp.utils.write_file("file://~/abc.txt", "hello world")``.
+
+``mp.utils.append_file(fname, str)``
+    Same as ``mp.utils.write_file`` if the file ``fname`` does not exist. If it
+    does exist then append instead of overwrite.
+
+Note: ``read_file``, ``write_file`` and ``append_file`` throw on errors, allow
+text content only.
+
+``mp.get_time_ms()``
+    Same as ``mp.get_time()`` but in ms instead of seconds.
+
+``mp.get_script_file()``
+    Returns the file name of the current script.
+
+``exit()`` (global)
+    Make the script exit at the end of the current event loop iteration.
+    Note: please remove added key bindings before calling ``exit()``.
+
+``mp.utils.compile_js(fname, content_str)``
+    Compiles the JS code ``content_str`` as file name ``fname`` (without loading
+    anything from the filesystem), and returns it as a function. Very similar
+    to a ``Function`` constructor, but shows at stack traces as ``fname``.
+
+``mp.module_paths``
+    Global modules search paths array for the ``require`` function (see below).
+
+Timers (global)
+---------------
+
+The standard HTML/node.js timers are available:
+
+``id = setTimeout(fn [,duration [,arg1 [,arg2...]]])``
+
+``id = setTimeout(code_string [,duration])``
+
+``clearTimeout(id)``
+
+``id = setInterval(fn [,duration [,arg1 [,arg2...]]])``
+
+``id = setInterval(code_string [,duration])``
+
+``clearInterval(id)``
+
+``setTimeout`` and ``setInterval`` return id, and later call ``fn`` (or execute
+``code_string``) after ``duration`` ms. Interval also repeat every ``duration``.
+
+``duration`` has a minimum and default value of 0, ``code_string`` is
+a plain string which is evaluated as JS code, and ``[,arg1 [,arg2..]]`` are used
+as arguments (if provided) when calling back ``fn``.
+
+The ``clear...(id)`` functions cancel timer ``id``, and are irreversible.
+
+Note: timers always call back asynchronously, e.g. ``setTimeout(fn)`` will never
+call ``fn`` before returning. ``fn`` will be called either at the end of this
+event loop iteration or at a later event loop iteration. This is true also for
+intervals - which also never call back twice at the same event loop iteration.
+
+Additionally, timers are processed after the event queue is empty, so it's valid
+to use ``setTimeout(fn)`` as a one-time idle observer.
+
+CommonJS modules and ``require(id)``
+------------------------------------
+
+CommonJS Modules are a standard system where scripts can export common functions
+for use by other scripts. Specifically, a module is a script which adds
+properties (functions, etc) to its pre-existing ``exports`` object, which
+another script can access with ``require(module-id)``. This runs the module and
+returns its ``exports`` object. Further calls to ``require`` for the same module
+will return its cached ``exports`` object without running the module again.
+
+Modules and ``require`` are supported, standard compliant, and generally similar
+to node.js. However, most node.js modules won't run due to missing modules such
+as ``fs``, ``process``, etc, but some node.js modules with minimal dependencies
+do work. In general, this is for mpv modules and not a node.js replacement.
+
+A ``.js`` file extension is always added to ``id``, e.g. ``require("./foo")``
+will load the file ``./foo.js`` and return its ``exports`` object.
+
+An id which starts with ``./`` or ``../`` is relative to the script or module
+which ``require`` it. Otherwise it's considered a top-level id (CommonJS term).
+
+Top-level id is evaluated as absolute filesystem path if possible, e.g. ``/x/y``
+or ``~/x``. Otherwise it's considered a global module id and searched according
+to ``mp.module_paths`` in normal array order, e.g. ``require("x")`` tries to
+load ``x.js`` at one of the array paths, and id ``foo/x`` tries to load ``x.js``
+inside dir ``foo`` at one of the paths.
+
+The ``mp.module_paths`` array is empty by default except for scripts which are
+loaded as a directory where it contains one item - ``<directory>/modules/`` .
+The array may be updated from a script (or using custom init - see below) which
+will affect future calls to ``require`` for global module id's which are not
+already loaded/cached.
+
+No ``global`` variable, but a module's ``this`` at its top lexical scope is the
+global object - also in strict mode. If you have a module which needs ``global``
+as the global object, you could do ``this.global = this;`` before ``require``.
+
+Functions and variables declared at a module don't pollute the global object.
+
+Custom initialization
+---------------------
+
+After mpv initializes the JavaScript environment for a script but before it
+loads the script - it tries to run the file ``init.js`` at the root of the mpv
+configuration directory. Code at this file can update the environment further
+for all scripts. E.g. if it contains ``mp.module_paths.push("/foo")`` then
+``require`` at all scripts will search global module id's also at ``/foo``
+(do NOT do ``mp.module_paths = ["/foo"];`` because this will remove existing
+paths - like ``<script-dir>/modules`` for scripts which load from a directory).
+
+The custom-init file is ignored if mpv is invoked with ``--no-config``.
+
+Before mpv 0.34, the file name was ``.init.js`` (with dot) at the same dir.
+
+The event loop
+--------------
+
+The event loop poll/dispatch mpv events as long as the queue is not empty, then
+processes the timers, then waits for the next event, and repeats this forever.
+
+You could put this code at your script to replace the built-in event loop, and
+also print every event which mpv sends to your script:
+
+::
+
+    function mp_event_loop() {
+        var wait = 0;
+        do {
+            var e = mp.wait_event(wait);
+            dump(e);  // there could be a lot of prints...
+            if (e.event != "none") {
+                mp.dispatch_event(e);
+                wait = 0;
+            } else {
+                wait = mp.process_timers() / 1000;
+                if (wait != 0) {
+                    mp.notify_idle_observers();
+                    wait = mp.peek_timers_wait() / 1000;
+                }
+            }
+        } while (mp.keep_running);
+    }
+
+
+``mp_event_loop`` is a name which mpv tries to call after the script loads.
+The internal implementation is similar to this (without ``dump`` though..).
+
+``e = mp.wait_event(wait)`` returns when the next mpv event arrives, or after
+``wait`` seconds if positive and no mpv events arrived. ``wait`` value of 0
+returns immediately (with ``e.event == "none"`` if the queue is empty).
+
+``mp.dispatch_event(e)`` calls back the handlers registered for ``e.event``,
+if there are such (event handlers, property observers, script messages, etc).
+
+``mp.process_timers()`` calls back the already-added, non-canceled due timers,
+and returns the duration in ms till the next due timer (possibly 0), or -1 if
+there are no pending timers. Must not be called recursively.
+
+``mp.notify_idle_observers()`` calls back the idle observers, which we do when
+we're about to sleep (wait != 0), but the observers may add timers or take
+non-negligible duration to complete, so we re-calculate ``wait`` afterwards.
+
+``mp.peek_timers_wait()`` returns the same values as ``mp.process_timers()``
+but without doing anything. Invalid result if called from a timer callback.
+
+Note: ``exit()`` is also registered for the ``shutdown`` event, and its
+implementation is a simple ``mp.keep_running = false``.
diff --git a/DOCS/man/libmpv.rst b/DOCS/man/libmpv.rst
new file mode 100644
index 0000000..e00f8b9
--- /dev/null
+++ b/DOCS/man/libmpv.rst
@@ -0,0 +1,79 @@
+EMBEDDING INTO OTHER PROGRAMS (LIBMPV)
+======================================
+
+mpv can be embedded into other programs as video/audio playback backend. The
+recommended way to do so is using libmpv. See ``libmpv/client.h`` in the mpv
+source code repository. This provides a C API. Bindings for other languages
+might be available (see wiki).
+
+Since libmpv merely allows access to underlying mechanisms that can control
+mpv, further documentation is spread over a few places:
+
+- https://github.com/mpv-player/mpv/blob/master/libmpv/client.h
+- https://mpv.io/manual/master/#options
+- https://mpv.io/manual/master/#list-of-input-commands
+- https://mpv.io/manual/master/#properties
+- https://github.com/mpv-player/mpv-examples/tree/master/libmpv
+
+C PLUGINS
+=========
+
+You can write C plugins for mpv. These use the libmpv API, although they do not
+use the libmpv library itself.
+
+They are enabled by default if compiler supports linking with the ``-rdynamic``
+flag on Linux/BSD platforms. On Windows the are always enabled.
+
+C plugins location
+------------------
+
+C plugins are put into the mpv scripts directory in its config directory
+(see the `FILES`_ section for details). They must have a ``.so`` or ``.dll``
+file extension. They can also be explicitly loaded with the ``--script`` option.
+
+API
+---
+
+A C plugin must export the following function::
+
+    int mpv_open_cplugin(mpv_handle *handle)
+
+The plugin function will be called on loading time. This function does not
+return as long as your plugin is loaded (it runs in its own thread). The
+``handle`` will be deallocated as soon as the plugin function returns.
+
+The return value is interpreted as error status. A value of ``0`` is
+interpreted as success, while ``-1`` signals an error. In the latter case,
+the player prints an uninformative error message that loading failed.
+
+Return values other than ``0`` and ``-1`` are reserved, and trigger undefined
+behavior.
+
+Within the plugin function, you can call libmpv API functions. The ``handle``
+is created by ``mpv_create_client()`` (or actually an internal equivalent),
+and belongs to you. You can call ``mpv_wait_event()`` to wait for things
+happening, and so on.
+
+Note that the player might block until your plugin calls ``mpv_wait_event()``
+for the first time. This gives you a chance to install initial hooks etc.
+before playback begins.
+
+The details are quite similar to Lua scripts.
+
+Linkage to libmpv
+-----------------
+
+The current implementation requires that your plugins are **not** linked against
+libmpv. What your plugins use are not symbols from a libmpv binary, but
+symbols from the mpv host binary.
+
+On Windows to make symbols from the host binary available, you have to define
+MPV_CPLUGIN_DYNAMIC_SYM when compiling cplugin. This will load symbols
+dynamically, before calling ``mpv_open_cplugin()``.
+
+Examples
+--------
+
+See:
+
+- https://github.com/mpv-player/mpv-examples/tree/master/cplugins
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
new file mode 100644
index 0000000..5708e19
--- /dev/null
+++ b/DOCS/man/lua.rst
@@ -0,0 +1,917 @@
+LUA SCRIPTING
+=============
+
+mpv can load Lua scripts. (See `Script location`_.)
+
+mpv provides the built-in module ``mp``, which contains functions to send
+commands to the mpv core and to retrieve information about playback state, user
+settings, file information, and so on.
+
+These scripts can be used to control mpv in a similar way to slave mode.
+Technically, the Lua code uses the client API internally.
+
+Example
+-------
+
+A script which leaves fullscreen mode when the player is paused:
+
+::
+
+    function on_pause_change(name, value)
+        if value == true then
+            mp.set_property("fullscreen", "no")
+        end
+    end
+    mp.observe_property("pause", "bool", on_pause_change)
+
+
+Script location
+---------------
+
+Scripts can be passed to the ``--script`` option, and are automatically loaded
+from the ``scripts`` subdirectory of the mpv configuration directory (usually
+``~/.config/mpv/scripts/``).
+
+A script can be a single file. The file extension is used to select the
+scripting backend to use for it. For Lua, it is ``.lua``. If the extension is
+not recognized, an error is printed. (If an error happens, the extension is
+either mistyped, or the backend was not compiled into your mpv binary.)
+
+mpv internally loads the script's name by stripping the ``.lua`` extension and
+replacing all nonalphanumeric characters with ``_``. E.g., ``my-tools.lua``
+becomes ``my_tools``. If there are several scripts with the same name, it is
+made unique by appending a number. This is the name returned by
+``mp.get_script_name()``.
+
+Entries with ``.disable`` extension are always ignored.
+
+If a script is a directory (either if a directory is passed to ``--script``,
+or any sub-directories in the script directory, such as for example
+``~/.config/mpv/scripts/something/``), then the directory represents a single
+script. The player will try to load a file named ``main.x``, where ``x`` is
+replaced with the file extension. For example, if ``main.lua`` exists, it is
+loaded with the Lua scripting backend.
+
+You must not put any other files or directories that start with ``main.`` into
+the script's top level directory. If the script directory contains for example
+both ``main.lua`` and ``main.js``, only one of them will be loaded (and which
+one depends on mpv internals that may change any time). Likewise, if there is
+for example ``main.foo``, your script will break as soon as mpv adds a backend
+that uses the ``.foo`` file extension.
+
+mpv also appends the top level directory of the script to the start of Lua's
+package path so you can import scripts from there too. Be aware that this will
+shadow Lua libraries that use the same package path. (Single file scripts do not
+include mpv specific directories in the Lua package path. This was silently
+changed in mpv 0.32.0.)
+
+Using a script directory is the recommended way to package a script that
+consists of multiple source files, or requires other files (you can use
+``mp.get_script_directory()`` to get the location and e.g. load data files).
+
+Making a script a git repository, basically a repository which contains a
+``main.lua`` file in the root directory, makes scripts easily updateable
+(without the dangers of auto-updates). Another suggestion is to use git
+submodules to share common files or libraries.
+
+Details on the script initialization and lifecycle
+--------------------------------------------------
+
+Your script will be loaded by the player at program start from the ``scripts``
+configuration subdirectory, or from a path specified with the ``--script``
+option. Some scripts are loaded internally (like ``--osc``). Each script runs in
+its own thread. Your script is first run "as is", and once that is done, the event loop
+is entered. This event loop will dispatch events received by mpv and call your
+own event handlers which you have registered with ``mp.register_event``, or
+timers added with ``mp.add_timeout`` or similar. Note that since the
+script starts execution concurrently with player initialization, some properties
+may not be populated with meaningful values until the relevant subsystems have
+initialized.
+
+When the player quits, all scripts will be asked to terminate. This happens via
+a ``shutdown`` event, which by default will make the event loop return. If your
+script got into an endless loop, mpv will probably behave fine during playback,
+but it won't terminate when quitting, because it's waiting on your script.
+
+Internally, the C code will call the Lua function ``mp_event_loop`` after
+loading a Lua script. This function is normally defined by the default prelude
+loaded before your script (see ``player/lua/defaults.lua`` in the mpv sources).
+The event loop will wait for events and dispatch events registered with
+``mp.register_event``. It will also handle timers added with ``mp.add_timeout``
+and similar (by waiting with a timeout).
+
+Since mpv 0.6.0, the player will wait until the script is fully loaded before
+continuing normal operation. The player considers a script as fully loaded as
+soon as it starts waiting for mpv events (or it exits). In practice this means
+the player will more or less hang until the script returns from the main chunk
+(and ``mp_event_loop`` is called), or the script calls ``mp_event_loop`` or
+``mp.dispatch_events`` directly. This is done to make it possible for a script
+to fully setup event handlers etc. before playback actually starts. In older
+mpv versions, this happened asynchronously. With mpv 0.29.0, this changes
+slightly, and it merely waits for scripts to be loaded in this manner before
+starting playback as part of the player initialization phase. Scripts run though
+initialization in parallel. This might change again.
+
+mp functions
+------------
+
+The ``mp`` module is preloaded, although it can be loaded manually with
+``require 'mp'``. It provides the core client API.
+
+``mp.command(string)``
+    Run the given command. This is similar to the commands used in input.conf.
+    See `List of Input Commands`_.
+
+    By default, this will show something on the OSD (depending on the command),
+    as if it was used in ``input.conf``. See `Input Command Prefixes`_ how
+    to influence OSD usage per command.
+
+    Returns ``true`` on success, or ``nil, error`` on error.
+
+``mp.commandv(arg1, arg2, ...)``
+    Similar to ``mp.command``, but pass each command argument as separate
+    parameter. This has the advantage that you don't have to care about
+    quoting and escaping in some cases.
+
+    Example:
+
+    ::
+
+        mp.command("loadfile " .. filename .. " append")
+        mp.commandv("loadfile", filename, "append")
+
+    These two commands are equivalent, except that the first version breaks
+    if the filename contains spaces or certain special characters.
+
+    Note that properties are *not* expanded.  You can use either ``mp.command``,
+    the ``expand-properties`` prefix, or the ``mp.get_property`` family of
+    functions.
+
+    Unlike ``mp.command``, this will not use OSD by default either (except
+    for some OSD-specific commands).
+
+``mp.command_native(table [,def])``
+    Similar to ``mp.commandv``, but pass the argument list as table. This has
+    the advantage that in at least some cases, arguments can be passed as
+    native types. It also allows you to use named argument.
+
+    If the table is an array, each array item is like an argument in
+    ``mp.commandv()`` (but can be a native type instead of a string).
+
+    If the table contains string keys, it's interpreted as command with named
+    arguments. This requires at least an entry with the key ``name`` to be
+    present, which must be a string, and contains the command name. The special
+    entry ``_flags`` is optional, and if present, must be an array of
+    `Input Command Prefixes`_ to apply. All other entries are interpreted as
+    arguments.
+
+    Returns a result table on success (usually empty), or ``def, error`` on
+    error. ``def`` is the second parameter provided to the function, and is
+    nil if it's missing.
+
+``mp.command_native_async(table [,fn])``
+    Like ``mp.command_native()``, but the command is ran asynchronously (as far
+    as possible), and upon completion, fn is called. fn has three arguments:
+    ``fn(success, result, error)``:
+
+         ``success``
+            Always a Boolean and is true if the command was successful,
+            otherwise false.
+
+        ``result``
+            The result value (can be nil) in case of success, nil otherwise (as
+            returned by ``mp.command_native()``).
+
+        ``error``
+            The error string in case of an error, nil otherwise.
+
+    Returns a table with undefined contents, which can be used as argument for
+    ``mp.abort_async_command``.
+
+    If starting the command failed for some reason, ``nil, error`` is returned,
+    and ``fn`` is called indicating failure, using the same error value.
+
+    ``fn`` is always called asynchronously, even if the command failed to start.
+
+``mp.abort_async_command(t)``
+    Abort a ``mp.command_native_async`` call. The argument is the return value
+    of that command (which starts asynchronous execution of the command).
+    Whether this works and how long it takes depends on the command and the
+    situation. The abort call itself is asynchronous. Does not return anything.
+
+``mp.del_property(name)``
+    Delete the given property. See ``mp.get_property`` and `Properties`_ for more
+    information about properties. Most properties cannot be deleted.
+
+    Returns true on success, or ``nil, error`` on error.
+
+``mp.get_property(name [,def])``
+    Return the value of the given property as string. These are the same
+    properties as used in input.conf. See `Properties`_ for a list of
+    properties. The returned string is formatted similar to ``${=name}``
+    (see `Property Expansion`_).
+
+    Returns the string on success, or ``def, error`` on error. ``def`` is the
+    second parameter provided to the function, and is nil if it's missing.
+
+``mp.get_property_osd(name [,def])``
+    Similar to ``mp.get_property``, but return the property value formatted for
+    OSD. This is the same string as printed with ``${name}`` when used in
+    input.conf.
+
+    Returns the string on success, or ``def, error`` on error. ``def`` is the
+    second parameter provided to the function, and is an empty string if it's
+    missing. Unlike ``get_property()``, assigning the return value to a variable
+    will always result in a string.
+
+``mp.get_property_bool(name [,def])``
+    Similar to ``mp.get_property``, but return the property value as Boolean.
+
+    Returns a Boolean on success, or ``def, error`` on error.
+
+``mp.get_property_number(name [,def])``
+    Similar to ``mp.get_property``, but return the property value as number.
+
+    Note that while Lua does not distinguish between integers and floats,
+    mpv internals do. This function simply request a double float from mpv,
+    and mpv will usually convert integer property values to float.
+
+    Returns a number on success, or ``def, error`` on error.
+
+``mp.get_property_native(name [,def])``
+    Similar to ``mp.get_property``, but return the property value using the best
+    Lua type for the property. Most time, this will return a string, Boolean,
+    or number. Some properties (for example ``chapter-list``) are returned as
+    tables.
+
+    Returns a value on success, or ``def, error`` on error. Note that ``nil``
+    might be a possible, valid value too in some corner cases.
+
+``mp.set_property(name, value)``
+    Set the given property to the given string value. See ``mp.get_property``
+    and `Properties`_ for more information about properties.
+
+    Returns true on success, or ``nil, error`` on error.
+
+``mp.set_property_bool(name, value)``
+    Similar to ``mp.set_property``, but set the given property to the given
+    Boolean value.
+
+``mp.set_property_number(name, value)``
+    Similar to ``mp.set_property``, but set the given property to the given
+    numeric value.
+
+    Note that while Lua does not distinguish between integers and floats,
+    mpv internals do. This function will test whether the number can be
+    represented as integer, and if so, it will pass an integer value to mpv,
+    otherwise a double float.
+
+``mp.set_property_native(name, value)``
+    Similar to ``mp.set_property``, but set the given property using its native
+    type.
+
+    Since there are several data types which cannot represented natively in
+    Lua, this might not always work as expected. For example, while the Lua
+    wrapper can do some guesswork to decide whether a Lua table is an array
+    or a map, this would fail with empty tables. Also, there are not many
+    properties for which it makes sense to use this, instead of
+    ``set_property``, ``set_property_bool``, ``set_property_number``.
+    For these reasons, this function should probably be avoided for now, except
+    for properties that use tables natively.
+
+``mp.get_time()``
+    Return the current mpv internal time in seconds as a number. This is
+    basically the system time, with an arbitrary offset.
+
+``mp.add_key_binding(key, name|fn [,fn [,flags]])``
+    Register callback to be run on a key binding. The binding will be mapped to
+    the given ``key``, which is a string describing the physical key. This uses
+    the same key names as in input.conf, and also allows combinations
+    (e.g. ``ctrl+a``). If the key is empty or ``nil``, no physical key is
+    registered, but the user still can create own bindings (see below).
+
+    After calling this function, key presses will cause the function ``fn`` to
+    be called (unless the user remapped the key with another binding).
+
+    The ``name`` argument should be a short symbolic string. It allows the user
+    to remap the key binding via input.conf using the ``script-message``
+    command, and the name of the key binding (see below for
+    an example). The name should be unique across other bindings in the same
+    script - if not, the previous binding with the same name will be
+    overwritten. You can omit the name, in which case a random name is generated
+    internally. (Omitting works as follows: either pass ``nil`` for ``name``,
+    or pass the ``fn`` argument in place of the name. The latter is not
+    recommended and is handled for compatibility only.)
+
+    The last argument is used for optional flags. This is a table, which can
+    have the following entries:
+
+        ``repeatable``
+            If set to ``true``, enables key repeat for this specific binding.
+
+        ``complex``
+            If set to ``true``, then ``fn`` is called on both key up and down
+            events (as well as key repeat, if enabled), with the first
+            argument being a table. This table has the following entries (and
+            may contain undocumented ones):
+
+                ``event``
+                    Set to one of the strings ``down``, ``repeat``, ``up`` or
+                    ``press`` (the latter if key up/down can't be tracked).
+
+                ``is_mouse``
+                    Boolean Whether the event was caused by a mouse button.
+
+                ``key_name``
+                    The name of they key that triggered this, or ``nil`` if
+                    invoked artificially. If the key name is unknown, it's an
+                    empty string.
+
+                ``key_text``
+                    Text if triggered by a text key, otherwise ``nil``. See
+                    description of ``script-binding`` command for details (this
+                    field is equivalent to the 5th argument).
+
+    Internally, key bindings are dispatched via the ``script-message-to`` or
+    ``script-binding`` input commands and ``mp.register_script_message``.
+
+    Trying to map multiple commands to a key will essentially prefer a random
+    binding, while the other bindings are not called. It is guaranteed that
+    user defined bindings in the central input.conf are preferred over bindings
+    added with this function (but see ``mp.add_forced_key_binding``).
+
+    Example:
+
+    ::
+
+        function something_handler()
+            print("the key was pressed")
+        end
+        mp.add_key_binding("x", "something", something_handler)
+
+    This will print the message ``the key was pressed`` when ``x`` was pressed.
+
+    The user can remap these key bindings. Then the user has to put the
+    following into their input.conf to remap the command to the ``y`` key:
+
+    ::
+
+        y script-binding something
+
+
+    This will print the message when the key ``y`` is pressed. (``x`` will
+    still work, unless the user remaps it.)
+
+    You can also explicitly send a message to a named script only. Assume the
+    above script was using the filename ``fooscript.lua``:
+
+    ::
+
+        y script-binding fooscript/something
+
+``mp.add_forced_key_binding(...)``
+    This works almost the same as ``mp.add_key_binding``, but registers the
+    key binding in a way that will overwrite the user's custom bindings in their
+    input.conf. (``mp.add_key_binding`` overwrites default key bindings only,
+    but not those by the user's input.conf.)
+
+``mp.remove_key_binding(name)``
+    Remove a key binding added with ``mp.add_key_binding`` or
+    ``mp.add_forced_key_binding``. Use the same name as you used when adding
+    the bindings. It's not possible to remove bindings for which you omitted
+    the name.
+
+``mp.register_event(name, fn)``
+    Call a specific function when an event happens. The event name is a string,
+    and the function fn is a Lua function value.
+
+    Some events have associated data. This is put into a Lua table and passed
+    as argument to fn. The Lua table by default contains a ``name`` field,
+    which is a string containing the event name. If the event has an error
+    associated, the ``error`` field is set to a string describing the error,
+    on success it's not set.
+
+    If multiple functions are registered for the same event, they are run in
+    registration order, which the first registered function running before all
+    the other ones.
+
+    Returns true if such an event exists, false otherwise.
+
+    See `Events`_ and `List of events`_ for details.
+
+``mp.unregister_event(fn)``
+    Undo ``mp.register_event(..., fn)``. This removes all event handlers that
+    are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison,
+    so be careful when dealing with closures.
+
+``mp.observe_property(name, type, fn)``
+    Watch a property for changes. If the property ``name`` is changed, then
+    the function ``fn(name)`` will be called. ``type`` can be ``nil``, or be
+    set to one of ``none``, ``native``, ``bool``, ``string``, or ``number``.
+    ``none`` is the same as ``nil``. For all other values, the new value of
+    the property will be passed as second argument to ``fn``, using
+    ``mp.get_property_<type>`` to retrieve it. This means if ``type`` is for
+    example ``string``, ``fn`` is roughly called as in
+    ``fn(name, mp.get_property_string(name))``.
+
+    If possible, change events are coalesced. If a property is changed a bunch
+    of times in a row, only the last change triggers the change function. (The
+    exact behavior depends on timing and other things.)
+
+    If a property is unavailable, or on error, the value argument to ``fn`` is
+    ``nil``. (The ``observe_property()`` call always succeeds, even if a
+    property does not exist.)
+
+    In some cases the function is not called even if the property changes.
+    This depends on the property, and it's a valid feature request to ask for
+    better update handling of a specific property.
+
+    If the ``type`` is ``none`` or ``nil``, sporadic property change events are
+    possible. This means the change function ``fn`` can be called even if the
+    property doesn't actually change.
+
+    You always get an initial change notification. This is meant to initialize
+    the user's state to the current value of the property.
+
+``mp.unobserve_property(fn)``
+    Undo ``mp.observe_property(..., fn)``. This removes all property handlers
+    that are equal to the ``fn`` parameter. This uses normal Lua ``==``
+    comparison, so be careful when dealing with closures.
+
+``mp.add_timeout(seconds, fn [, disabled])``
+    Call the given function fn when the given number of seconds has elapsed.
+    Note that the number of seconds can be fractional. For now, the timer's
+    resolution may be as low as 50 ms, although this will be improved in the
+    future.
+
+    If the ``disabled`` argument is set to ``true`` or a truthy value, the
+    timer will wait to be manually started with a call to its ``resume()``
+    method.
+
+    This is a one-shot timer: it will be removed when it's fired.
+
+    Returns a timer object. See ``mp.add_periodic_timer`` for details.
+
+``mp.add_periodic_timer(seconds, fn [, disabled])``
+    Call the given function periodically. This is like ``mp.add_timeout``, but
+    the timer is re-added after the function fn is run.
+
+    Returns a timer object. The timer object provides the following methods:
+        ``stop()``
+            Disable the timer. Does nothing if the timer is already disabled.
+            This will remember the current elapsed time when stopping, so that
+            ``resume()`` essentially unpauses the timer.
+
+        ``kill()``
+            Disable the timer. Resets the elapsed time. ``resume()`` will
+            restart the timer.
+
+        ``resume()``
+            Restart the timer. If the timer was disabled with ``stop()``, this
+            will resume at the time it was stopped. If the timer was disabled
+            with ``kill()``, or if it's a previously fired one-shot timer (added
+            with ``add_timeout()``), this starts the timer from the beginning,
+            using the initially configured timeout.
+
+        ``is_enabled()``
+            Whether the timer is currently enabled or was previously disabled
+            (e.g. by ``stop()`` or ``kill()``).
+
+        ``timeout`` (RW)
+            This field contains the current timeout period. This value is not
+            updated as time progresses. It's only used to calculate when the
+            timer should fire next when the timer expires.
+
+            If you write this, you can call ``t:kill() ; t:resume()`` to reset
+            the current timeout to the new one. (``t:stop()`` won't use the
+            new timeout.)
+
+        ``oneshot`` (RW)
+            Whether the timer is periodic (``false``) or fires just once
+            (``true``). This value is used when the timer expires (but before
+            the timer callback function fn is run).
+
+    Note that these are methods, and you have to call them using ``:`` instead
+    of ``.`` (Refer to https://www.lua.org/manual/5.2/manual.html#3.4.9 .)
+
+    Example:
+
+    ::
+
+        seconds = 0
+        timer = mp.add_periodic_timer(1, function()
+            print("called every second")
+            # stop it after 10 seconds
+            seconds = seconds + 1
+            if seconds >= 10 then
+                timer:kill()
+            end
+        end)
+
+
+``mp.get_opt(key)``
+    Return a setting from the ``--script-opts`` option. It's up to the user and
+    the script how this mechanism is used. Currently, all scripts can access
+    this equally, so you should be careful about collisions.
+
+``mp.get_script_name()``
+    Return the name of the current script. The name is usually made of the
+    filename of the script, with directory and file extension removed. If
+    there are several scripts which would have the same name, it's made unique
+    by appending a number. Any nonalphanumeric characters are replaced with ``_``.
+
+    .. admonition:: Example
+
+        The script ``/path/to/foo-script.lua`` becomes ``foo_script``.
+
+``mp.get_script_directory()``
+    Return the directory if this is a script packaged as directory (see
+    `Script location`_ for a description). Return nothing if this is a single
+    file script.
+
+``mp.osd_message(text [,duration])``
+    Show an OSD message on the screen. ``duration`` is in seconds, and is
+    optional (uses ``--osd-duration`` by default).
+
+Advanced mp functions
+---------------------
+
+These also live in the ``mp`` module, but are documented separately as they
+are useful only in special situations.
+
+``mp.get_wakeup_pipe()``
+    Calls ``mpv_get_wakeup_pipe()`` and returns the read end of the wakeup
+    pipe. This is deprecated, but still works. (See ``client.h`` for details.)
+
+``mp.get_next_timeout()``
+    Return the relative time in seconds when the next timer (``mp.add_timeout``
+    and similar) expires. If there is no timer, return ``nil``.
+
+``mp.dispatch_events([allow_wait])``
+    This can be used to run custom event loops. If you want to have direct
+    control what the Lua script does (instead of being called by the default
+    event loop), you can set the global variable ``mp_event_loop`` to your
+    own function running the event loop. From your event loop, you should call
+    ``mp.dispatch_events()`` to dequeue and dispatch mpv events.
+
+    If the ``allow_wait`` parameter is set to ``true``, the function will block
+    until the next event is received or the next timer expires. Otherwise (and
+    this is the default behavior), it returns as soon as the event loop is
+    emptied. It's strongly recommended to use ``mp.get_next_timeout()`` and
+    ``mp.get_wakeup_pipe()`` if you're interested in properly working
+    notification of new events and working timers.
+
+``mp.register_idle(fn)``
+    Register an event loop idle handler. Idle handlers are called before the
+    script goes to sleep after handling all new events. This can be used for
+    example to delay processing of property change events: if you're observing
+    multiple properties at once, you might not want to act on each property
+    change, but only when all change notifications have been received.
+
+``mp.unregister_idle(fn)``
+    Undo ``mp.register_idle(fn)``. This removes all idle handlers that
+    are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison,
+    so be careful when dealing with closures.
+
+``mp.enable_messages(level)``
+    Set the minimum log level of which mpv message output to receive. These
+    messages are normally printed to the terminal. By calling this function,
+    you can set the minimum log level of messages which should be received with
+    the ``log-message`` event. See the description of this event for details.
+    The level is a string, see ``msg.log`` for allowed log levels.
+
+``mp.register_script_message(name, fn)``
+    This is a helper to dispatch ``script-message`` or ``script-message-to``
+    invocations to Lua functions. ``fn`` is called if ``script-message`` or
+    ``script-message-to`` (with this script as destination) is run
+    with ``name`` as first parameter. The other parameters are passed to ``fn``.
+    If a message with the given name is already registered, it's overwritten.
+
+    Used by ``mp.add_key_binding``, so be careful about name collisions.
+
+``mp.unregister_script_message(name)``
+    Undo a previous registration with ``mp.register_script_message``. Does
+    nothing if the ``name`` wasn't registered.
+
+``mp.create_osd_overlay(format)``
+    Create an OSD overlay. This is a very thin wrapper around the ``osd-overlay``
+    command. The function returns a table, which mostly contains fields that
+    will be passed to ``osd-overlay``. The ``format`` parameter is used to
+    initialize the ``format`` field. The ``data`` field contains the text to
+    be used as overlay. For details, see the ``osd-overlay`` command.
+
+    In addition, it provides the following methods:
+
+    ``update()``
+        Commit the OSD overlay to the screen, or in other words, run the
+        ``osd-overlay`` command with the current fields of the overlay table.
+        Returns the result of the ``osd-overlay`` command itself.
+
+    ``remove()``
+        Remove the overlay from the screen. A ``update()`` call will add it
+        again.
+
+    Example:
+
+    ::
+
+        ov = mp.create_osd_overlay("ass-events")
+        ov.data = "{\\an5}{\\b1}hello world!"
+        ov:update()
+
+    The advantage of using this wrapper (as opposed to running ``osd-overlay``
+    directly) is that the ``id`` field is allocated automatically.
+
+``mp.get_osd_size()``
+    Returns a tuple of ``osd_width, osd_height, osd_par``. The first two give
+    the size of the OSD in pixels (for video outputs like ``--vo=xv``, this may
+    be "scaled" pixels). The third is the display pixel aspect ratio.
+
+    May return invalid/nonsense values if OSD is not initialized yet.
+
+mp.msg functions
+----------------
+
+This module allows outputting messages to the terminal, and can be loaded
+with ``require 'mp.msg'``.
+
+``msg.log(level, ...)``
+    The level parameter is the message priority. It's a string and one of
+    ``fatal``, ``error``, ``warn``, ``info``, ``v``, ``debug``, ``trace``. The
+    user's settings will determine which of these messages will be
+    visible. Normally, all messages are visible, except ``v``, ``debug`` and
+    ``trace``.
+
+    The parameters after that are all converted to strings. Spaces are inserted
+    to separate multiple parameters.
+
+    You don't need to add newlines.
+
+``msg.fatal(...)``, ``msg.error(...)``, ``msg.warn(...)``, ``msg.info(...)``, ``msg.verbose(...)``, ``msg.debug(...)``, ``msg.trace(...)``
+    All of these are shortcuts and equivalent to the corresponding
+    ``msg.log(level, ...)`` call.
+
+mp.options functions
+--------------------
+
+mpv comes with a built-in module to manage options from config-files and the
+command-line. All you have to do is to supply a table with default options to
+the read_options function. The function will overwrite the default values
+with values found in the config-file and the command-line (in that order).
+
+``options.read_options(table [, identifier [, on_update]])``
+    A ``table`` with key-value pairs. The type of the default values is
+    important for converting the values read from the config file or
+    command-line back. Do not use ``nil`` as a default value!
+
+    The ``identifier`` is used to identify the config-file and the command-line
+    options. These needs to unique to avoid collisions with other scripts.
+    Defaults to ``mp.get_script_name()`` if the parameter is ``nil`` or missing.
+
+    The ``on_update`` parameter enables run-time updates of all matching option
+    values via the ``script-opts`` option/property. If any of the matching
+    options changes, the values in the ``table`` (which was originally passed to
+    the function) are changed, and ``on_update(list)`` is called. ``list`` is
+    a table where each updated option has a ``list[option_name] = true`` entry.
+    There is no initial ``on_update()`` call. This never re-reads the config file.
+    ``script-opts`` is always applied on the original config file, ignoring
+    previous ``script-opts`` values (for example, if an option is removed from
+    ``script-opts`` at runtime, the option will have the value in the config
+    file). ``table`` entries are only written for option values whose values
+    effectively change (this is important if the script changes ``table``
+    entries independently).
+
+
+Example implementation::
+
+    local options = {
+        optionA = "defaultvalueA",
+        optionB = -0.5,
+        optionC = true,
+    }
+
+    require "mp.options".read_options(options, "myscript")
+    print(options.optionA)
+
+
+The config file will be stored in ``script-opts/identifier.conf`` in mpv's user
+folder. Comment lines can be started with # and stray spaces are not removed.
+Boolean values will be represented with yes/no.
+
+Example config::
+
+    # comment
+    optionA=Hello World
+    optionB=9999
+    optionC=no
+
+
+Command-line options are read from the ``--script-opts`` parameter. To avoid
+collisions, all keys have to be prefixed with ``identifier-``.
+
+Example command-line::
+
+     --script-opts=myscript-optionA=TEST,myscript-optionB=0,myscript-optionC=yes
+
+
+mp.utils functions
+------------------
+
+This built-in module provides generic helper functions for Lua, and have
+strictly speaking nothing to do with mpv or video/audio playback. They are
+provided for convenience. Most compensate for Lua's scarce standard library.
+
+Be warned that any of these functions might disappear any time. They are not
+strictly part of the guaranteed API.
+
+``utils.getcwd()``
+    Returns the directory that mpv was launched from. On error, ``nil, error``
+    is returned.
+
+``utils.readdir(path [, filter])``
+    Enumerate all entries at the given path on the filesystem, and return them
+    as array. Each entry is a directory entry (without the path).
+    The list is unsorted (in whatever order the operating system returns it).
+
+    If the ``filter`` argument is given, it must be one of the following
+    strings:
+
+        ``files``
+            List regular files only. This excludes directories, special files
+            (like UNIX device files or FIFOs), and dead symlinks. It includes
+            UNIX symlinks to regular files.
+
+        ``dirs``
+            List directories only, or symlinks to directories. ``.`` and ``..``
+            are not included.
+
+        ``normal``
+            Include the results of both ``files`` and ``dirs``. (This is the
+            default.)
+
+        ``all``
+            List all entries, even device files, dead symlinks, FIFOs, and the
+            ``.`` and ``..`` entries.
+
+    On error, ``nil, error`` is returned.
+
+``utils.file_info(path)``
+    Stats the given path for information and returns a table with the
+    following entries:
+
+        ``mode``
+            protection bits (on Windows, always 755 (octal) for directories
+            and 644 (octal) for files)
+        ``size``
+            size in bytes
+        ``atime``
+            time of last access
+        ``mtime``
+            time of last modification
+        ``ctime``
+            time of last metadata change
+        ``is_file``
+            Whether ``path`` is a regular file (boolean)
+        ``is_dir``
+            Whether ``path`` is a directory (boolean)
+
+    ``mode`` and ``size`` are integers.
+    Timestamps (``atime``, ``mtime`` and ``ctime``) are integer seconds since
+    the Unix epoch (Unix time).
+    The booleans ``is_file`` and ``is_dir`` are provided as a convenience;
+    they can be and are derived from ``mode``.
+
+    On error (e.g. path does not exist), ``nil, error`` is returned.
+
+``utils.split_path(path)``
+    Split a path into directory component and filename component, and return
+    them. The first return value is always the directory. The second return
+    value is the trailing part of the path, the directory entry.
+
+``utils.join_path(p1, p2)``
+    Return the concatenation of the 2 paths. Tries to be clever. For example,
+    if ``p2`` is an absolute path, ``p2`` is returned without change.
+
+``utils.subprocess(t)``
+    Runs an external process and waits until it exits. Returns process status
+    and the captured output. This is a legacy wrapper around calling the
+    ``subprocess`` command with ``mp.command_native``. It does the following
+    things:
+
+    - copy the table ``t``
+    - rename ``cancellable`` field to ``playback_only``
+    - rename ``max_size`` to ``capture_size``
+    - set ``capture_stdout`` field to ``true`` if unset
+    - set ``name`` field to ``subprocess``
+    - call ``mp.command_native(copied_t)``
+    - if the command failed, create a dummy result table
+    - copy ``error_string`` to ``error`` field if the string is non-empty
+    - return the result table
+
+    It is recommended to use ``mp.command_native`` or ``mp.command_native_async``
+    directly, instead of calling this legacy wrapper. It is for compatibility
+    only.
+
+    See the ``subprocess`` documentation for semantics and further parameters.
+
+``utils.subprocess_detached(t)``
+    Runs an external process and detaches it from mpv's control.
+
+    The parameter ``t`` is a table. The function reads the following entries:
+
+        ``args``
+            Array of strings of the same semantics as the ``args`` used in the
+            ``subprocess`` function.
+
+    The function returns ``nil``.
+
+    This is a legacy wrapper around calling the ``run`` command with
+    ``mp.commandv`` and other functions.
+
+``utils.getpid()``
+    Returns the process ID of the running mpv process. This can be used to identify
+    the calling mpv when launching (detached) subprocesses.
+
+``utils.get_env_list()``
+    Returns the C environment as a list of strings. (Do not confuse this with
+    the Lua "environment", which is an unrelated concept.)
+
+``utils.parse_json(str [, trail])``
+    Parses the given string argument as JSON, and returns it as a Lua table. On
+    error, returns ``nil, error``. (Currently, ``error`` is just a string
+    reading ``error``, because there is no fine-grained error reporting of any
+    kind.)
+
+    The returned value uses similar conventions as ``mp.get_property_native()``
+    to distinguish empty objects and arrays.
+
+    If the ``trail`` parameter is ``true`` (or any value equal to ``true``),
+    then trailing non-whitespace text is tolerated by the function, and the
+    trailing text is returned as 3rd return value. (The 3rd return value is
+    always there, but with ``trail`` set, no error is raised.)
+
+``utils.format_json(v)``
+    Format the given Lua table (or value) as a JSON string and return it. On
+    error, returns ``nil, error``. (Errors usually only happen on value types
+    incompatible with JSON.)
+
+    The argument value uses similar conventions as ``mp.set_property_native()``
+    to distinguish empty objects and arrays.
+
+``utils.to_string(v)``
+    Turn the given value into a string. Formats tables and their contents. This
+    doesn't do anything special; it is only needed because Lua is terrible.
+
+Events
+------
+
+Events are notifications from player core to scripts. You can register an
+event handler with ``mp.register_event``.
+
+Note that all scripts (and other parts of the player) receive events equally,
+and there's no such thing as blocking other scripts from receiving events.
+
+Example:
+
+::
+
+    function my_fn(event)
+        print("start of playback!")
+    end
+
+    mp.register_event("file-loaded", my_fn)
+
+For the existing event types, see `List of events`_.
+
+Extras
+------
+
+This documents experimental features, or features that are "too special" to
+guarantee a stable interface.
+
+``mp.add_hook(type, priority, fn)``
+    Add a hook callback for ``type`` (a string identifying a certain kind of
+    hook). These hooks allow the player to call script functions and wait for
+    their result (normally, the Lua scripting interface is asynchronous from
+    the point of view of the player core). ``priority`` is an arbitrary integer
+    that allows ordering among hooks of the same kind. Using the value 50 is
+    recommended as neutral default value.
+
+    ``fn(hook)`` is the function that will be called during execution of the
+    hook. The parameter passed to it (``hook``) is a Lua object that can control
+    further aspects about the currently invoked hook. It provides the following
+    methods:
+
+        ``defer()``
+            Returning from the hook function should not automatically continue
+            the hook. Instead, the API user wants to call ``hook:cont()`` on its
+            own at a later point in time (before or after the function has
+            returned).
+
+        ``cont()``
+            Continue the hook. Doesn't need to be called unless ``defer()`` was
+            called.
+
+    See `Hooks`_ for currently existing hooks and what they do - only the hook
+    list is interesting; handling hook execution is done by the Lua script
+    function automatically.
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
new file mode 100644
index 0000000..e97422d
--- /dev/null
+++ b/DOCS/man/mpv.rst
@@ -0,0 +1,1690 @@
+mpv
+###
+
+##############
+a media player
+##############
+
+:Copyright: GPLv2+
+:Manual section: 1
+:Manual group: multimedia
+
+.. contents:: Table of Contents
+
+SYNOPSIS
+========
+
+| **mpv** [options] [file|URL|PLAYLIST|-]
+| **mpv** [options] files
+
+DESCRIPTION
+===========
+
+**mpv** is a media player based on MPlayer and mplayer2. It supports a wide variety of video
+file formats, audio and video codecs, and subtitle types. Special input URL
+types are available to read input from a variety of sources other than disk
+files. Depending on platform, a variety of different video and audio output
+methods are supported.
+
+Usage examples to get you started quickly can be found at the end of this man
+page.
+
+
+INTERACTIVE CONTROL
+===================
+
+mpv has a fully configurable, command-driven control layer which allows you
+to control mpv using keyboard, mouse, or remote control (there is no
+LIRC support - configure remotes as input devices instead).
+
+See the ``--input-`` options for ways to customize it.
+
+The following listings are not necessarily complete. See ``etc/input.conf``
+in the mpv source files for a list of default bindings. User ``input.conf``
+files and Lua scripts can define additional key bindings.
+
+See `COMMAND INTERFACE`_ and `Key names`_ sections for more details on
+configuring keybindings.
+
+See also ``--input-test`` for interactive binding details by key, and the
+`stats`_ built-in script for key bindings list (including print to terminal).
+
+Keyboard Control
+----------------
+
+LEFT and RIGHT
+    Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek
+    (see ``--hr-seek``).
+
+UP and DOWN
+    Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see
+    ``--hr-seek``).
+
+Ctrl+LEFT and Ctrl+RIGHT
+    Seek to the previous/next subtitle. Subject to some restrictions and
+    might not always work; see ``sub-seek`` command.
+
+Ctrl+Shift+LEFT and Ctrl+Shift+RIGHT
+    Adjust subtitle delay so that the next or previous subtitle is displayed
+    now. This is especially useful to sync subtitles to audio.
+
+[ and ]
+    Decrease/increase current playback speed by 10%.
+
+{ and }
+    Halve/double current playback speed.
+
+BACKSPACE
+    Reset playback speed to normal.
+
+Shift+BACKSPACE
+    Undo the last seek. This works only if the playlist entry was not changed.
+    Hitting it a second time will go back to the original position.
+    See ``revert-seek`` command for details.
+
+Shift+Ctrl+BACKSPACE
+    Mark the current position. This will then be used by ``Shift+BACKSPACE``
+    as revert position (once you seek back, the marker will be reset). You can
+    use this to seek around in the file and then return to the exact position
+    where you left off.
+
+< and >
+    Go backward/forward in the playlist.
+
+ENTER
+    Go forward in the playlist.
+
+p and SPACE
+    Pause (pressing again unpauses).
+
+\.
+    Step forward. Pressing once will pause, every consecutive press will
+    play one frame and then go into pause mode again.
+
+,
+    Step backward. Pressing once will pause, every consecutive press will
+    play one frame in reverse and then go into pause mode again.
+
+q
+    Stop playing and quit.
+
+Q
+    Like ``q``, but store the current playback position. Playing the same file
+    later will resume at the old playback position if possible. See
+    `RESUMING PLAYBACK`_.
+
+/ and *
+    Decrease/increase volume.
+
+9 and 0
+    Decrease/increase volume.
+
+m
+    Mute sound.
+
+\_
+    Cycle through the available video tracks.
+
+\#
+    Cycle through the available audio tracks.
+
+E
+    Cycle through the available Editions.
+
+f
+    Toggle fullscreen (see also ``--fs``).
+
+ESC
+    Exit fullscreen mode.
+
+T
+    Toggle stay-on-top (see also ``--ontop``).
+
+w and W
+    Decrease/increase pan-and-scan range. The ``e`` key does the same as
+    ``W`` currently, but use is discouraged.
+
+o and P
+    Show progression bar, elapsed time and total duration on the OSD.
+
+O
+    Toggle OSD states between normal and playback time/duration.
+
+v
+    Toggle subtitle visibility.
+
+j and J
+    Cycle through the available subtitles.
+
+z and Z
+    Adjust subtitle delay by +/- 0.1 seconds. The ``x`` key does the same as
+    ``Z`` currently, but use is discouraged.
+
+l
+    Set/clear A-B loop points. See ``ab-loop`` command for details.
+
+L
+    Toggle infinite looping.
+
+Ctrl++ and Ctrl+-
+    Adjust audio delay (A/V sync) by +/- 0.1 seconds.
+
+Shift+g and Shift+f
+    Adjust subtitle font size by +/- 10%.
+
+u
+    Switch between applying only ``--sub-ass-*`` overrides (default) to SSA/ASS
+    subtitles, and overriding them almost completely with the normal subtitle
+    style. See ``--sub-ass-override`` for more info.
+
+V
+    Toggle subtitle VSFilter aspect compatibility mode. See
+    ``--sub-ass-vsfilter-aspect-compat`` for more info.
+
+r and R
+    Move subtitles up/down. The ``t`` key does the same as ``R`` currently, but
+    use is discouraged.
+
+s
+    Take a screenshot.
+
+S
+    Take a screenshot, without subtitles. (Whether this works depends on VO
+    driver support.)
+
+Ctrl+s
+    Take a screenshot, as the window shows it (with subtitles, OSD, and scaled
+    video).
+
+PGUP and PGDWN
+    Seek to the beginning of the previous/next chapter. In most cases,
+    "previous" will actually go to the beginning of the current chapter; see
+    ``--chapter-seek-threshold``.
+
+Shift+PGUP and Shift+PGDWN
+    Seek backward or forward by 10 minutes. (This used to be mapped to
+    PGUP/PGDWN without Shift.)
+
+d
+    Activate/deactivate deinterlacer.
+
+A
+    Cycle aspect ratio override.
+
+Ctrl+h
+    Toggle hardware video decoding on/off.
+
+Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
+    Move the video rectangle (panning).
+
+Alt++ and Alt+-
+    Combining ``Alt`` with the ``+`` or ``-`` keys changes video zoom.
+
+Alt+BACKSPACE
+    Reset the pan/zoom settings.
+
+F8
+    Show the playlist and the current position in it (useful only if a UI window
+    is used, broken on the terminal).
+
+F9
+    Show the list of audio and subtitle streams (useful only if a UI window  is
+    used, broken on the terminal).
+
+i and I
+    Show/toggle an overlay displaying statistics about the currently playing
+    file such as codec, framerate, number of dropped frames and so on. See
+    `STATS`_ for more information.
+
+DEL
+    Cycle OSC visibility between never / auto (mouse-move) / always
+
+\`
+    Show the console. (ESC closes it again. See `CONSOLE`_.)
+
+(The following keys are valid only when using a video output that supports the
+corresponding adjustment.)
+
+1 and 2
+    Adjust contrast.
+
+3 and 4
+    Adjust brightness.
+
+5 and 6
+    Adjust gamma.
+
+7 and 8
+    Adjust saturation.
+
+Alt+0 (and Command+0 on macOS)
+    Resize video window to half its original size.
+
+Alt+1 (and Command+1 on macOS)
+    Resize video window to its original size.
+
+Alt+2 (and Command+2 on macOS)
+    Resize video window to double its original size.
+
+Command + f (macOS only)
+    Toggle fullscreen (see also ``--fs``).
+
+(The following keys are valid if you have a keyboard with multimedia keys.)
+
+PAUSE
+    Pause.
+
+STOP
+    Stop playing and quit.
+
+PREVIOUS and NEXT
+    Seek backward/forward 1 minute.
+
+ZOOMIN and ZOOMOUT
+    Changes video zoom.
+
+If you miss some older key bindings, look at ``etc/restore-old-bindings.conf``
+in the mpv git repository.
+
+Mouse Control
+-------------
+
+Left double click
+    Toggle fullscreen on/off.
+
+Right click
+    Toggle pause on/off.
+
+Forward/Back button
+    Skip to next/previous entry in playlist.
+
+Wheel up/down
+    Decrease/increase volume.
+
+Wheel left/right
+    Seek forward/backward 10 seconds.
+
+
+USAGE
+=====
+
+Command line arguments starting with ``-`` are interpreted as options,
+everything else as filenames or URLs. All options except *flag* options (or
+choice options which include ``yes``) require a parameter in the form
+``--option=value``.
+
+One exception is the lone ``-`` (without anything else), which means media data
+will be read from stdin. Also, ``--`` (without anything else) will make the
+player interpret all following arguments as filenames, even if they start with
+``-``. (To play a file named ``-``, you need to use ``./-``.)
+
+Every *flag* option has a *no-flag* counterpart, e.g. the opposite of the
+``--fs`` option is ``--no-fs``. ``--fs=yes`` is same as ``--fs``, ``--fs=no``
+is the same as ``--no-fs``.
+
+If an option is marked as *(XXX only)*, it will only work in combination with
+the *XXX* option or if *XXX* is compiled in.
+
+Legacy option syntax
+--------------------
+
+The ``--option=value`` syntax is not strictly enforced, and the alternative
+legacy syntax ``-option value`` and ``-option=value`` will also work. This is
+mostly  for compatibility with MPlayer. Using these should be avoided. Their
+semantics can change any time in the future.
+
+For example, the alternative syntax will consider an argument following the
+option a filename. ``mpv -fs no`` will attempt to play a file named ``no``,
+because ``--fs`` is a flag option that requires no parameter. If an option
+changes and its parameter becomes optional, then a command line using the
+alternative syntax will break.
+
+Until mpv 0.31.0, there was no difference whether an option started with ``--``
+or a single ``-``. Newer mpv releases strictly expect that you pass the option
+value after a ``=``. For example, before ``mpv --log-file f.txt`` would write
+a log to ``f.txt``, but now this command line fails, as ``--log-file`` expects
+an option value, and ``f.txt`` is simply considered a normal file to be played
+(as in ``mpv f.txt``).
+
+The future plan is that ``-option value`` will not work anymore, and options
+with a single ``-`` behave the same as ``--`` options.
+
+Escaping spaces and other special characters
+--------------------------------------------
+
+Keep in mind that the shell will partially parse and mangle the arguments you
+pass to mpv. For example, you might need to quote or escape options and
+filenames:
+
+    ``mpv "filename with spaces.mkv" --title="window title"``
+
+It gets more complicated if the suboption parser is involved. The suboption
+parser puts several options into a single string, and passes them to a
+component at once, instead of using multiple options on the level of the
+command line.
+
+The suboption parser can quote strings with ``"`` and ``[...]``.
+Additionally, there is a special form of quoting with ``%n%`` described below.
+
+For example, assume the hypothetical ``foo`` filter can take multiple options:
+
+    ``mpv test.mkv --vf=foo:option1=value1:option2:option3=value3,bar``
+
+This passes ``option1`` and ``option3`` to the ``foo`` filter, with ``option2``
+as flag (implicitly ``option2=yes``), and adds a ``bar`` filter after that. If
+an option contains spaces or characters like ``,`` or ``:``, you need to quote
+them:
+
+    ``mpv '--vf=foo:option1="option value with spaces",bar'``
+
+Shells may actually strip some quotes from the string passed to the commandline,
+so the example quotes the string twice, ensuring that mpv receives the ``"``
+quotes.
+
+The ``[...]`` form of quotes wraps everything between ``[`` and ``]``. It's
+useful with shells that don't interpret these characters in the middle of
+an argument (like bash). These quotes are balanced (since mpv 0.9.0): the ``[``
+and ``]`` nest, and the quote terminates on the last ``]`` that has no matching
+``[`` within the string. (For example, ``[a[b]c]`` results in ``a[b]c``.)
+
+The fixed-length quoting syntax is intended for use with external
+scripts and programs.
+
+It is started with ``%`` and has the following format::
+
+    %n%string_of_length_n
+
+.. admonition:: Examples
+
+    ``mpv '--vf=foo:option1=%11%quoted text' test.avi``
+
+    Or in a script:
+
+    ``mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi``
+
+Note: where applicable with JSON-IPC, ``%n%`` is the length in UTF-8 bytes,
+after decoding the JSON data.
+
+Suboptions passed to the client API are also subject to escaping. Using
+``mpv_set_option_string()`` is exactly like passing ``--name=data`` to the
+command line (but without shell processing of the string). Some options
+support passing values in a more structured way instead of flat strings, and
+can avoid the suboption parsing mess. For example, ``--vf`` supports
+``MPV_FORMAT_NODE``, which lets you pass suboptions as a nested data structure
+of maps and arrays.
+
+Paths
+-----
+
+Some care must be taken when passing arbitrary paths and filenames to mpv. For
+example, paths starting with ``-`` will be interpreted as options. Likewise,
+if a path contains the sequence ``://``, the string before that might be
+interpreted as protocol prefix, even though ``://`` can be part of a legal
+UNIX path. To avoid problems with arbitrary paths, you should be sure that
+absolute paths passed to mpv start with ``/``, and prefix relative paths with
+``./``.
+
+Using the ``file://`` pseudo-protocol is discouraged, because it involves
+strange URL unescaping rules.
+
+The name ``-`` itself is interpreted as stdin, and will cause mpv to disable
+console controls. (Which makes it suitable for playing data piped to stdin.)
+
+The special argument ``--`` can be used to stop mpv from interpreting the
+following arguments as options.
+
+When using the client API, you should strictly avoid using ``mpv_command_string``
+for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command``
+to avoid the need for filename escaping.
+
+For paths passed to suboptions, the situation is further complicated by the
+need to escape special characters. To work this around, the path can be
+additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n``
+(see above).
+
+Some mpv options interpret paths starting with ``~``.
+Currently, the prefix ``~~home/`` expands to the mpv configuration directory
+(usually ``~/.config/mpv/``).
+``~/`` expands to the user's home directory. (The trailing ``/`` is always
+required.) The following paths are currently recognized:
+
+================ ===============================================================
+Name             Meaning
+================ ===============================================================
+``~~/``          If the subpath exists in any of the mpv's config directories
+                 the path of the existing file/dir is returned. Otherwise this
+                 is equivalent to ``~~home/``.
+                 Note that if --no-config is used ``~~/foobar`` will resolve to
+                 ``foobar`` which can be unexpected.
+``~/``           user home directory root (similar to shell, ``$HOME``)
+``~~home/``      mpv config dir (for example ``~/.config/mpv/``)
+``~~global/``    the global config path, if available (not on win32)
+``~~osxbundle/`` the macOS bundle resource path (macOS only)
+``~~desktop/``   the path to the desktop (win32, macOS)
+``~~exe_dir/``   win32 only: the path to the directory containing the exe (for
+                 config file purposes; ``$MPV_HOME`` overrides it)
+``~~cache/``     the path to application cache data (``~/.cache/mpv/``)
+                 On some platforms, this will be the same as ``~~home/``.
+``~~state/``     the path to application state data (``~/.local/state/mpv/``)
+                 On some platforms, this will be the same as ``~~home/``.
+``~~old_home/``  do not use
+================ ===============================================================
+
+
+Per-File Options
+----------------
+
+When playing multiple files, any option given on the command line usually
+affects all files. Example::
+
+    mpv --a file1.mkv --b file2.mkv --c
+
+=============== ===========================
+File            Active options
+=============== ===========================
+file1.mkv       ``--a --b --c``
+file2.mkv       ``--a --b --c``
+=============== ===========================
+
+(This is different from MPlayer and mplayer2.)
+
+Also, if any option is changed at runtime (via input commands), they are not
+reset when a new file is played.
+
+Sometimes, it is useful to change options per-file. This can be achieved by
+adding the special per-file markers ``--{`` and ``--}``. (Note that you must
+escape these on some shells.) Example::
+
+    mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f
+
+=============== ===========================
+File            Active options
+=============== ===========================
+file1.mkv       ``--a --b --f``
+file2.mkv       ``--a --b --f --c --d --e``
+file3.mkv       ``--a --b --f --c --d --e``
+file4.mkv       ``--a --b --f``
+=============== ===========================
+
+Additionally, any file-local option changed at runtime is reset when the current
+file stops playing. If option ``--c`` is changed during playback of
+``file2.mkv``, it is reset when advancing to ``file3.mkv``. This only affects
+file-local options. The option ``--a`` is never reset here.
+
+
+List Options
+------------
+
+Some options which store lists of option values can have action suffixes. For
+example, the ``--display-tags`` option takes a ``,``-separated list of tags, but
+the option also allows you to append a single tag with ``--display-tags-append``,
+and the tag name can for example contain a literal ``,`` without the need for
+escaping.
+
+String list and path list options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+String lists are separated by ``,``. The strings are not parsed or interpreted
+by the option system itself. However, most path or file list options use ``:``
+(Unix) or ``;`` (Windows) as separator, instead of ``,``.
+
+They support the following operations:
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-set          Set a list of items (using the list separator, escaped with backslash)
+-append       Append single item (does not interpret escapes)
+-add          Append 1 or more items (same syntax as -set)
+-pre          Prepend 1 or more items (same syntax as -set)
+-clr          Clear the option (remove all items)
+-remove       Delete item if present (does not interpret escapes)
+-toggle       Append an item, or remove if if it already exists (no escapes)
+============= ===============================================
+
+``-append`` is meant as a simple way to append a single item without having
+to escape the argument (you may still need to escape on the shell level).
+
+Key/value list options
+~~~~~~~~~~~~~~~~~~~~~~
+
+A key/value list is a list of key/value string pairs. In programming languages,
+this type of data structure is often called a map or a dictionary. The order
+normally does not matter, although in some cases the order might matter.
+
+They support the following operations:
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-set          Set a list of items (using ``,`` as separator)
+-append       Append a single item (escapes for the key, no escapes for the value)
+-add          Append 1 or more items (same syntax as -set)
+-remove       Delete item by key if present (does not interpret escapes)
+============= ===============================================
+
+Keys are unique within the list. If an already present key is set, the existing
+key is removed before the new value is appended.
+
+If you want to pass a value without interpreting it for escapes or ``,``, it is
+recommended to use the ``-append`` variant. When using libmpv, prefer using
+``MPV_FORMAT_NODE_MAP``; when using a scripting backend or the JSON IPC, use an
+appropriate structured data type.
+
+Prior to mpv 0.33, ``:`` was also recognized as separator by ``-set``.
+
+Filter options
+~~~~~~~~~~~~~~
+
+This is a very complex option type for the ``--af`` and ``--vf`` options only.
+They often require complicated escaping. See `VIDEO FILTERS`_ for details. They
+support the following operations:
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-set          Set a list of filters (using ``,`` as separator)
+-append       Append single filter
+-add          Append 1 or more filters (same syntax as -set)
+-pre          Prepend 1 or more filters (same syntax as -set)
+-clr          Clear the option (remove all filters)
+-remove       Delete filter if present
+-toggle       Append a filter, or remove if if it already exists
+-help         Pseudo operation that prints a help text to the terminal
+============= ===============================================
+
+General
+~~~~~~~
+
+Without suffix, the operation used is normally ``-set``.
+
+Although some operations allow specifying multiple items, using this is strongly
+discouraged and deprecated, except for ``-set``. There is a chance that
+operations like ``-add`` and ``-pre`` will work like ``-append`` and accept a
+single, unescaped item only (so the ``,`` separator will not be interpreted and
+is passed on as part of the value).
+
+Some options (like ``--sub-file``, ``--audio-file``, ``--glsl-shader``) are
+aliases for the proper option with ``-append`` action. For example,
+``--sub-file`` is an alias for ``--sub-files-append``.
+
+Options of this type can be changed at runtime using the ``change-list``
+command, which takes the suffix (without the ``-``) as separate operation
+parameter.
+
+CONFIGURATION FILES
+===================
+
+Location and Syntax
+-------------------
+
+You can put all of the options in configuration files which will be read every
+time mpv is run. The system-wide configuration file 'mpv.conf' is in your
+configuration directory (e.g. ``/etc/mpv`` or ``/usr/local/etc/mpv``), the
+user-specific one is ``~/.config/mpv/mpv.conf``. For details and platform
+specifics (in particular Windows paths) see the `FILES`_ section.
+
+User-specific options override system-wide options and options given on the
+command line override both. The syntax of the configuration files is
+``option=value``. Everything after a *#* is considered a comment. Options that
+work without values can be enabled by setting them to *yes* and disabled by
+setting them to *no*, and if the value is omitted, *yes* is implied. Even
+suboptions can be specified in this way.
+
+.. admonition:: Example configuration file
+
+    ::
+
+        # Don't allow new windows to be larger than the screen.
+        autofit-larger=100%x100%
+        # Enable hardware decoding if available, =yes is implied.
+        hwdec
+        # Spaces don't have to be escaped.
+        osd-playing-msg=File: ${filename}
+
+Escaping special characters
+--------------------------------------
+
+This is done like with command line options. A config entry can be quoted with
+``"``, ``'``, as well as with the fixed-length syntax (``%n%``) mentioned
+before. This is like passing the exact contents of the quoted string as a
+command line option. C-style escapes are currently _not_ interpreted on this
+level, although some options do this manually (this is a mess and should
+probably be changed at some point). The shell is not involved here, so option
+values only need to be quoted to escape ``#`` and ``\``, ``"``, ``'`` or ``%``
+at the beginning of the value, and leading and trailing whitespace.
+
+Putting Command Line Options into the Configuration File
+--------------------------------------------------------
+
+Almost all command line options can be put into the configuration file. Here
+is a small guide:
+
+======================= ========================
+Option                  Configuration file entry
+======================= ========================
+``--flag``              ``flag``
+``-opt val``            ``opt=val``
+``--opt=val``           ``opt=val``
+``-opt "has spaces"``   ``opt=has spaces``
+======================= ========================
+
+File-specific Configuration Files
+---------------------------------
+
+You can also write file-specific configuration files. If you wish to have a
+configuration file for a file called 'video.avi', create a file named
+'video.avi.conf' with the file-specific options in it and put it in
+``~/.config/mpv/``. You can also put the configuration file in the same directory
+as the file to be played. Both require you to set the ``--use-filedir-conf``
+option (either on the command line or in your global config file). If a
+file-specific configuration file is found in the same directory, no
+file-specific configuration is loaded from ``~/.config/mpv``. In addition, the
+``--use-filedir-conf`` option enables directory-specific configuration files.
+For this, mpv first tries to load a mpv.conf from the same directory
+as the file played and then tries to load any file-specific configuration.
+
+
+Profiles
+--------
+
+To ease working with different configurations, profiles can be defined in the
+configuration files. A profile starts with its name in square brackets,
+e.g. ``[my-profile]``. All following options will be part of the profile. A
+description (shown by ``--profile=help``) can be defined with the
+``profile-desc`` option. To end the profile, start another one or use the
+profile name ``default`` to continue with normal options.
+
+You can list profiles with ``--profile=help``, and show the contents of a
+profile with ``--show-profile=<name>`` (replace ``<name>`` with the profile
+name). You can apply profiles on start with the ``--profile=<name>`` option,
+or at runtime with the ``apply-profile <name>`` command.
+
+.. admonition:: Example mpv config file with profiles
+
+    ::
+
+        # normal top-level option
+        fullscreen=yes
+
+        # a profile that can be enabled with --profile=big-cache
+        [big-cache]
+        cache=yes
+        demuxer-max-bytes=123400KiB
+        demuxer-readahead-secs=20
+
+        [slow]
+        profile-desc="some profile name"
+        # reference a builtin profile
+        profile=high-quality
+
+        [fast]
+        vo=vdpau
+
+        # using a profile again extends it
+        [slow]
+        framedrop=no
+        # you can also include other profiles
+        profile=big-cache
+
+Runtime profiles
+----------------
+
+Profiles can be set at runtime with ``apply-profile`` command. Since this
+operation is "destructive" (every item in a profile is simply set as an
+option, overwriting the previous value), you can't just enable and disable
+profiles again.
+
+As a partial remedy, there is a way to make profiles save old option values
+before overwriting them with the profile values, and then restoring the old
+values at a later point using ``apply-profile <profile-name> restore``.
+
+This can be enabled with the ``profile-restore`` option, which takes one of
+the following options:
+
+    ``default``
+        Does nothing, and nothing can be restored (default).
+
+    ``copy``
+        When applying a profile, copy the old values of all profile options to a
+        backup before setting them from the profile. These options are reset to
+        their old values using the backup when restoring.
+
+        Every profile has its own list of backed up values. If the backup
+        already exists (e.g. if ``apply-profile name`` was called more than
+        once in a row), the existing backup is no changed. The restore operation
+        will remove the backup.
+
+        It's important to know that restoring does not "undo" setting an option,
+        but simply copies the old option value. Consider for example ``vf-add``,
+        appends an entry to ``vf``. This mechanism will simply copy the entire
+        ``vf`` list, and does _not_ execute the inverse of ``vf-add`` (that
+        would be ``vf-remove``) on restoring.
+
+        Note that if a profile contains recursive profiles (via the ``profile``
+        option), the options in these recursive profiles are treated as if they
+        were part of this profile. The referenced profile's backup list is not
+        used when creating or using the backup. Restoring a profile does not
+        restore referenced profiles, only the options of referenced profiles (as
+        if they were part of the main profile).
+
+    ``copy-equal``
+        Similar to ``copy``, but restore an option only if it has the same value
+        as the value effectively set by the profile. This tries to deal with
+        the situation when the user does not want the option to be reset after
+        interactively changing it.
+
+.. admonition:: Example
+
+    ::
+
+        [something]
+        profile-restore=copy-equal
+        vf-add=rotate=PI/2  # rotate by 90 degrees
+
+    Then running these commands will result in behavior as commented:
+
+    ::
+
+        set vf vflip
+        apply-profile something
+        vf add hflip
+        apply-profile something
+        # vf == vflip,rotate=PI/2,hflip,rotate=PI/2
+        apply-profile something restore
+        # vf == vflip
+
+Conditional auto profiles
+-------------------------
+
+Profiles which have the ``profile-cond`` option set are applied automatically
+if the associated condition matches (unless auto profiles are disabled). The
+option takes a string, which is interpreted as Lua expression. If the
+expression evaluates as truthy, the profile is applied. If the expression
+errors or evaluates as falsy, the profile is not applied. This Lua code
+execution is not sandboxed.
+
+Any variables in condition expressions can reference properties. If an
+identifier is not already defined by Lua or mpv, it is interpreted as property.
+For example, ``pause`` would return the current pause status. You cannot
+reference properties with ``-`` this way since that would denote a subtraction,
+but if the variable name contains any ``_`` characters, they are turned into
+``-``. For example, ``playback_time`` would return the property
+``playback-time``.
+
+A more robust way to access properties is using ``p.property_name`` or
+``get("property-name", default_value)``. The automatic variable to property
+magic will break if a new identifier with the same name is introduced (for
+example, if a function named ``pause()`` were added, ``pause`` would return a
+function value instead of the value of the ``pause`` property).
+
+Note that if a property is not available, it will return ``nil``, which can
+cause errors if used in expressions. These are logged in verbose mode, and the
+expression is considered to be false.
+
+Whenever a property referenced by a profile condition changes, the condition
+is re-evaluated. If the return value of the condition changes from falsy or
+error to truthy, the profile is applied.
+
+This mechanism tries to "unapply" profiles once the condition changes from
+truthy to falsy or error. If you want to use this, you need to set
+``profile-restore`` for the profile. Another possibility it to create another
+profile with an inverse condition to undo the other profile.
+
+Recursive profiles can be used. But it is discouraged to reference other
+conditional profiles in a conditional profile, since this can lead to tricky
+and unintuitive behavior.
+
+.. admonition:: Example
+
+    Make only HD video look funny:
+
+    ::
+
+        [something]
+        profile-desc=HD video sucks
+        profile-cond=width >= 1280
+        hue=-50
+
+    Make only videos containing "youtube" or "youtu.be" in their path brighter:
+
+    ::
+
+        [youtube]
+        profile-cond=path:find('youtu%.?be')
+        gamma=20
+
+    If you want the profile to be reverted if the condition goes to false again,
+    you can set ``profile-restore``:
+
+    ::
+
+        [something]
+        profile-desc=Mess up video when entering fullscreen
+        profile-cond=fullscreen
+        profile-restore=copy
+        vf-add=rotate=PI/2  # rotate by 90 degrees
+
+    This appends the ``rotate`` filter to the video filter chain when entering
+    fullscreen. When leaving fullscreen, the ``vf`` option is set to the value
+    it had before entering fullscreen. Note that this would also remove any
+    other filters that were added during fullscreen mode by the user. Avoiding
+    this is trickier, and could for example be solved by adding a second profile
+    with an inverse condition and operation:
+
+    ::
+
+        [something]
+        profile-cond=fullscreen
+        vf-add=@rot:rotate=PI/2
+
+        [something-inv]
+        profile-cond=not fullscreen
+        vf-remove=@rot
+
+.. warning::
+
+    Every time an involved property changes, the condition is evaluated again.
+    If your condition uses ``p.playback_time`` for example, the condition is
+    re-evaluated approximately on every video frame. This is probably slow.
+
+This feature is managed by an internal Lua script. Conditions are executed as
+Lua code within this script. Its environment contains at least the following
+things:
+
+``(function environment table)``
+    Every Lua function has an environment table. This is used for identifier
+    access. There is no named Lua symbol for it; it is implicit.
+
+    The environment does "magic" accesses to mpv properties. If an identifier
+    is not already defined in ``_G``, it retrieves the mpv property of the same
+    name. Any occurrences of ``_`` in the name are replaced with ``-`` before
+    reading the property. The returned value is as retrieved by
+    ``mp.get_property_native(name)``. Internally, a cache of property values,
+    updated by observing the property is used instead, so properties that are
+    not observable will be stuck at the initial value forever.
+
+    If you want to access properties, that actually contain ``_`` in the name,
+    use ``get()`` (which does not perform transliteration).
+
+    Internally, the environment table has a ``__index`` meta method set, which
+    performs the access logic.
+
+``p``
+    A "magic" table similar to the environment table. Unlike the latter, this
+    does not prefer accessing variables defined in ``_G`` - it always accesses
+    properties.
+
+``get(name [, def])``
+    Read a property and return its value. If the property value is ``nil`` (e.g.
+    if the property does not exist), ``def`` is returned.
+
+    This is superficially similar to ``mp.get_property_native(name)``. An
+    important difference is that this accesses the property cache, and enables
+    the change detection logic (which is essential to the dynamic runtime
+    behavior of auto profiles). Also, it does not return an error value as
+    second return value.
+
+    The "magic" tables mentioned above use this function as backend. It does not
+    perform the ``_`` transliteration.
+
+In addition, the same environment as in a blank mpv Lua script is present. For
+example, ``math`` is defined and gives access to the Lua standard math library.
+
+.. warning::
+
+    This feature is subject to change indefinitely. You might be forced to
+    adjust your profiles on mpv updates.
+
+Legacy auto profiles
+--------------------
+
+Some profiles are loaded automatically using a legacy mechanism. The following
+example demonstrates this:
+
+.. admonition:: Auto profile loading
+
+    ::
+
+        [extension.mkv]
+        profile-desc="profile for .mkv files"
+        vf=vflip
+
+The profile name follows the schema ``type.name``, where type can be
+``protocol`` for the input/output protocol in use (see ``--list-protocols``),
+and ``extension`` for the extension of the path of the currently played file
+(*not* the file format).
+
+This feature is very limited, and is considered soft-deprecated. Use conditional
+auto profiles.
+
+Using mpv from other programs or scripts
+========================================
+
+There are three choices for using mpv from other programs or scripts:
+
+    1. Calling it as UNIX process. If you do this, *do not parse terminal output*.
+       The terminal output is intended for humans, and may change any time. In
+       addition, terminal behavior itself may change any time. Compatibility
+       cannot be guaranteed.
+
+       Your code should work even if you pass ``--no-terminal``. Do not attempt
+       to simulate user input by sending terminal control codes to mpv's stdin.
+       If you need interactive control, using ``--input-ipc-server`` is
+       recommended. This gives you access to the `JSON IPC`_  over unix domain
+       sockets (or named pipes on Windows).
+
+       Depending on what you do, passing ``--no-config`` or ``--config-dir`` may
+       be a good idea to avoid conflicts with the normal mpv user configuration
+       intended for CLI playback.
+
+       Using ``--input-ipc-server`` is also suitable for purposes like remote
+       control (however, the IPC protocol itself is not "secure" and not
+       intended to be so).
+
+    2. Using libmpv. This is generally recommended when mpv is used as playback
+       backend for a completely different application. The provided C API is
+       very close to CLI mechanisms and the scripting API.
+
+       Note that even though libmpv has different defaults, it can be configured
+       to work exactly like the CLI player (except command line parsing is
+       unavailable).
+
+       See `EMBEDDING INTO OTHER PROGRAMS (LIBMPV)`_.
+
+    3. As a user script (`LUA SCRIPTING`_, `JAVASCRIPT`_, `C PLUGINS`_). This is
+       recommended when the goal is to "enhance" the CLI player. Scripts get
+       access to the entire client API of mpv.
+
+       This is the standard way to create third-party extensions for the player.
+
+All these access the client API, which is the sum of the various mechanisms
+provided by the player core, as documented here: `OPTIONS`_,
+`List of Input Commands`_, `Properties`_, `List of events`_ (also see C API),
+`Hooks`_.
+
+TAKING SCREENSHOTS
+==================
+
+Screenshots of the currently played file can be taken using the 'screenshot'
+input mode command, which is by default bound to the ``s`` key. Files named
+``mpv-shotNNNN.jpg`` will be saved in the working directory, using the first
+available number - no files will be overwritten. In pseudo-GUI mode, the
+screenshot will be saved somewhere else. See `PSEUDO GUI MODE`_.
+
+A screenshot will usually contain the unscaled video contents at the end of the
+video filter chain and subtitles. By default, ``S`` takes screenshots without
+subtitles, while ``s`` includes subtitles.
+
+Unlike with MPlayer, the ``screenshot`` video filter is not required. This
+filter was never required in mpv, and has been removed.
+
+TERMINAL STATUS LINE
+====================
+
+During playback, mpv shows the playback status on the terminal. It looks like
+something like this:
+
+    ``AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000``
+
+The status line can be overridden with the ``--term-status-msg`` option.
+
+The following is a list of things that can show up in the status line. Input
+properties, that can be used to get the same information manually, are also
+listed.
+
+- ``AV:`` or ``V:`` (video only) or ``A:`` (audio only)
+- The current time position in ``HH:MM:SS`` format (``playback-time`` property)
+- The total file duration (absent if unknown) (``duration`` property)
+- Playback speed, e.g. ``x2.0``. Only visible if the speed is not normal. This
+  is the user-requested speed, and not the actual speed  (usually they should
+  be the same, unless playback is too slow). (``speed`` property.)
+- Playback percentage, e.g. ``(13%)``. How much of the file has been played.
+  Normally calculated out of playback position and duration, but can fallback
+  to other methods (like byte position) if these are not available.
+  (``percent-pos`` property.)
+- The audio/video sync as ``A-V:  0.000``. This is the difference between
+  audio and video time. Normally it should be 0 or close to 0. If it's growing,
+  it might indicate a playback problem. (``avsync`` property.)
+- Total A/V sync change, e.g. ``ct: -0.417``. Normally invisible. Can show up
+  if there is audio "missing", or not enough frames can be dropped. Usually
+  this will indicate a problem. (``total-avsync-change`` property.)
+- Encoding state in ``{...}``, only shown in encoding mode.
+- Display sync state. If display sync is active (``display-sync-active``
+  property), this shows ``DS: 2.500/13``, where the first number is average
+  number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz
+  screens), which might jitter if the ratio doesn't round off, or there are
+  mistimed frames (``vsync-ratio``), and the second number of estimated number
+  of vsyncs which took too long (``vo-delayed-frame-count`` property). The
+  latter is a heuristic, as it's generally not possible to determine this with
+  certainty.
+- Dropped frames, e.g. ``Dropped: 4``. Shows up only if the count is not 0. Can
+  grow if the video framerate is higher than that of the display, or if video
+  rendering is too slow. May also be incremented on "hiccups" and when the video
+  frame couldn't be displayed on time. (``frame-drop-count`` property.)
+  If the decoder drops frames, the number of decoder-dropped frames is appended
+  to the display as well, e.g.: ``Dropped: 4/34``. This happens only if
+  decoder frame dropping is enabled with the ``--framedrop`` options.
+  (``decoder-frame-drop-count`` property.)
+- Cache state, e.g. ``Cache:  2s/134KB``. Visible if the stream cache is enabled.
+  The first value shows the amount of video buffered in the demuxer in seconds,
+  the second value shows the estimated size of the buffered amount in kilobytes.
+  (``demuxer-cache-duration`` and ``demuxer-cache-state`` properties.)
+
+
+LOW LATENCY PLAYBACK
+====================
+
+mpv is optimized for normal video playback, meaning it actually tries to buffer
+as much data as it seems to make sense. This will increase latency. Reducing
+latency is possible only by specifically disabling features which increase
+latency.
+
+The builtin ``low-latency`` profile tries to apply some of the options which can
+reduce latency. You can use  ``--profile=low-latency`` to apply all of them. You
+can list the contents with ``--show-profile=low-latency`` (some of the options
+are quite obscure, and may change every mpv release).
+
+Be aware that some of the options can reduce playback quality.
+
+Most latency is actually caused by inconvenient timing behavior. You can disable
+this with ``--untimed``, but it will likely break, unless the stream has no
+audio, and the input feeds data to the player at a constant rate.
+
+Another common problem is with MJPEG streams. These do not signal the correct
+framerate. Using ``--untimed`` or ``--no-correct-pts --container-fps-override=60``
+might help.
+
+For livestreams, data can build up due to pausing the stream, due to slightly
+lower playback rate, or "buffering" pauses. If the demuxer cache is enabled,
+these can be skipped manually. The experimental ``drop-buffers`` command can
+be used to discard any buffered data, though it's very disruptive.
+
+In some cases, manually tuning TCP buffer sizes and such can help to reduce
+latency.
+
+Additional options that can be tried:
+
+- ``--opengl-glfinish=yes``, can reduce buffering in the graphics driver
+- ``--opengl-swapinterval=0``, same
+- ``--vo=xv``, same
+- without audio ``--framedrop=no --speed=1.01`` may help for live sources
+  (results can be mixed)
+
+RESUMING PLAYBACK
+=================
+
+mpv is capable of storing the playback position of the currently playing file
+and resume from there the next time that file is played. This is done with the
+commands ``quit-watch-later`` (bound to Shift+Q by default) and
+``write-watch-later-config``, and with the ``--save-position-on-quit`` option.
+
+The difference between always quitting with a key bound to ``quit-watch-later``
+and using ``--save-position-on-quit`` is that the latter will save the playback
+position even when mpv is closed with a method other than a keybinding, for
+example if you shutdown your system without closing mpv beforehand, unless of
+course mpv is terminated abruptly and doesn't have the time to save (e.g. with
+the KILL Unix signal).
+
+mpv also stores options other than the playback position when they have been
+modified after playback began, for example the volume and selected audio/subtitles,
+and restores their values the next time the file is played. Which options are
+saved can be configured with the ``--watch-later-options`` option.
+
+When playing multiple playlist entries, mpv checks if one them has a resume
+config file associated, and if it finds one it restarts playback from it. For
+example, if you use ``quit-watch-later`` on the 5th episode of a show, and
+later play all the episodes, mpv will automatically resume playback from
+episode 5.
+
+More options to configure this functionality are listed in `Watch Later`_.
+
+PROTOCOLS
+=========
+
+``http://...``, ``https://``, ...
+
+    Many network protocols are supported, but the protocol prefix must always
+    be specified. mpv will never attempt to guess whether a filename is
+    actually a network address. A protocol prefix is always required.
+
+    Note that not all prefixes are documented here. Undocumented prefixes are
+    either aliases to documented protocols, or are just redirections to
+    protocols implemented and documented in FFmpeg.
+
+    ``data:`` is supported in FFmpeg (not in Libav), but needs to be in the
+    format ``data://``. This is done to avoid ambiguity with filenames. You
+    can also prefix it with ``lavf://`` or ``ffmpeg://``.
+
+``ytdl://...``
+
+    By default, the youtube-dl hook script only looks at http(s) URLs. Prefixing
+    an URL with ``ytdl://`` forces it to be always processed by the script. This
+    can also be used to invoke special youtube-dl functionality like playing a
+    video by ID or invoking search.
+
+    Keep in mind that you can't pass youtube-dl command line options by this,
+    and you have to use ``--ytdl-raw-options`` instead.
+
+``-``
+
+    Play data from stdin.
+
+``smb://PATH``
+
+    Play a path from  Samba share. (Requires FFmpeg support.)
+
+``bd://[title][/device]`` ``--bluray-device=PATH``
+
+    Play a Blu-ray disc. Since libbluray 1.0.1, you can read from ISO files
+    by passing them to ``--bluray-device``.
+
+    ``title`` can be: ``longest`` or ``first`` (selects the default
+    playlist); ``mpls/<number>`` (selects <number>.mpls playlist);
+    ``<number>`` (select playlist with the same index). mpv will list
+    the available playlists on loading.
+
+    ``bluray://`` is an alias.
+
+``dvd://[title][/device]`` ``--dvd-device=PATH``
+
+    Play a DVD. DVD menus are not supported. If no title is given, the longest
+    title is auto-selected. Without ``--dvd-device``, it will probably try
+    to open an actual optical drive, if available and implemented for the OS.
+
+    ``dvdnav://`` is an old alias for ``dvd://`` and does exactly the same
+    thing.
+
+``dvb://[cardnumber@]channel`` ``--dvbin-...``
+
+    Digital TV via DVB. (Linux only.)
+
+``mf://[filemask|@listfile]`` ``--mf-...``
+
+    Play a series of images as video.
+
+``cdda://[device]`` ``--cdrom-device=PATH`` ``--cdda-...``
+
+    Play CD.
+
+``lavf://...``
+
+    Access any FFmpeg/Libav libavformat protocol. Basically, this passed the
+    string after the ``//`` directly to libavformat.
+
+``av://type:options``
+
+    This is intended for using libavdevice inputs. ``type`` is the libavdevice
+    demuxer name, and ``options`` is the (pseudo-)filename passed to the
+    demuxer.
+
+    .. admonition:: Example
+
+        ::
+
+            mpv av://v4l2:/dev/video0 --profile=low-latency --untimed
+
+        This plays video from the first v4l input with nearly the lowest latency
+        possible. It's a good replacement for the removed ``tv://`` input.
+        Using ``--untimed`` is a hack to output a captured frame immediately,
+        instead of respecting the input framerate. (There may be better ways to
+        handle this in the future.)
+
+    ``avdevice://`` is an alias.
+
+``file://PATH``
+
+    A local path as URL. Might be useful in some special use-cases. Note that
+    ``PATH`` itself should start with a third ``/`` to make the path an
+    absolute path.
+
+``appending://PATH``
+
+    Play a local file, but assume it's being appended to. This is useful for
+    example for files that are currently being downloaded to disk. This will
+    block playback, and stop playback only if no new data was appended after
+    a timeout of about 2 seconds.
+
+    Using this is still a bit of a bad idea, because there is no way to detect
+    if a file is actually being appended, or if it's still written. If you're
+    trying to play the  output of some program, consider using a pipe
+    (``something | mpv -``). If it really has to be a file on disk, use tail to
+    make it wait forever, e.g. ``tail -f -c +0 file.mkv | mpv -``.
+
+``fd://123``
+
+    Read data from the given file descriptor (for example 123). This is similar
+    to piping data to stdin via ``-``, but can use an arbitrary file descriptor.
+    mpv may modify some file descriptor properties when the stream layer "opens"
+    it.
+
+``fdclose://123``
+
+    Like ``fd://``, but the file descriptor is closed after use. When using this
+    you need to ensure that the same fd URL will only be used once.
+
+``edl://[edl specification as in edl-mpv.rst]``
+
+    Stitch together parts of multiple files and play them.
+
+``slice://start[-end]@URL``
+
+    Read a slice of a stream.
+
+    ``start`` and ``end`` represent a byte range and accept
+    suffixes such as ``KiB`` and ``MiB``. ``end`` is optional.
+
+    if ``end`` starts with ``+``, it is considered as offset from ``start``.
+
+    Only works with seekable streams.
+
+    Examples::
+
+      mpv slice://1g-2g@cap.ts
+
+      This starts reading from cap.ts after seeking 1 GiB, then
+      reads until reaching 2 GiB or end of file.
+
+      mpv slice://1g-+2g@cap.ts
+
+      This starts reading from cap.ts after seeking 1 GiB, then
+      reads until reaching 3 GiB or end of file.
+
+      mpv slice://100m@appending://cap.ts
+
+      This starts reading from cap.ts after seeking 100MiB, then
+      reads until end of file.
+
+``null://``
+
+    Simulate an empty file. If opened for writing, it will discard all data.
+    The ``null`` demuxer will specifically pass autoprobing if this protocol
+    is used (while it's not automatically invoked for empty files).
+
+``memory://data``
+
+    Use the ``data`` part as source data.
+
+``hex://data``
+
+    Like ``memory://``, but the string is interpreted as hexdump.
+
+PSEUDO GUI MODE
+===============
+
+mpv has no official GUI, other than the OSC (`ON SCREEN CONTROLLER`_), which
+is not a full GUI and is not meant to be. However, to compensate for the lack
+of expected GUI behavior, mpv will in some cases start with some settings
+changed to behave slightly more like a GUI mode.
+
+Currently this happens only in the following cases:
+
+- if started using the ``mpv.desktop`` file on Linux (e.g. started from menus
+  or file associations provided by desktop environments)
+- if started from explorer.exe on Windows (technically, if it was started on
+  Windows, and all of the stdout/stderr/stdin handles are unset)
+- started out of the bundle on macOS
+- if you manually use ``--player-operation-mode=pseudo-gui`` on the command line
+
+This mode applies options from the builtin profile ``builtin-pseudo-gui``, but
+only if these haven't been set in the user's config file or on the command line,
+which is the main difference to using ``--profile=builtin-pseudo-gui``.
+
+The profile is currently defined as follows:
+
+::
+
+    [builtin-pseudo-gui]
+    terminal=no
+    force-window=yes
+    idle=once
+    screenshot-directory=~~desktop/
+
+The ``pseudo-gui`` profile exists for compatibility. The options in the
+``pseudo-gui`` profile are applied unconditionally. In addition, the profile
+makes sure to enable the pseudo-GUI mode, so that ``--profile=pseudo-gui``
+works like in older mpv releases:
+
+::
+
+    [pseudo-gui]
+    player-operation-mode=pseudo-gui
+
+.. warning::
+
+    Currently, you can extend the ``pseudo-gui`` profile in the config file the
+    normal way. This is deprecated. In future mpv releases, the behavior might
+    change, and not apply your additional settings, and/or use a different
+    profile name.
+
+Linux desktop issues
+====================
+
+This subsection describes common problems on the Linux desktop. None of these
+problems exist on systems like Windows or macOS.
+
+Disabling Screensaver
+---------------------
+
+By default, mpv tries to disable the OS screensaver during playback (only if
+a VO using the OS GUI API is active). ``--stop-screensaver=no`` disables this.
+
+A common problem is that Linux desktop environments ignore the standard
+screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver
+extension (XSS) on X11, and the idle-inhibit protocol on Wayland.
+
+Before mpv 0.33.0, the X11 backend ran ``xdg-screensaver reset`` in 10 second
+intervals when not paused in order to support screensaver inhibition in these
+environments. This functionality was removed in 0.33.0, but it is possible to
+call the ``xdg-screensaver`` command line program from a user script instead.
+
+
+.. include:: options.rst
+
+.. include:: ao.rst
+
+.. include:: vo.rst
+
+.. include:: af.rst
+
+.. include:: vf.rst
+
+.. include:: encode.rst
+
+.. include:: input.rst
+
+.. include:: osc.rst
+
+.. include:: stats.rst
+
+.. include:: console.rst
+
+.. include:: lua.rst
+
+.. include:: javascript.rst
+
+.. include:: ipc.rst
+
+.. include:: changes.rst
+
+.. include:: libmpv.rst
+
+ENVIRONMENT VARIABLES
+=====================
+
+There are a number of environment variables that can be used to control the
+behavior of mpv.
+
+``HOME``, ``XDG_CONFIG_HOME``
+    Used to determine mpv config directory. If ``XDG_CONFIG_HOME`` is not set,
+    ``$HOME/.config/mpv`` is used.
+
+    ``$HOME/.mpv`` is always added to the list of config search paths with a
+    lower priority.
+
+``MPV_HOME``
+    Directory where mpv looks for user settings. Overrides ``HOME``, and mpv
+    will try to load the config file as ``$MPV_HOME/mpv.conf``.
+
+``MPV_VERBOSE`` (see also ``-v`` and ``--msg-level``)
+    Set the initial verbosity level across all message modules (default: 0).
+    This is an integer, and the resulting verbosity corresponds to the number
+    of ``--v`` options passed to the command line.
+
+``MPV_LEAK_REPORT``
+    If set to ``1``, enable internal talloc leak reporting. If set to another
+    value, disable leak reporting. If unset, use the default, which normally is
+    ``0``. If mpv was built with ``--enable-ta-leak-report``, the default is
+    ``1``. If leak reporting was disabled at compile time (``NDEBUG`` in
+    custom ``CFLAGS``), this environment variable is ignored.
+
+``LADSPA_PATH``
+    Specifies the search path for LADSPA plugins. If it is unset, fully
+    qualified path names must be used.
+
+``DISPLAY``
+    Standard X11 display name to use.
+
+FFmpeg/Libav:
+    This library accesses various environment variables. However, they are not
+    centrally documented, and documenting them is not our job. Therefore, this
+    list is incomplete.
+
+    Notable environment variables:
+
+    ``http_proxy``
+        URL to proxy for ``http://`` and ``https://`` URLs.
+
+    ``no_proxy``
+        List of domain patterns for which no proxy should be used.
+        List entries are separated by ``,``. Patterns can include ``*``.
+
+libdvdcss:
+    ``DVDCSS_CACHE``
+        Specify a directory in which to store title key values. This will
+        speed up descrambling of DVDs which are in the cache. The
+        ``DVDCSS_CACHE`` directory is created if it does not exist, and a
+        subdirectory is created named after the DVD's title or manufacturing
+        date. If ``DVDCSS_CACHE`` is not set or is empty, libdvdcss will use
+        the default value which is ``${HOME}/.dvdcss/`` under Unix and
+        the roaming application data directory (``%APPDATA%``) under
+        Windows. The special value "off" disables caching.
+
+    ``DVDCSS_METHOD``
+        Sets the authentication and decryption method that libdvdcss will use
+        to read scrambled discs. Can be one of ``title``, ``key`` or ``disc``.
+
+        key
+           is the default method. libdvdcss will use a set of calculated
+           player keys to try to get the disc key. This can fail if the drive
+           does not recognize any of the player keys.
+
+        disc
+           is a fallback method when key has failed. Instead of using player
+           keys, libdvdcss will crack the disc key using a brute force
+           algorithm. This process is CPU intensive and requires 64 MB of
+           memory to store temporary data.
+
+        title
+           is the fallback when all other methods have failed. It does not
+           rely on a key exchange with the DVD drive, but rather uses a crypto
+           attack to guess the title key. On rare cases this may fail because
+           there is not enough encrypted data on the disc to perform a
+           statistical attack, but on the other hand it is the only way to
+           decrypt a DVD stored on a hard disc, or a DVD with the wrong region
+           on an RPC2 drive.
+
+    ``DVDCSS_RAW_DEVICE``
+        Specify the raw device to use. Exact usage will depend on your
+        operating system, the Linux utility to set up raw devices is raw(8)
+        for instance. Please note that on most operating systems, using a raw
+        device requires highly aligned buffers: Linux requires a 2048 bytes
+        alignment (which is the size of a DVD sector).
+
+    ``DVDCSS_VERBOSE``
+        Sets the libdvdcss verbosity level.
+
+        :0: Outputs no messages at all.
+        :1: Outputs error messages to stderr.
+        :2: Outputs error messages and debug messages to stderr.
+
+    ``DVDREAD_NOKEYS``
+        Skip retrieving all keys on startup. Currently disabled.
+
+    ``HOME``
+        FIXME: Document this.
+
+
+EXIT CODES
+==========
+
+Normally **mpv** returns 0 as exit code after finishing playback successfully.
+If errors happen, the following exit codes can be returned:
+
+    :1: Error initializing mpv. This is also returned if unknown options are
+        passed to mpv.
+    :2: The file passed to mpv couldn't be played. This is somewhat fuzzy:
+        currently, playback of a file is considered to be successful if
+        initialization was mostly successful, even if playback fails
+        immediately after initialization.
+    :3: There were some files that could be played, and some files which
+        couldn't (using the definition of success from above).
+    :4: Quit due to a signal, Ctrl+c in a VO window (by default), or from the
+        default quit key bindings in encoding mode.
+
+Note that quitting the player manually will always lead to exit code 0,
+overriding the exit code that would be returned normally. Also, the ``quit``
+input command can take an exit code: in this case, that exit code is returned.
+
+FILES
+=====
+
+Note that this section assumes Linux/BSD. On other platforms the paths may be different.
+For Windows-specifics, see `FILES ON WINDOWS`_ section.
+
+``/usr/local/etc/mpv/mpv.conf``
+    mpv system-wide settings (depends on ``--prefix`` passed to configure - mpv
+    in default configuration will use ``/usr/local/etc/mpv/`` as config
+    directory, while most Linux distributions will set it to ``/etc/mpv/``).
+
+``~/.cache/mpv``
+    The standard cache directory. Certain options within mpv may cause it to write
+    cache files to disk. This can be overridden by environment variables, in
+    ascending order:
+
+    :1: If ``$XDG_CACHE_HOME`` is set, then the derived cache directory
+        will be ``$XDG_CACHE_HOME/mpv``.
+    :2: If ``$MPV_HOME`` is set, then the derived cache directory will be
+       ``$MPV_HOME``.
+
+    If the directory does not exist, mpv will try to create it automatically.
+
+``~/.config/mpv``
+    The standard configuration directory. This can be overridden by environment
+    variables, in ascending order:
+
+    :1: If ``$XDG_CONFIG_HOME`` is set, then the derived configuration directory
+        will be ``$XDG_CONFIG_HOME/mpv``.
+    :2: If ``$MPV_HOME`` is set, then the derived configuration directory will be
+       ``$MPV_HOME``.
+
+    If this directory, nor the original configuration directory (see below) do
+    not exist, mpv tries to create this directory automatically.
+
+``~/.mpv/``
+    The original (pre 0.5.0) configuration directory. It will continue to be
+    read if present. If this directory is present and the standard configuration
+    directory is not present, then cache files and watch later config files will
+    also be written to this directory.
+
+    If both this directory and the standard configuration directory are
+    present, configuration will be read from both with the standard
+    configuration directory content taking precedence. However, you should
+    fully migrate to the standard directory and a warning will be shown in
+    this situation.
+
+``~/.config/mpv/mpv.conf``
+    mpv user settings (see `CONFIGURATION FILES`_ section)
+
+``~/.config/mpv/input.conf``
+    key bindings (see `INPUT.CONF`_ section)
+
+``~/.config/mpv/fonts.conf``
+    Fontconfig fonts.conf that is customized for mpv. You should include system
+    fonts.conf in this file or mpv would not know about fonts that you already
+    have in the system.
+
+    Only available when libass is built with fontconfig.
+
+``~/.config/mpv/subfont.ttf``
+    fallback subtitle font
+
+``~/.config/mpv/fonts/``
+    Default location for ``--sub-fonts-dir`` (see `Subtitles`_) and
+    ``--osd-fonts-dir`` (see `OSD`_).
+
+``~/.config/mpv/scripts/``
+    All files in this directory are loaded as if they were passed to the
+    ``--script`` option. They are loaded in alphabetical order.
+
+    The ``--load-scripts=no`` option disables loading these files.
+
+    See `Script location`_ for details.
+
+``~/.local/state/mpv/watch_later/``
+    Contains temporary config files needed for resuming playback of files with
+    the watch later feature. See for example the ``Q`` key binding, or the
+    ``quit-watch-later`` input command.
+
+    This can be overridden by environment variables, in ascending order:
+
+    :1: If ``$XDG_STATE_HOME`` is set, then the derived watch later directory
+        will be ``$XDG_STATE_HOME/mpv/watch_later``.
+    :2: If ``$MPV_HOME`` is set, then the derived watch later directory will be
+       ``$MPV_HOME/watch_later``.
+
+    Each file is a small config file which is loaded if the corresponding media
+    file is loaded. It contains the playback position and some (not necessarily
+    all) settings that were changed during playback. The filenames are hashed
+    from the full paths of the media files. It's in general not possible to
+    extract the media filename from this hash. However, you can set the
+    ``--write-filename-in-watch-later-config`` option, and the player will
+    add the media filename to the contents of the resume config file.
+
+``~/.config/mpv/script-opts/osc.conf``
+    This is loaded by the OSC script. See the `ON SCREEN CONTROLLER`_ docs
+    for details.
+
+    Other files in this directory are specific to the corresponding scripts
+    as well, and the mpv core doesn't touch them.
+
+FILES ON WINDOWS
+================
+
+On win32 (if compiled with MinGW, but not Cygwin), the default config file
+locations are different. They are generally located under ``%APPDATA%/mpv/``.
+For example, the path to mpv.conf is ``%APPDATA%/mpv/mpv.conf``, which maps to
+a system and user-specific path, for example
+
+    ``C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf``
+
+You can find the exact path by running ``echo %APPDATA%\mpv\mpv.conf`` in cmd.exe.
+
+Other config files (such as ``input.conf``) are in the same directory. See the
+`FILES`_ section above.
+
+The cache directory is located at ``%LOCALAPPDATA%/mpv/cache``.
+
+The watch_later directory is located at ``%LOCALAPPDATA%/mpv/watch_later``.
+
+The environment variable ``$MPV_HOME`` completely overrides these, like on
+UNIX.
+
+If a directory named ``portable_config`` next to the mpv.exe exists, all
+config will be loaded from this directory only. Watch later config files and
+cache files are written to this directory as well. (This exists on Windows
+only and is redundant with ``$MPV_HOME``. However, since Windows is very
+scripting unfriendly, a wrapper script just setting ``$MPV_HOME``, like you
+could do it on other systems, won't work. ``portable_config`` is provided for
+convenience to get around this restriction.)
+
+Config files located in the same directory as ``mpv.exe`` are loaded with
+lower priority. Some config files are loaded only once, which means that
+e.g. of 2 ``input.conf`` files located in two config directories, only the
+one from the directory with higher priority will be loaded.
+
+A third config directory with the lowest priority is the directory named ``mpv``
+in the same directory as ``mpv.exe``. This used to be the directory with the
+highest priority, but is now discouraged to use and might be removed in the
+future.
+
+Note that mpv likes to mix ``/`` and ``\`` path separators for simplicity.
+kernel32.dll accepts this, but cmd.exe does not.
+
+FILES ON MACOS
+==============
+
+On macOS the watch later directory is located at ``~/.config/mpv/watch_later/``
+and the cache directory is set to ``~/Library/Caches/io.mpv/``. These directories
+can't be overwritten by enviroment variables.
+Everything else is the same as `FILES`_.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
new file mode 100644
index 0000000..e0445d4
--- /dev/null
+++ b/DOCS/man/options.rst
@@ -0,0 +1,7377 @@
+OPTIONS
+=======
+
+Track Selection
+---------------
+
+``--alang=<languagecode[,languagecode,...]>``
+    Specify a priority list of audio languages to use, as IETF language tags.
+    Equivalent ISO 639-1 two-letter and ISO 639-2 three-letter codes are treated the same.
+    The first tag in the list whose language matches a track in the file will be used.
+    A track that matches more subtags will be preferred over one that matches fewer,
+    with preference given to earlier subtags over later ones. See also ``--aid``.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``mpv dvd://1 --alang=hu,en`` chooses the Hungarian language track
+          on a DVD and falls back on English if Hungarian is not available.
+        - ``mpv --alang=jpn example.mkv`` plays a Matroska file with Japanese
+          audio.
+
+``--slang=<languagecode[,languagecode,...]>``
+    Equivalent to ``--alang``, for subtitle tracks.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``mpv dvd://1 --slang=hu,en`` chooses the Hungarian subtitle track on
+          a DVD and falls back on English if Hungarian is not available.
+        - ``mpv --slang=jpn example.mkv`` plays a Matroska file with Japanese
+          subtitles.
+        - ``mpv --slang=pt-BR example.mkv`` plays a Matroska file with Brazilian
+          Portuguese subtitles if available, and otherwise any Portuguese subtitles.
+
+``--vlang=<...>``
+    Equivalent to ``--alang`` and ``--slang``, for video tracks.
+
+    This is a string list option. See `List Options`_ for details.
+
+``--aid=<ID|auto|no>``
+    Select audio track. ``auto`` selects the default, ``no`` disables audio.
+    See also ``--alang``. mpv normally prints available audio tracks on the
+    terminal when starting playback of a file.
+
+    ``--audio`` is an alias for ``--aid``.
+
+    ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback.
+    (The latter variant does not work with the client API.)
+
+    .. note::
+
+        The track selection options (``--aid`` but also ``--sid`` and the
+        others) sometimes expose behavior that may appear strange. Also, the
+        behavior tends to change around with each mpv release.
+
+        The track selection properties will return the option value outside of
+        playback (as expected), but during playback, the affective track
+        selection is returned. For example, with ``--aid=auto``, the ``aid``
+        property will suddenly return ``2`` after playback initialization
+        (assuming the file has at least 2 audio tracks, and the second is the
+        default).
+
+        At mpv 0.32.0 (and some releases before), if you passed a track value
+        for which a corresponding track didn't exist (e.g. ``--aid=2`` and there
+        was only 1 audio track), the ``aid`` property returned ``no``. However if
+        another audio track was added during playback, and you tried to set the
+        ``aid`` property to ``2``, nothing happened, because the ``aid`` option
+        still had the value ``2``, and writing the same value has no effect.
+
+        With mpv 0.33.0, the behavior was changed. Now track selection options
+        are reset to ``auto`` at playback initialization, if the option had
+        tries to select a track that does not exist. The same is done if the
+        track exists, but fails to initialize. The consequence is that unlike
+        before mpv 0.33.0, the user's track selection parameters are clobbered
+        in certain situations.
+
+        Also since mpv 0.33.0, trying to select a track by number will strictly
+        select this track. Before this change, trying to select a track which
+        did not exist would fall back to track default selection at playback
+        initialization. The new behavior is more consistent.
+
+        Setting a track selection property at runtime, and then playing a new
+        file might reset the track selection to defaults, if the fingerprint
+        of the track list of the new file is different.
+
+        Be aware of tricky combinations of all of all of the above: for example,
+        ``mpv --aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv``
+        would first play the correct track, and the second file without audio.
+        If you then go back the first file, its first audio track will be played,
+        and the second file is played with audio. If you do the same thing again
+        but instead of using ``--aid=2`` you run ``set aid 2`` while the file is
+        playing, then changing to the second file will play its audio track.
+        This is because runtime selection enables the fingerprint heuristic.
+
+        Most likely this is not the end.
+
+``--sid=<ID|auto|no>``
+    Display the subtitle stream specified by ``<ID>``. ``auto`` selects
+    the default, ``no`` disables subtitles.
+
+    ``--sub`` is an alias for ``--sid``.
+
+    ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding.
+    (The latter variant does not work with the client API.)
+
+``--vid=<ID|auto|no>``
+    Select video channel. ``auto`` selects the default, ``no`` disables video.
+
+    ``--video`` is an alias for ``--vid``.
+
+    ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback.
+    (The latter variant does not work with the client API.)
+
+    If video is disabled, mpv will try to download the audio only if media is
+    streamed with youtube-dl, because it saves bandwidth. This is done by
+    setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script.
+
+``--edition=<ID|auto>``
+    (Matroska files only)
+    Specify the edition (set of chapters) to use, where 0 is the first. If set
+    to ``auto`` (the default), mpv will choose the first edition declared as a
+    default, or if there is no default, the first edition defined.
+
+``--track-auto-selection=<yes|no>``
+    Enable the default track auto-selection (default: yes). Enabling this will
+    make the player select streams according to ``--aid``, ``--alang``, and
+    others. If it is disabled, no tracks are selected. In addition, the player
+    will not exit if no tracks are selected, and wait instead (this wait mode
+    is similar to pausing, but the pause option is not set).
+
+    This is useful with ``--lavfi-complex``: you can start playback in this
+    mode, and then set select tracks at runtime by setting the filter graph.
+    Note that if ``--lavfi-complex`` is set before playback is started, the
+    referenced tracks are always selected.
+
+``--subs-with-matching-audio=<yes|no>``
+    When autoselecting a subtitle track, select a full/non-forced one even if the selected
+    audio stream matches your preferred subtitle language (default: yes). If this option is
+    set to ``no``, a non-forced subtitle track that matches the audio language will never be
+    autoselected by mpv regardless of the value of ``--slang`` or ``--subs-fallback``.
+
+``--subs-match-os-language=<yes|no>``
+    When autoselecting a subtitle track, select the track that matches the language of your OS
+    if the audio stream is in a different language if suitable (default track or a forced track
+    under the right conditions). Note that if ``-slang`` is set, this will be completely ignored
+    (default: yes).
+
+``--subs-fallback=<yes|default|no>``
+    When autoselecting a subtitle track, if no tracks match your preferred languages,
+    select a full track even if it doesn't match your preferred subtitle language (default: default).
+    Setting this to `default` means that only streams flagged as `default` will be selected.
+
+``--subs-fallback-forced=<yes|no|always>``
+    When autoselecting a subtitle track, the default value of `yes` will prefer using a forced
+    subtitle track if the subtitle language matches the audio language and matches your list of
+    preferred languages. The special value `always` will only select forced subtitle tracks and
+    never fallback on a non-forced track. Conversely, `no` will never select a forced subtitle
+    track.
+
+
+Playback Control
+----------------
+
+``--start=<relative time>``
+    Seek to given time position.
+
+    The general format for times is ``[+|-][[hh:]mm:]ss[.ms]``. If the time is
+    prefixed with ``-``, the time is considered relative from the end of the
+    file (as signaled by the demuxer/the file). A ``+`` is usually ignored (but
+    see below).
+
+    The following alternative time specifications are recognized:
+
+    ``pp%`` seeks to percent position pp (0-100).
+
+    ``#c`` seeks to chapter number c. (Chapters start from 1.)
+
+    ``none`` resets any previously set option (useful for libmpv).
+
+    If ``--rebase-start-time=no`` is given, then prefixing times with ``+``
+    makes the time relative to the start of the file. A timestamp without
+    prefix is considered an absolute time, i.e. should seek to a frame with a
+    timestamp as the file contains it. As a bug, but also a hidden feature,
+    putting 1 or more spaces before the ``+`` or ``-`` always interprets the
+    time as absolute, which can be used to seek to negative timestamps (useful
+    for debugging at most).
+
+    .. admonition:: Examples
+
+        ``--start=+56``, ``--start=00:56``
+            Seeks to the start time + 56 seconds.
+        ``--start=-56``, ``--start=-00:56``
+            Seeks to the end time - 56 seconds.
+        ``--start=01:10:00``
+            Seeks to 1 hour 10 min.
+        ``--start=50%``
+            Seeks to the middle of the file.
+        ``--start=30 --end=40``
+            Seeks to 30 seconds, plays 10 seconds, and exits.
+        ``--start=-3:20 --length=10``
+            Seeks to 3 minutes and 20 seconds before the end of the file, plays
+            10 seconds, and exits.
+        ``--start='#2' --end='#4'``
+            Plays chapters 2 and 3, and exits.
+
+``--end=<relative time>``
+    Stop at given time. Use ``--length`` if the time should be relative
+    to ``--start``. See ``--start`` for valid option values and examples.
+
+``--length=<relative time>``
+    Stop after a given time relative to the start time.
+    See ``--start`` for valid option values and examples.
+
+    If both ``--end`` and ``--length`` are provided, playback will stop when it
+    reaches either of the two endpoints.
+
+    Obscurity note: this does not work correctly if ``--rebase-start-time=no``,
+    and the specified time is not an "absolute" time, as defined in the
+    ``--start`` option description.
+
+``--rebase-start-time=<yes|no>``
+    Whether to move the file start time to ``00:00:00`` (default: yes). This
+    is less awkward for files which start at a random timestamp, such as
+    transport streams. On the other hand, if there are timestamp resets, the
+    resulting behavior can be rather weird. For this reason, and in case you
+    are actually interested in the real timestamps, this behavior can be
+    disabled with ``no``.
+
+``--speed=<0.01-100>``
+    Slow down or speed up playback by the factor given as parameter.
+
+    If ``--audio-pitch-correction`` (on by default) is used, playing with a
+    speed higher than normal automatically inserts the ``scaletempo2`` audio
+    filter.
+
+``--pause``
+    Start the player in paused state.
+
+``--shuffle``
+    Play files in random order.
+
+``--playlist-start=<auto|index>``
+    Set which file on the internal playlist to start playback with. The index
+    is an integer, with 0 meaning the first file. The value ``auto`` means that
+    the selection of the entry to play is left to the playback resume mechanism
+    (default). If an entry with the given index doesn't exist, the behavior is
+    unspecified and might change in future mpv versions. The same applies if
+    the playlist contains further playlists (don't expect any reasonable
+    behavior). Passing a playlist file to mpv should work with this option,
+    though. E.g. ``mpv playlist.m3u --playlist-start=123`` will work as expected,
+    as long as ``playlist.m3u`` does not link to further playlists.
+
+    The value ``no`` is a deprecated alias for ``auto``.
+
+``--playlist=<filename>``
+    Play files according to a playlist file. Supports some common formats. If
+    no format is detected, it will be treated as list of files, separated by
+    newline characters. You may need this option to load plaintext files as
+    a playlist. Note that XML playlist formats are not supported.
+
+    This option forces ``--demuxer=playlist`` to interpret the playlist file.
+    Some playlist formats, notably CUE and optical disc formats, need to use
+    different demuxers and will not work with this option. They still can be
+    played directly, without using this option.
+
+    You can play playlists directly, without this option. Before mpv version
+    0.31.0, this option disabled any security mechanisms that might be in
+    place, but since 0.31.0 it uses the same security mechanisms as playing a
+    playlist file directly. If you trust the playlist file, you can disable
+    any security checks with ``--load-unsafe-playlists``. Because playlists
+    can load other playlist entries, consider applying this option only to the
+    playlist itself and not its entries, using something along these lines:
+
+        ``mpv --{ --playlist=filename --load-unsafe-playlists --}``
+
+    .. warning::
+
+        The way older versions of mpv played playlist files via ``--playlist``
+        was not safe against maliciously constructed files. Such files may
+        trigger harmful actions. This has been the case for all versions of
+        mpv prior to 0.31.0, and all MPlayer versions, but unfortunately this
+        fact was not well documented earlier, and some people have even
+        misguidedly recommended the use of ``--playlist`` with untrusted
+        sources. Do NOT use ``--playlist`` with random internet sources or
+        files you do not trust if you are not sure your mpv is at least 0.31.0.
+
+        In particular, playlists can contain entries using protocols other than
+        local files, such as special protocols like ``avdevice://`` (which are
+        inherently unsafe).
+
+``--chapter-merge-threshold=<number>``
+    Threshold for merging almost consecutive ordered chapter parts in
+    milliseconds (default: 100). Some Matroska files with ordered chapters
+    have inaccurate chapter end timestamps, causing a small gap between the
+    end of one chapter and the start of the next one when they should match.
+    If the end of one playback part is less than the given threshold away from
+    the start of the next one then keep playing video normally over the
+    chapter change instead of doing a seek.
+
+``--chapter-seek-threshold=<seconds>``
+    Distance in seconds from the beginning of a chapter within which a backward
+    chapter seek will go to the previous chapter (default: 5.0). Past this
+    threshold, a backward chapter seek will go to the beginning of the current
+    chapter instead. A negative value means always go back to the previous
+    chapter.
+
+``--hr-seek=<no|absolute|yes|default>``
+    Select when to use precise seeks that are not limited to keyframes. Such
+    seeks require decoding video from the previous keyframe up to the target
+    position and so can take some time depending on decoding performance. For
+    some video formats, precise seeks are disabled. This option selects the
+    default choice to use for seeks; it is possible to explicitly override that
+    default in the definition of key bindings and in input commands.
+
+    :no:       Never use precise seeks.
+    :absolute: Use precise seeks if the seek is to an absolute position in the
+               file, such as a chapter seek, but not for relative seeks like
+               the default behavior of arrow keys.
+    :default:  Like ``absolute``, but enable hr-seeks in audio-only cases. The
+               exact behavior is implementation specific and may change with
+               new releases (default).
+    :yes:      Use precise seeks whenever possible.
+    :always:   Same as ``yes`` (for compatibility).
+
+``--hr-seek-demuxer-offset=<seconds>``
+    This option exists to work around failures to do precise seeks (as in
+    ``--hr-seek``) caused by bugs or limitations in the demuxers for some file
+    formats. Some demuxers fail to seek to a keyframe before the given target
+    position, going to a later position instead. The value of this option is
+    subtracted from the time stamp given to the demuxer. Thus, if you set this
+    option to 1.5 and try to do a precise seek to 60 seconds, the demuxer is
+    told to seek to time 58.5, which hopefully reduces the chance that it
+    erroneously goes to some time later than 60 seconds. The downside of
+    setting this option is that precise seeks become slower, as video between
+    the earlier demuxer position and the real target may be unnecessarily
+    decoded.
+
+``--hr-seek-framedrop=<yes|no>``
+    Allow the video decoder to drop frames during seek, if these frames are
+    before the seek target. If this is enabled, precise seeking can be faster,
+    but if you're using video filters which modify timestamps or add new
+    frames, it can lead to precise seeking skipping the target frame. This
+    e.g. can break frame backstepping when deinterlacing is enabled.
+
+    Default: ``yes``
+
+``--index=<mode>``
+    Controls how to seek in files. Note that if the index is missing from a
+    file, it will be built on the fly by default, so you don't need to change
+    this. But it might help with some broken files.
+
+    :default:   use an index if the file has one, or build it if missing
+    :recreate:  don't read or use the file's index
+
+    .. note::
+
+        This option only works if the underlying media supports seeking
+        (i.e. not with stdin, pipe, etc).
+
+``--load-unsafe-playlists``
+    Load URLs from playlists which are considered unsafe (default: no). This
+    includes special protocols and anything that doesn't refer to normal files.
+    Local files and HTTP links on the other hand are always considered safe.
+
+    In addition, if a playlist is loaded while this is set, the added playlist
+    entries are not marked as originating from network or potentially unsafe
+    location. (Instead, the behavior is as if the playlist entries were provided
+    directly to mpv command line or ``loadfile`` command.)
+
+``--access-references=<yes|no>``
+    Follow any references in the file being opened (default: yes). Disabling
+    this is helpful if the file is automatically scanned (e.g. thumbnail
+    generation). If the thumbnail scanner for example encounters a playlist
+    file, which contains network URLs, and the scanner should not open these,
+    enabling this option will prevent it. This option also disables ordered
+    chapters, mov reference files, opening of archives, and a number of other
+    features.
+
+    On older FFmpeg versions, this will not work in some cases. Some FFmpeg
+    demuxers might not respect this option.
+
+    This option does not prevent opening of paired subtitle files and such. Use
+    ``--autoload-files=no`` to prevent this.
+
+    This option does not always work if you open non-files (for example using
+    ``dvd://directory`` would open a whole bunch of files in the given
+    directory). Prefixing the filename with ``./`` if it doesn't start with
+    a ``/`` will avoid this.
+
+``--loop-playlist=<N|inf|force|no>``, ``--loop-playlist``
+    Loops playback ``N`` times. A value of ``1`` plays it one time (default),
+    ``2`` two times, etc. ``inf`` means forever. ``no`` is the same as ``1`` and
+    disables looping. If several files are specified on command line, the
+    entire playlist is looped. ``--loop-playlist`` is the same as
+    ``--loop-playlist=inf``.
+
+    The ``force`` mode is like ``inf``, but does not skip playlist entries
+    which have been marked as failing. This means the player might waste CPU
+    time trying to loop a file that doesn't exist. But it might be useful for
+    playing webradios under very bad network conditions.
+
+``--loop-file=<N|inf|no>``, ``--loop=<N|inf|no>``
+    Loop a single file N times. ``inf`` means forever, ``no`` means normal
+    playback. For compatibility, ``--loop-file`` and ``--loop-file=yes`` are
+    also accepted, and are the same as ``--loop-file=inf``.
+
+    The difference to ``--loop-playlist`` is that this doesn't loop the playlist,
+    just the file itself. If the playlist contains only a single file, the
+    difference between the two option is that this option performs a seek on
+    loop, instead of reloading the file.
+
+    .. note::
+
+        ``--loop-file`` counts the number of times it causes the player to
+        seek to the beginning of the file, not the number of full playthroughs. This
+        means ``--loop-file=1`` will end up playing the file twice. Contrast with
+        ``--loop-playlist``, which counts the number of full playthroughs.
+
+    ``--loop`` is an alias for this option.
+
+``--ab-loop-a=<time>``, ``--ab-loop-b=<time>``
+    Set loop points. If playback passes the ``b`` timestamp, it will seek to
+    the ``a`` timestamp. Seeking past the ``b`` point doesn't loop (this is
+    intentional).
+
+    If ``a`` is after ``b``, the behavior is as if the points were given in
+    the right order, and the player will seek to ``b`` after crossing through
+    ``a``. This is different from old behavior, where looping was disabled (and
+    as a bug, looped back to ``a`` on the end of the file).
+
+    If either options are set to ``no`` (or unset), looping is disabled. This
+    is different from old behavior, where an unset ``a`` implied the start of
+    the file, and an unset ``b`` the end of the file.
+
+    The loop-points can be adjusted at runtime with the corresponding
+    properties. See also ``ab-loop`` command.
+
+``--ab-loop-count=<N|inf>``
+    Run A-B loops only N times, then ignore the A-B loop points (default: inf).
+    Every finished loop iteration will decrement this option by 1 (unless it is
+    set to ``inf`` or 0). ``inf`` means that looping goes on forever. If this
+    option is set to 0, A-B looping is ignored, and even the ``ab-loop`` command
+    will not enable looping again (the command will show ``(disabled)`` on the
+    OSD message if both loop points are set, but ``ab-loop-count`` is 0).
+
+``--ordered-chapters``, ``--no-ordered-chapters``
+    Enabled by default.
+    Disable support for Matroska ordered chapters. mpv will not load or
+    search for video segments from other files, and will also ignore any
+    chapter order specified for the main file.
+
+``--ordered-chapters-files=<playlist-file>``
+    Loads the given file as playlist, and tries to use the files contained in
+    it as reference files when opening a Matroska file that uses ordered
+    chapters. This overrides the normal mechanism for loading referenced
+    files by scanning the same directory the main file is located in.
+
+    Useful for loading ordered chapter files that are not located on the local
+    filesystem, or if the referenced files are in different directories.
+
+    Note: a playlist can be as simple as a text file containing filenames
+    separated by newlines.
+
+``--chapters-file=<filename>``
+    Load chapters from this file, instead of using the chapter metadata found
+    in the main file.
+
+    This accepts a media file (like mkv) or even a pseudo-format like ffmetadata
+    and uses its chapters to replace the current file's chapters. This doesn't
+    work with OGM or XML chapters directly.
+
+``--sstep=<sec>``
+    Skip <sec> seconds after every frame.
+
+    .. note::
+
+        Without ``--hr-seek``, skipping will snap to keyframes.
+
+``--stop-playback-on-init-failure=<yes|no>``
+    Stop playback if either audio or video fails to initialize (default: no).
+    With ``no``, playback will continue in video-only or audio-only mode if one
+    of them fails. This doesn't affect playback of audio-only or video-only
+    files.
+
+``--play-direction=<forward|+|backward|->``
+    Control the playback direction (default: forward). Setting ``backward``
+    will attempt to play the file in reverse direction, with decreasing
+    playback time. If this is set on playback starts, playback will start from
+    the end of the file. If this is changed at during playback, a hr-seek will
+    be issued to change the direction.
+
+    ``+`` and ``-`` are aliases for ``forward`` and ``backward``.
+
+    The rest of this option description pertains to the ``backward`` mode.
+
+    .. note::
+
+        Backward playback is extremely fragile. It may not always work, is much
+        slower than forward playback, and breaks certain other features. How
+        well it works depends mainly on the file being played. Generally, it
+        will show good results (or results at all) only if the stars align.
+
+    mpv, as well as most media formats, were designed for forward playback
+    only. Backward playback is bolted on top of mpv, and tries to make a medium
+    effort to make backward playback work. Depending on your use-case, another
+    tool may work much better.
+
+    Backward playback is not exactly a 1st class feature. Implementation
+    tradeoffs were made, that are bad for backward playback, but in turn do not
+    cause disadvantages for normal playback. Various possible optimizations are
+    not implemented in order to keep the complexity down. Normally, a media
+    player is highly pipelined (future data is prepared in separate threads, so
+    it is available in realtime when the next stage needs it), but backward
+    playback will essentially stall the pipeline at various random points.
+
+    For example, for intra-only codecs are trivially backward playable, and
+    tools built around them may make efficient use of them (consider video
+    editors or camera viewers). mpv won't be efficient in this case, because it
+    uses its generic backward playback algorithm, that on top of it is not very
+    optimized.
+
+    If you just want to quickly go backward through the video and just show
+    "keyframes", just use forward playback, and hold down the left cursor key
+    (which on CLI with default config sends many small relative seek commands).
+
+    The implementation consists of mostly 3 parts:
+
+    - Backward demuxing. This relies on the demuxer cache, so the demuxer cache
+      should (or must, didn't test it) be enabled, and its size will affect
+      performance. If the cache is too small or too large, quadratic runtime
+      behavior may result.
+
+    - Backward decoding. The decoder library used (libavcodec) does not support
+      this. It is emulated by feeding bits of data in forward, putting the
+      result in a queue, returning the queue data to the VO in reverse, and
+      then starting over at an earlier position. This can require buffering an
+      extreme amount of decoded data, and also completely breaks pipelining.
+
+    - Backward output. This is relatively simple, because the decoder returns
+      the frames in the needed order. However, this may cause various problems
+      because filters see audio and video going backward.
+
+    Known problems:
+
+    - It's fragile. If anything doesn't work, random non-useful behavior may
+      occur. In simple cases, the player will just play nonsense and artifacts.
+      In other cases, it may get stuck or heat the CPU. (Exceeding memory usage
+      significantly beyond the user-set limits would be a bug, though.)
+
+    - Performance and resource usage isn't good. In part this is inherent to
+      backward playback of normal media formats, and in parts due to
+      implementation choices and tradeoffs.
+
+    - This is extremely reliant on good demuxer behavior. Although backward
+      demuxing requires no special demuxer support, it is required that the
+      demuxer performs seeks reliably, fulfills some specific requirements
+      about packet metadata, and has deterministic behavior.
+
+    - Starting playback exactly from the end may or may not work, depending on
+      seeking behavior and file duration detection.
+
+    - Some container formats, audio, and video codecs are not supported due to
+      their behavior. There is no list, and the player usually does not detect
+      them. Certain live streams (including TV captures) may exhibit problems
+      in particular, as well as some lossy audio codecs. h264 intra-refresh is
+      known not to work due to problems with libavcodec. WAV and some other raw
+      audio formats tend to have problems - there are hacks for dealing with
+      them, which may or may not work.
+
+    - Backward demuxing of subtitles is not supported. Subtitle display still
+      works for some external text subtitle formats. (These are fully read into
+      memory, and only backward display is needed.) Text subtitles that are
+      cached in the subtitle renderer also have a chance to be displayed
+      correctly.
+
+    - Some features dealing with playback of broken or hard to deal with files
+      will not work fully (such as timestamp correction).
+
+    - If demuxer low level seeks (i.e. seeking the actual demuxer instead of
+      just within the demuxer cache) are performed by backward playback, the
+      created seek ranges may not join, because not enough overlap is achieved.
+
+    - Trying to use this with hardware video decoding will probably exhaust all
+      your GPU memory and then crash a thing or two. Or it will fail because
+      ``--hwdec-extra-frames`` will certainly be set too low.
+
+    - Stream recording is broken. ``--stream-record`` may keep working if you
+      backward play within a cached region only.
+
+    - Relative seeks may behave weird. Small seeks backward (towards smaller
+      time, i.e. ``seek -1``) may not really seek properly, and audio will
+      remain muted for a while. Using hr-seek is recommended, which should have
+      none of these problems.
+
+    - Some things are just weird. For example, while seek commands manipulate
+      playback time in the expected way (provided they work correctly), the
+      framestep commands are transposed. Backstepping will perform very
+      expensive work to step forward by 1 frame.
+
+    Tuning:
+
+    - Remove all ``--vf``/``--af`` filters you have set. Disable hardware
+      decoding. Disable functions like SPDIF passthrough.
+
+    - Increasing ``--video-reversal-buffer`` might help if reversal queue
+      overflow is reported, which may happen in high bitrate video, or video
+      with large GOP. Hardware decoding mostly ignores this, and you need to
+      increase ``--hwdec-extra-frames`` instead (until you get playback without
+      logged errors).
+
+    - The demuxer cache is essential for backward demuxing. Make sure to set
+      ``--cache=yes``. The cache size might matter. If it's too small, a queue
+      overflow will be logged, and backward playback cannot continue, or it
+      performs too many low level seeks. If it's too large, implementation
+      tradeoffs may cause general performance issues. Use
+      ``--demuxer-max-bytes`` to potentially increase the amount of packets the
+      demuxer layer can queue for reverse demuxing (basically it's the
+      ``--video-reversal-buffer`` equivalent for the demuxer layer).
+
+    - Setting ``--vd-queue-enable=yes`` can help a lot to make playback smooth
+      (once it works).
+
+    - ``--demuxer-backward-playback-step`` also factors into how many seeks may
+      be performed, and whether backward demuxing could break due to queue
+      overflow. If it's set too high, the backstep operation needs to search
+      through more packets all the time, even if the cache is large enough.
+
+    - Setting ``--demuxer-cache-wait`` may be useful to cache the entire file
+      into the demuxer cache. Set ``--demuxer-max-bytes`` to a large size to
+      make sure it can read the entire cache; ``--demuxer-max-back-bytes``
+      should also be set to a large size to prevent that tries to trim the
+      cache.
+
+    - If audio artifacts are audible, even though the AO does not underrun,
+      increasing ``--audio-backward-overlap`` might help in some cases.
+
+``--video-reversal-buffer=<bytesize>``, ``--audio-reversal-buffer=<bytesize>``
+    For backward decoding. Backward decoding decodes forward in steps, and then
+    reverses the decoder output. These options control the approximate maximum
+    amount of bytes that can be buffered. The main use of this is to avoid
+    unbounded resource usage; during normal backward playback, it's not supposed
+    to hit the limit, and if it does, it will drop frames and complain about it.
+
+    Use this option if you get reversal queue overflow errors during backward
+    playback. Increase the size until the warning disappears. Usually, the video
+    buffer will overflow first, especially if it's high resolution video.
+
+    This does not work correctly if video hardware decoding is used. The video
+    frame size will not include the referenced GPU and driver memory. Some
+    hardware decoders may also be limited by ``--hwdec-extra-frames``.
+
+    How large the queue size needs to be depends entirely on the way the media
+    was encoded. Audio typically requires a very small buffer, while video can
+    require excessively large buffers.
+
+    (Technically, this allows the last frame to exceed the limit. Also, this
+    does not account for other buffered frames, such as inside the decoder or
+    the video output.)
+
+    This does not affect demuxer cache behavior at all.
+
+    See ``--list-options`` for defaults and value range. ``<bytesize>`` options
+    accept suffixes such as ``KiB`` and ``MiB``.
+
+``--video-backward-overlap=<auto|number>``, ``--audio-backward-overlap=<auto|number>``
+    Number of overlapping keyframe ranges to use for backward decoding (default:
+    auto) ("keyframe" to be understood as in the mpv/ffmpeg specific meaning).
+    Backward decoding works by forward decoding in small steps. Some codecs
+    cannot restart decoding from any packet (even if it's marked as seek point),
+    which becomes noticeable with backward decoding (in theory this is a problem
+    with seeking too, but ``--hr-seek-demuxer-offset`` can fix it for seeking).
+    In particular, MDCT based audio codecs are affected.
+
+    The solution is to feed a previous packet to the decoder each time, and then
+    discard the output. This option controls how many packets to feed. The
+    ``auto`` choice is currently hardcoded to 0 for video, and uses 1 for lossy
+    audio, 0 for lossless audio. For some specific lossy audio codecs, this is
+    set to 2.
+
+    ``--video-backward-overlap`` can potentially handle intra-refresh video,
+    depending on the exact conditions. You may have to use the
+    ``--vd-lavc-show-all`` option as well.
+
+``--video-backward-batch=<number>``, ``--audio-backward-batch=<number>``
+    Number of keyframe ranges to decode at once when backward decoding (default:
+    1 for video, 10 for audio). Another pointless tuning parameter nobody should
+    use. This should affect performance only. In theory, setting a number higher
+    than 1 for audio will reduce overhead due to less frequent backstep
+    operations and less redundant decoding work due to fewer decoded overlap
+    frames (see ``--audio-backward-overlap``). On the other hand, it requires
+    a larger reversal buffer, and could make playback less smooth due to
+    breaking pipelining (e.g. by decoding a lot, and then doing nothing for a
+    while).
+
+    It probably never makes sense to set ``--video-backward-batch``. But in
+    theory, it could help with intra-only video codecs by reducing backstep
+    operations.
+
+``--demuxer-backward-playback-step=<seconds>``
+    Number of seconds the demuxer should seek back to get new packets during
+    backward playback (default: 60). This is useful for tuning backward
+    playback, see ``--play-direction`` for details.
+
+    Setting this to a very low value or 0 may make the player think seeking is
+    broken, or may make it perform multiple seeks.
+
+    Setting this to a high value may lead to quadratic runtime behavior.
+
+Program Behavior
+----------------
+
+``--help``, ``--h``
+    Show short summary of options.
+
+    You can also pass a string to this option, which will list all top-level
+    options which contain the string in the name, e.g. ``--h=scale`` for all
+    options that contain the word ``scale``. The special string ``*`` lists
+    all top-level options.
+
+``-v``
+    Increment verbosity level, one level for each ``-v`` found on the command
+    line.
+
+``--version, -V``
+    Print version string and exit.
+
+``--no-config``
+    Do not load default configuration or any user files. This prevents loading of
+    both the user-level and system-wide ``mpv.conf`` and ``input.conf`` files. Other
+    user files are blocked as well, such as resume playback files and cache files.
+    This option only takes effect when used as a command line flag.
+
+    .. note::
+
+        Files explicitly requested by command line options, like
+        ``--include`` or ``--use-filedir-conf``, will still be loaded.
+
+    See also: ``--config-dir``.
+
+``--list-options``
+    Prints all available options.
+
+``--list-properties``
+    Print a list of the available properties.
+
+``--list-protocols``
+    Print a list of the supported protocols.
+
+``--log-file=<path>``
+    Opens the given path for writing, and print log messages to it. Existing
+    files will be truncated. The log level is at least ``-v -v``, but
+    can be raised via ``--msg-level`` (the option cannot lower it below the
+    forced minimum log level).
+
+    A special case is the macOS bundle, it will create a log file at
+    ``~/Library/Logs/mpv.log`` by default.
+
+``--config-dir=<path>``
+    Force a different configuration directory. If this is set, the given
+    directory is used to load configuration files, and all other configuration
+    directories are ignored. This means the global mpv configuration directory
+    as well as per-user directories are ignored, and overrides through
+    environment variables (``MPV_HOME``) are also ignored.
+
+    Note that the cache and state paths (``~~/cache``, ``~~/state``) are not
+    considered "configuration" and keep their auto-detection logic.
+
+    Note that the ``--no-config`` option takes precedence over this option.
+
+``--dump-stats=<filename>``
+    Write certain statistics to the given file. The file is truncated on
+    opening. The file will contain raw samples, each with a timestamp. To
+    make this file into a readable, the script ``TOOLS/stats-conv.py`` can be
+    used (which currently displays it as a graph).
+
+    This option is useful for debugging only.
+
+``--idle=<no|yes|once>``
+    Makes mpv wait idly instead of quitting when there is no file to play.
+    Mostly useful in input mode, where mpv can be controlled through input
+    commands. (Default: ``no``)
+
+    ``once`` will only idle at start and let the player close once the
+    first playlist has finished playing back.
+
+``--include=<configuration-file>``
+    Specify configuration file to be parsed after the default ones.
+
+``--load-scripts=<yes|no>``
+    If set to ``no``, don't auto-load scripts from the ``scripts``
+    configuration subdirectory (usually ``~/.config/mpv/scripts/``).
+    (Default: ``yes``)
+
+``--script=<filename>``, ``--scripts=file1.lua:file2.lua:...``
+    Load a Lua script. The second option allows you to load multiple scripts by
+    separating them with the path separator (``:`` on Unix, ``;`` on Windows).
+
+    ``--scripts`` is a path list option. See `List Options`_ for details.
+
+``--script-opts=key1=value1,key2=value2,...``
+    Set options for scripts. A script can query an option by key. If an
+    option is used and what semantics the option value has depends entirely on
+    the loaded scripts. Values not claimed by any scripts are ignored.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+``--merge-files``
+    Pretend that all files passed to mpv are concatenated into a single, big
+    file. This uses timeline/EDL support internally.
+
+``--profile=<profile1,profile2,...>``
+    Use the given profile(s), ``--profile=help`` displays a list of the
+    defined profiles.
+
+``--reset-on-next-file=<all|option1,option2,...>``
+    Normally, mpv will try to keep all settings when playing the next file on
+    the playlist, even if they were changed by the user during playback. (This
+    behavior is the opposite of MPlayer's, which tries to reset all settings
+    when starting next file.)
+
+    Default: Do not reset anything.
+
+    This can be changed with this option. It accepts a list of options, and
+    mpv will reset the value of these options on playback start to the initial
+    value. The initial value is either the default value, or as set by the
+    config file or command line.
+
+    The special name ``all`` resets as many options as possible.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``--reset-on-next-file=pause``
+          Reset pause mode when switching to the next file.
+        - ``--reset-on-next-file=fullscreen,speed``
+          Reset fullscreen and playback speed settings if they were changed
+          during playback.
+        - ``--reset-on-next-file=all``
+          Try to reset all settings that were changed during playback.
+
+``--show-profile=<profile>``
+    Show the description and content of a profile. Lists all profiles if no
+    parameter is provided.
+
+``--use-filedir-conf``
+    Look for a file-specific configuration file in the same directory as the
+    file that is being played. See `File-specific Configuration Files`_.
+
+    .. warning::
+
+        May be dangerous if playing from untrusted media.
+
+``--ytdl``, ``--no-ytdl``
+    Enable the youtube-dl hook-script. It will look at the input URL, and will
+    play the video located on the website. This works with many streaming sites,
+    not just the one that the script is named after. This requires a recent
+    version of youtube-dl to be installed on the system. (Enabled by default.)
+
+    If the script can't do anything with an URL, it will do nothing.
+
+    This accepts a set of options, which can be passed to it with the
+    ``--script-opts`` option (using ``ytdl_hook-`` as prefix):
+
+    ``try_ytdl_first=<yes|no>``
+        If 'yes' will try parsing the URL with youtube-dl first, instead of the
+        default where it's only after mpv failed to open it. This mostly depends
+        on whether most of your URLs need youtube-dl parsing.
+
+    ``exclude=<URL1|URL2|...``
+        A ``|``-separated list of URL patterns which mpv should not use with
+        youtube-dl. The patterns are matched after the ``http(s)://`` part of
+        the URL.
+
+        ``^`` matches the beginning of the URL, ``$`` matches its end, and you
+        should use ``%`` before any of the characters ``^$()%|,.[]*+-?`` to
+        match that character.
+
+        .. admonition:: Examples
+
+            - ``--script-opts=ytdl_hook-exclude='^youtube%.com'``
+              will exclude any URL that starts with ``http://youtube.com`` or
+              ``https://youtube.com``.
+            - ``--script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$'``
+              will exclude any URL that ends with ``.mkv`` or ``.mp4``.
+
+        See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1
+
+    ``all_formats=<yes|no>``
+        If 'yes' will attempt to add all formats found reported by youtube-dl
+        (default: no). Each format is added as a separate track. In addition,
+        they are delay-loaded, and actually opened only when a track is selected
+        (this should keep load times as low as without this option).
+
+        It adds average bitrate metadata, if available, which means you can use
+        ``--hls-bitrate`` to decide which track to select. (HLS used to be the
+        only format whose alternative quality streams were exposed in a similar
+        way, thus the option name.)
+
+        Tracks which represent formats that were selected by youtube-dl as
+        default will have the default flag set. This means mpv should generally
+        still select formats chosen with ``--ytdl-format`` by default.
+
+        Although this mechanism makes it possible to switch streams at runtime,
+        it's not suitable for this purpose for various technical reasons. (It's
+        slow, which can't be really fixed.) In general, this option is not
+        useful, and was only added to show that it's possible.
+
+        There are two cases that must be considered when doing quality/bandwidth
+        selection:
+
+            1. Completely separate audio and video streams (DASH-like). Each of
+               these streams contain either only audio or video, so you can
+               mix and combine audio/video bandwidths without restriction. This
+               intuitively matches best with the concept of selecting quality
+               by track (what ``all_formats`` is supposed to do).
+
+            2. Separate sets of muxed audio and video streams. Each version of
+               the media contains both an audio and video stream, and they are
+               interleaved. In order not to waste bandwidth, you should only
+               select one of these versions (if, for example, you select an
+               audio stream, then video will be downloaded, even if you selected
+               video from a different stream).
+
+               mpv will still represent them as separate tracks, but will set
+               the title of each track to ``muxed-N``, where ``N`` is replaced
+               with the youtube-dl format ID of the originating stream.
+
+        Some sites will mix 1. and 2., but we assume that they do so for
+        compatibility reasons, and there is no reason to use them at all.
+
+    ``force_all_formats=<yes|no>``
+        If set to 'yes', and ``all_formats`` is also set to 'yes', this will
+        try to represent all youtube-dl reported formats as tracks, even if
+        mpv would normally use the direct URL reported by it (default: yes).
+
+        It appears this normally makes a difference if youtube-dl works on a
+        master HLS playlist.
+
+        If this is set to 'no', this specific kind of stream is treated like
+        ``all_formats`` is set to 'no', and the stream selection as done by
+        youtube-dl (via ``--ytdl-format``) is used.
+
+    ``thumbnails=<all|best|none>``
+        Add thumbnails as video tracks (default: none).
+
+        Thumbnails get downloaded when they are added as tracks, so 'all' can
+        have a noticable impact on how long it takes to open the video when
+        there are a lot of thumbnails.
+
+    ``use_manifests=<yes|no>``
+        Make mpv use the master manifest URL for formats like HLS and DASH,
+        if available, allowing for video/audio selection in runtime (default:
+        no). It's disabled ("no") by default for performance reasons.
+
+    ``ytdl_path=youtube-dl``
+        Configure paths to youtube-dl's executable or a compatible fork's. The
+        paths should be separated by : on Unix and ; on Windows. mpv looks in
+        order for the configured paths in PATH and in mpv's config directory.
+        The defaults are "yt-dlp", "yt-dlp_x86" and "youtube-dl". On Windows
+        the suffix extension is not necessary, but only ".exe" is acceptable.
+
+    .. admonition:: Why do the option names mix ``_`` and ``-``?
+
+        I have no idea.
+
+``--ytdl-format=<ytdl|best|worst|mp4|webm|...>``
+    Video format/quality that is directly passed to youtube-dl. The possible
+    values are specific to the website and the video, for a given url the
+    available formats can be found with the command
+    ``youtube-dl --list-formats URL``. See youtube-dl's documentation for
+    available aliases.
+    (Default: ``bestvideo+bestaudio/best``)
+
+    The ``ytdl`` value does not pass a ``--format`` option to youtube-dl at all,
+    and thus does not override its default. Note that sometimes youtube-dl
+    returns a format that mpv cannot use, and in these cases the mpv default
+    may work better.
+
+``--ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]``
+    Pass arbitrary options to youtube-dl. Parameter and argument should be
+    passed as a key-value pair. Options without argument must include ``=``.
+
+    There is no sanity checking so it's possible to break things (i.e.
+    passing invalid parameters to youtube-dl).
+
+    A proxy URL can be passed for youtube-dl to use it in parsing the website.
+    This is useful for geo-restricted URLs. After youtube-dl parsing, some
+    URLs also require a proxy for playback, so this can pass that proxy
+    information to mpv. Take note that SOCKS proxies aren't supported and
+    https URLs also bypass the proxy. This is a limitation in FFmpeg.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        - ``--ytdl-raw-options=username=user,password=pass``
+        - ``--ytdl-raw-options=force-ipv6=``
+        - ``--ytdl-raw-options=proxy=[http://127.0.0.1:3128]``
+        - ``--ytdl-raw-options-append=proxy=http://127.0.0.1:3128``
+
+``--js-memory-report=<yes|no>``
+    Enable memory reporting for javascript scripts in the stats overlay.
+    This is disabled by default because it has an overhead and increases
+    memory usage. This option will only work if it is enabled before mpv is
+    started.
+
+``--load-stats-overlay=<yes|no>``
+    Enable the builtin script that shows useful playback information on a key
+    binding (default: yes). By default, the ``i`` key is used (``I`` to make
+    the overlay permanent).
+
+``--load-osd-console=<yes|no>``
+    Enable the built-in script that shows a console on a key binding and lets
+    you enter commands (default: yes). The ````` key is used to show the
+    console by default, and ``ESC`` to hide it again.
+
+``--load-auto-profiles=<yes|no|auto>``
+    Enable the builtin script that does auto profiles (default: auto). See
+    `Conditional auto profiles`_ for details. ``auto`` will load the script,
+    but immediately unload it if there are no conditional profiles.
+
+``--player-operation-mode=<cplayer|pseudo-gui>``
+    For enabling "pseudo GUI mode", which means that the defaults for some
+    options are changed. This option should not normally be used directly, but
+    only by mpv internally, or mpv-provided scripts, config files, or .desktop
+    files. See `PSEUDO GUI MODE`_ for details.
+
+Watch Later
+-----------
+
+``--save-position-on-quit``
+    Always save the current playback position on quit. When this file is
+    played again later, the player will seek to the old playback position on
+    start. This does not happen if playback of a file is stopped in any other
+    way than quitting. For example, going to the next file in the playlist
+    will not save the position, and start playback at beginning the next time
+    the file is played.
+
+    This behavior is disabled by default, but is always available when quitting
+    the player with Shift+Q.
+
+    See `RESUMING PLAYBACK`_.
+
+``--watch-later-dir=<path>``
+    The directory in which to store the "watch later" temporary files.
+
+    ``--watch-later-directory`` is an alias for ``--watch-later-dir``.
+
+    If this option is unset, the files will be stored in a subdirectory
+    named "watch_later" underneath the local state directory
+    (usually ``~/.local/state/mpv/``).
+
+``--no-resume-playback``
+    Do not restore playback position from the ``watch_later`` configuration
+    subdirectory (usually ``~/.config/mpv/watch_later/``).
+
+``--resume-playback-check-mtime``
+    Only restore the playback position from the ``watch_later`` configuration
+    subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
+    modification time is the same as at the time of saving. This may prevent
+    skipping forward in files with the same name which have different content.
+    (Default: ``no``)
+
+``--watch-later-options=option1,option2,...``
+    The options that are saved in "watch later" files if they have been changed
+    since when mpv started. These values will be restored the next time the
+    files are played. Note that the playback position is saved via the ``start``
+    option.
+
+    When removing options, existing watch later data won't be modified and will
+    still be applied fully, but new watch later data won't contain these
+    options.
+
+    See ``--help=watch-later-options`` for the list of the properties that are
+    restored by default.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``--watch-later-options-remove=sid``
+          The subtitle track selection will not be restored.
+        - ``--watch-later-options-remove=volume``
+          ``--watch-later-options-remove=mute``
+          The volume and mute state won't be saved to watch later files.
+        - ``--watch-later-options=start``
+          No option will be saved to watch later files, except the playback
+          position.
+
+``--write-filename-in-watch-later-config``
+    Prepend the watch later config files with the name of the file they refer
+    to. This is simply written as comment on the top of the file.
+
+    .. warning::
+
+        This option may expose privacy-sensitive information and is thus
+        disabled by default.
+
+``--ignore-path-in-watch-later-config``
+    Ignore path (i.e. use filename only) when using watch later feature.
+    (Default: disabled)
+
+Video
+-----
+
+``--vo=<driver>``
+    Specify the video output backend to be used. See `VIDEO OUTPUT DRIVERS`_ for
+    details and descriptions of available drivers.
+
+``--vd=<...>``
+    Specify a priority list of video decoders to be used, according to their
+    family and name. See ``--ad`` for further details. Both of these options
+    use the same syntax and semantics; the only difference is that they
+    operate on different codec lists.
+
+    .. note::
+
+        See ``--vd=help`` for a full list of available decoders.
+
+``--vf=<filter1[=parameter1:parameter2:...],filter2,...>``
+    Specify a list of video filters to apply to the video stream. See
+    `VIDEO FILTERS`_ for details and descriptions of the available filters.
+    The option variants ``--vf-add``, ``--vf-pre``, and ``--vf-clr`` exist
+    to modify a previously specified list, but you should not need these for
+    typical use.
+
+``--untimed``
+    Do not sleep when outputting video frames. Useful for benchmarks when used
+    with ``--no-audio.``
+
+``--framedrop=<mode>``
+    Skip displaying some frames to maintain A/V sync on slow systems, or
+    playing high framerate video on video outputs that have an upper framerate
+    limit.
+
+    The argument selects the drop methods, and can be one of the following:
+
+    <no>
+        Disable any frame dropping. Not recommended, for testing only.
+    <vo>
+        Drop late frames on video output (default). This still decodes and
+        filters all frames, but doesn't render them on the VO. Drops are
+        indicated in the terminal status line as ``Dropped:`` field.
+
+        In audio sync. mode, this drops frames that are outdated at the time of
+        display. If the decoder is too slow, in theory all frames would have to
+        be dropped (because all frames are too late) - to avoid this, frame
+        dropping stops  if the effective framerate is below 10 FPS.
+
+        In display-sync. modes (see ``--video-sync``), this affects only how
+        A/V drops or repeats frames. If this mode is disabled, A/V desync will
+        in theory not affect video scheduling anymore (much like the
+        ``display-resample-desync`` mode). However, even if disabled, frames
+        will still be skipped (i.e. dropped) according to the ratio between
+        video and display frequencies.
+
+        This is the recommended mode, and the default.
+    <decoder>
+        Old, decoder-based framedrop mode. (This is the same as ``--framedrop=yes``
+        in mpv 0.5.x and before.) This tells the decoder to skip frames (unless
+        they are needed to decode future frames). May help with slow systems,
+        but can produce unwatchable choppy output, or even freeze the display
+        completely.
+
+        This uses a heuristic which may not make sense, and in  general cannot
+        achieve good results, because the decoder's frame dropping cannot be
+        controlled in a predictable manner. Not recommended.
+
+        Even if you want to use this, prefer ``decoder+vo`` for better results.
+
+        The ``--vd-lavc-framedrop`` option controls what frames to drop.
+    <decoder+vo>
+        Enable both modes. Not recommended. Better than just ``decoder`` mode.
+
+    .. note::
+
+        ``--vo=vdpau`` has its own code for the ``vo`` framedrop mode. Slight
+        differences to other VOs are possible.
+
+``--video-latency-hacks=<yes|no>``
+    Enable some things which tend to reduce video latency by 1 or 2 frames
+    (default: no). Note that this option might be removed without notice once
+    the player's timing code does not inherently need to do these things
+    anymore. Using this option is known to break other options such as
+    interpolation, so it is not recommended to enable this.
+
+    This does:
+
+    - Use the demuxer reported FPS for frame dropping. This avoids the
+      player needing to decode 1 frame in advance, lowering total latency in
+      effect. This also means that if the demuxer reported FPS is wrong, or
+      the video filter chain changes FPS (e.g. deinterlacing), then it could
+      drop too many or not enough frames.
+    - Disable waiting for the first video frame. Normally the player waits for
+      the first video frame to be fully rendered before starting playback
+      properly. Some VOs will lazily initialize stuff when rendering the first
+      frame, so if this is not done, there is some likeliness that the VO has
+      to drop some frames if rendering the first frame takes longer than needed.
+
+``--display-fps-override=<fps>``
+    Set the display FPS used with the ``--video-sync=display-*`` modes. By
+    default, a detected value is used. Keep in mind that setting an incorrect
+    value (even if slightly incorrect) can ruin video playback. On multi-monitor
+    systems, there is a chance that the detected value is from the wrong
+    monitor.
+
+    Set this option only if you have reason to believe the automatically
+    determined value is wrong.
+
+``--hwdec=<api1,api2,...|no|auto|auto-safe|auto-copy>``
+    Specify the hardware video decoding API that should be used if possible.
+    Whether hardware decoding is actually done depends on the video codec. If
+    hardware decoding is not possible, mpv will fall back on software decoding.
+
+    Hardware decoding is not enabled by default, to keep the out-of-the-box
+    configuration as reliable as possible. However, when using modern hardware,
+    hardware video decoding should work correctly, offering reduced CPU usage,
+    and possibly lower power consumption. On older systems, it may be necessary
+    to use hardware decoding due to insufficient CPU resources; and even on
+    modern systems, sufficiently complex content (eg: 4K60 AV1) may require it.
+
+    .. note::
+
+        Use the ``Ctrl+h`` shortcut to toggle hardware decoding at runtime. It
+        toggles this option between ``auto-safe`` and ``no``.
+
+        If you decide you want to use hardware decoding by default, the general
+        recommendation is to try out decoding with the command line option, and
+        prove to yourself that it works as desired for the content you care
+        about. After that, you can add it to your config file.
+
+        When testing, you should start by using ``hwdec=auto-safe`` as it will
+        limit itself to choosing from hwdecs that are actively supported by the
+        development team. If that doesn't result in working hardware decoding,
+        you can try ``hwdec=auto`` to have it attempt to load every possible
+        hwdec, but if ``auto-safe`` didn't work, you will probably need to know
+        exactly which hwdec matches your hardware and read up on that entry
+        below.
+
+        If ``auto-safe`` or ``auto`` produced the desired results, we recommend
+        just sticking with that and only setting a specific hwdec in your config
+        file if it is really necessary.
+
+        If you use the Ubuntu package, keep in mind that their
+        ``/etc/mpv/mpv.conf`` contains ``hwdec=vaapi``, which is less than
+        ideal as it may not be the right choice for your system, and it may end
+        up using an inefficient wrapper library under the covers. We recommend
+        removing this line or deleting the file altogether.
+
+    .. note::
+
+        Even if enabled, hardware decoding is still only white-listed for some
+        codecs. See ``--hwdec-codecs`` to enable hardware decoding in more cases.
+
+    .. admonition:: Which method to choose?
+
+        - If you only want to enable hardware decoding at runtime, don't set the
+          parameter, or put ``hwdec=no`` into your ``mpv.conf`` (relevant on
+          distros which force-enable it by default, such as on Ubuntu). Use the
+          ``Ctrl+h`` default binding to enable it at runtime.
+        - If you're not sure, but want hardware decoding always enabled by
+          default, put ``hwdec=auto-safe`` into your ``mpv.conf``, and
+          acknowledge that this may cause problems.
+        - If you want to test available hardware decoding methods, pass
+          ``--hwdec=auto --hwdec-codecs=all`` and look at the terminal output.
+        - If you're a developer, or want to perform elaborate tests, you may
+          need any of the other possible option values.
+
+    This option accepts a comma delimited list of ``api`` types, along with certain
+    special values:
+
+    :no:        always use software decoding (default)
+    :auto-safe: enable any whitelisted hw decoder (see below)
+    :auto:      forcibly enable any hw decoder found (see below)
+    :yes:       exactly the same as ``auto-safe``
+    :auto-copy: enable best hw decoder with copy-back (see below)
+
+    .. note::
+
+        Special values can be mixed with api names. eg: ``vaapi,auto`` will try
+        and use the ``vaapi`` hwdec, and if that fails, will run through the
+        normal ``auto`` logic.
+
+    Actively supported hwdecs:
+
+    :d3d11va:   requires ``--vo=gpu`` with ``--gpu-context=d3d11`` or
+                ``--gpu-context=angle`` (Windows 8+ only)
+    :d3d11va-copy: copies video back to system RAM (Windows 8+ only)
+    :videotoolbox: requires ``--vo=gpu`` (macOS 10.8 and up),
+                   or ``--vo=libmpv`` (iOS 9.0 and up)
+    :videotoolbox-copy: copies video back into system RAM (macOS 10.8 or iOS 9.0 and up)
+    :vaapi:     requires ``--vo=gpu``, ``--vo=vaapi`` or ``--vo=dmabuf-wayland`` (Linux only)
+    :vaapi-copy: copies video back into system RAM (Linux with some GPUs only)
+    :nvdec:     requires ``--vo=gpu`` (Any platform CUDA is available)
+    :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
+    :drm:       requires ``--vo=gpu`` (Linux only)
+    :drm-copy:   copies video back to system RAM (Linux only)
+    :vulkan:    requires ``--vo=gpu-next`` (Any platform with Vulkan Video Decoding)
+    :vulkan-copy: copies video back to system RAM (Any platform with Vulkan Video Decoding)
+
+    Other hwdecs (only use if you know you have to):
+
+    :dxva2:     requires ``--vo=gpu`` with ``--gpu-context=d3d11``,
+                ``--gpu-context=angle`` or ``--gpu-context=dxinterop``
+                (Windows only)
+    :dxva2-copy: copies video back to system RAM (Windows only)
+    :vdpau:     requires ``--vo=gpu`` with ``--gpu-context=x11``, or
+                ``--vo=vdpau`` (Linux only)
+    :vdpau-copy: copies video back into system RAM (Linux with some GPUs only)
+    :mediacodec: requires ``--vo=gpu --gpu-context=android``
+                 or ``--vo=mediacodec_embed`` (Android only)
+    :mediacodec-copy: copies video back to system RAM (Android only)
+    :mmal:      requires ``--vo=gpu`` (Raspberry Pi only - default if available)
+    :mmal-copy: copies video back to system RAM (Raspberry Pi only)
+    :cuda:      requires ``--vo=gpu`` (Any platform CUDA is available)
+    :cuda-copy: copies video back to system RAM (Any platform CUDA is available)
+    :crystalhd: copies video back to system RAM (Any platform supported by hardware)
+    :rkmpp:     requires ``--vo=gpu`` (some RockChip devices only)
+
+    ``auto`` tries to automatically enable hardware decoding using the first
+    available method. This still depends what VO you are using. For example,
+    if you are not using ``--vo=gpu`` or ``--vo=vdpau``, vdpau decoding will
+    never be enabled. Also note that if the first found method doesn't actually
+    work, it will always fall back to software decoding, instead of trying the
+    next method (might matter on some Linux systems).
+
+    ``auto-safe`` is similar to ``auto``, but allows only whitelisted methods
+    that are considered "safe". This is supposed to be a reasonable way to
+    enable hardware decdoding by default in a config file (even though you
+    shouldn't do that anyway; prefer runtime enabling with ``Ctrl+h``). Unlike
+    ``auto``, this will not try to enable unknown or known-to-be-bad methods. In
+    addition, this may disable hardware decoding in other situations when it's
+    known to cause problems, but currently this mechanism is quite primitive.
+    (As an example for something that still causes problems: certain
+    combinations of HEVC and Intel chips on Windows tend to cause mpv to crash,
+    most likely due to driver bugs.)
+
+    ``auto-copy-safe`` selects the union of methods selected with ``auto-safe``
+    and ``auto-copy``.
+
+    ``auto-copy`` selects only modes that copy the video data back to system
+    memory after decoding. This selects modes like ``vaapi-copy`` (and so on).
+    If none of these work, hardware decoding is disabled. This mode is usually
+    guaranteed to incur no additional quality loss compared to software
+    decoding (assuming modern codecs and an error free video stream), and will
+    allow CPU processing with video filters. This mode works with all video
+    filters and VOs.
+
+    Because these copy the decoded video back to system RAM, they're often less
+    efficient than the direct modes, and may not help too much over software
+    decoding if you are short on CPU resources.
+
+    .. note::
+
+       Most non-copy methods only work with the OpenGL GPU backend. Currently,
+       only the ``vaapi``, ``nvdec``, ``cuda`` and ``vulkan`` methods work with
+       Vulkan.
+
+    The ``vaapi`` mode, if used with ``--vo=gpu``, requires Mesa 11, and most
+    likely works with Intel and AMD GPUs only. It also requires the opengl EGL
+    backend.
+
+    ``nvdec`` and ``nvdec-copy`` are the newest, and recommended method to do
+    hardware decoding on Nvidia GPUs.
+
+    ``cuda`` and ``cuda-copy`` are an older implementation of hardware decoding
+    on Nvidia GPUs that uses Nvidia's bitstream parsers rather than FFmpeg's.
+    This can lead to feature deficiencies, such as incorrect playback of HDR
+    content, and ``nvdec``/``nvdec-copy`` should always be preferred unless you
+    specifically need Nvidia's deinterlacing algorithms. To use this
+    deinterlacing you must pass the option:
+    ``vd-lavc-o=deint=[weave|bob|adaptive]``.
+    Pass ``weave`` (or leave the option unset) to not attempt any
+    deinterlacing.
+
+    .. admonition:: Quality reduction with hardware decoding
+
+        In theory, hardware decoding does not reduce video quality (at least
+        for the codecs h264 and HEVC). However, due to restrictions in video
+        output APIs, as well as bugs in the actual hardware decoders, there can
+        be some loss, or even blatantly incorrect results. This has largely
+        ceased to be a problem with modern hardware, but there is a lot of
+        hardware out there, so caveat emptor. Known problems are discussed
+        below, but the list cannot be considered exhaustive, as even hwdecs that
+        work well on certain hardware generations may be problematic on other
+        ones.
+
+        In some cases, RGB conversion is forced, which means the RGB conversion
+        is performed by the hardware decoding API, instead of the shaders
+        used by ``--vo=gpu``. This means certain colorspaces may not display
+        correctly, and certain filtering (such as debanding) cannot be applied
+        in an ideal way. This will also usually force the use of low quality
+        chroma scalers instead of the one specified by ``--cscale``. In other
+        cases, hardware decoding can also reduce the bit depth of the decoded
+        image, which can introduce banding or precision loss for 10-bit files.
+
+        ``vdpau`` always does RGB conversion in hardware, which does not
+        support newer colorspaces like BT.2020 correctly. However, ``vdpau``
+        doesn't support 10 bit or HDR encodings, so these limitations are
+        unlikely to be relevant.
+
+        ``dxva2`` is not safe. It appears to always use BT.601 for forced RGB
+        conversion, but actual behavior depends on the GPU drivers. Some drivers
+        appear to convert to limited range RGB, which gives a faded appearance.
+        In addition to driver-specific behavior, global system settings might
+        affect this additionally. This can give incorrect results even with
+        completely ordinary video sources.
+
+        ``rpi`` always uses the hardware overlay renderer, even with
+        ``--vo=gpu``.
+
+        ``mediacodec`` is not safe. It forces RGB conversion (not with ``-copy``)
+        and how well it handles non-standard colorspaces is not known.
+        In the rare cases where 10-bit is supported the bit depth of the output
+        will be reduced to 8.
+
+        ``cuda`` should usually be safe, but depending on how a file/stream
+        has been mixed, it has been reported to corrupt the timestamps causing
+        glitched, flashing frames. It can also sometimes cause massive
+        framedrops for unknown reasons. Caution is advised, and ``nvdec``
+        should always be preferred.
+
+        ``crystalhd`` is not safe. It always converts to 4:2:2 YUV, which
+        may be lossy, depending on how chroma sub-sampling is done during
+        conversion. It also discards the top left pixel of each frame for
+        some reason.
+
+        If you run into any weird decoding issues, frame glitches or
+        discoloration, and you have ``--hwdec`` turned on, the first thing you
+        should try is disabling it.
+
+``--gpu-hwdec-interop=<auto|all|no|name>``
+    This option is for troubleshooting hwdec interop issues. Since it's a
+    debugging option, its semantics may change at any time.
+
+    This is useful for the ``gpu`` and ``libmpv`` VOs for selecting which
+    hwdec interop context to use exactly. Effectively it also can be used
+    to block loading of certain backends.
+
+    If set to ``auto`` (default), the behavior depends on the VO: for ``gpu``,
+    it does nothing, and the interop context is loaded on demand (when the
+    decoder probes for ``--hwdec`` support). For ``libmpv``, which has
+    has no on-demand loading, this is equivalent to ``all``.
+
+    The empty string is equivalent to ``auto``.
+
+    If set to ``all``, it attempts to load all interop contexts at GL context
+    creation time.
+
+    Other than that, a specific backend can be set, and the list of them can
+    be queried with ``help`` (mpv CLI only).
+
+    Runtime changes to this are ignored (the current option value is used
+    whenever the renderer is created).
+
+``--hwdec-extra-frames=<N>``
+    Number of GPU frames hardware decoding should preallocate (default: see
+    ``--list-options`` output). If this is too low, frame allocation may fail
+    during decoding, and video frames might get dropped and/or corrupted.
+    Setting it too high simply wastes GPU memory and has no advantages.
+
+    This value is used only for hardware decoding APIs which require
+    preallocating surfaces (known examples include ``d3d11va`` and ``vaapi``).
+    For other APIs, frames are allocated as needed. The details depend on the
+    libavcodec implementations of the hardware decoders.
+
+    The required number of surfaces depends on dynamic runtime situations. The
+    default is a fixed value that is thought to be sufficient for most uses. But
+    in certain situations, it may not be enough.
+
+``--hwdec-image-format=<name>``
+    Set the internal pixel format used by hardware decoding via ``--hwdec``
+    (default ``no``). The special value ``no`` selects an implementation
+    specific standard format. Most decoder implementations support only one
+    format, and will fail to initialize if the format is not supported.
+
+    Some implementations might support multiple formats. In particular,
+    videotoolbox is known to require ``uyvy422`` for good performance on some
+    older hardware. d3d11va can always use ``yuv420p``, which uses an opaque
+    format, with likely no advantages.
+
+``--cuda-decode-device=<auto|0..>``
+    Choose the GPU device used for decoding when using the ``cuda`` or
+    ``nvdec`` hwdecs with the OpenGL GPU backend, and with the ``cuda-copy``
+    or ``nvdec-copy`` hwdecs in all cases.
+
+    For the OpenGL GPU backend, the default device used for decoding is the one
+    being used to provide ``gpu`` output (and in the vast majority of cases,
+    only one GPU will be present).
+
+    For the ``copy`` hwdecs, the default device will be the first device
+    enumerated by the CUDA libraries - however that is done.
+
+    For the Vulkan GPU backend, decoding must always happen on the display
+    device, and this option has no effect.
+
+``--vaapi-device=<device file>``
+    Choose the DRM device for ``vaapi-copy``. This should be the path to a
+    DRM device file. (Default: ``/dev/dri/renderD128``)
+
+``--panscan=<0.0-1.0>``
+    Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9
+    video to make it fit a 4:3 display without black bands). The range
+    controls how much of the image is cropped. May not work with all video
+    output drivers.
+
+    This option has no effect if ``--video-unscaled`` option is used.
+
+``--video-aspect-override=<ratio|no>``
+    Override video aspect ratio, in case aspect information is incorrect or
+    missing in the file being played.
+
+    These values have special meaning:
+
+    :0:  disable aspect ratio handling, pretend the video has square pixels
+    :no: same as ``0``
+    :-1: use the video stream or container aspect (default)
+
+    But note that handling of these special values might change in the future.
+
+    .. admonition:: Examples
+
+        - ``--video-aspect-override=4:3``  or ``--video-aspect-override=1.3333``
+        - ``--video-aspect-override=16:9`` or ``--video-aspect-override=1.7777``
+        - ``--no-video-aspect-override`` or ``--video-aspect-override=no``
+
+``--video-aspect-method=<bitstream|container>``
+    This sets the default video aspect determination method (if the aspect is
+    _not_ overridden by the user with ``--video-aspect-override`` or others).
+
+    :container: Strictly prefer the container aspect ratio. This is apparently
+                the default behavior with VLC, at least with Matroska. Note that
+                if the container has no aspect ratio set, the behavior is the
+                same as with bitstream.
+    :bitstream: Strictly prefer the bitstream aspect ratio, unless the bitstream
+                aspect ratio is not set. This is apparently the default behavior
+                with XBMC/kodi, at least with Matroska.
+
+    The current default for mpv is ``container``.
+
+    Normally you should not set this. Try the various choices if you encounter
+    video that has the wrong aspect ratio in mpv, but seems to be correct in
+    other players.
+
+``--video-unscaled=<no|yes|downscale-big>``
+    Disable scaling of the video. If the window is larger than the video,
+    black bars are added. Otherwise, the video is cropped, unless the option
+    is set to ``downscale-big``, in which case the video is fit to window. The
+    video still can be influenced by the other ``--video-...`` options. This
+    option disables the effect of ``--panscan``.
+
+    Note that the scaler algorithm may still be used, even if the video isn't
+    scaled. For example, this can influence chroma conversion. The video will
+    also still be scaled in one dimension if the source uses non-square pixels
+    (e.g. anamorphic widescreen DVDs).
+
+    This option is disabled if the ``--no-keepaspect`` option is used.
+
+``--video-pan-x=<value>``, ``--video-pan-y=<value>``
+    Moves the displayed video rectangle by the given value in the X or Y
+    direction. The unit is in fractions of the size of the scaled video (the
+    full size, even if parts of the video are not visible due to panscan or
+    other options).
+
+    For example, displaying a video fullscreen on a 1920x1080 screen with
+    ``--video-pan-x=-0.1`` would move the video 192 pixels to the left and
+    ``--video-pan-y=-0.1`` would move the video 108 pixels up.
+
+    This option is disabled if the ``--no-keepaspect`` option is used.
+
+``--video-rotate=<0-359|no>``
+    Rotate the video clockwise, in degrees. If ``no`` is given, the video is
+    never rotated, even if the file has rotation metadata. (The rotation value
+    is added to the rotation metadata, which means the value ``0`` would rotate
+    the video according to the rotation metadata.)
+
+    When using hardware decoding without copy-back, only 90° steps work, while
+    software decoding and hardware decoding methods that copy the video back to
+    system memory support all values between 0 and 359.
+
+``--video-crop=<[W[xH]][+x+y]>``, ``--video-crop=<x:y>``
+    Crop the video by starting at the x, y offset for w, h pixels. The crop is
+    applied to the source video rectangle (before anamorphic stretch) by the VO.
+    A crop rectangle that is not within the video rectangle will be ignored.
+    This works with hwdec, unlike the equivalent 'lavfi-crop'. When offset is
+    omitted, the central area will be cropped. Setting the crop to empty one
+    ``--video-crop=0x0+0+0`` overrides container crop and disables cropping.
+    Setting the crop to ``--video-crop=""`` disables manual cropping and restores
+    the container crop if it's specified.
+
+``--video-zoom=<value>``
+    Adjust the video display scale factor by the given value. The parameter is
+    given log 2. For example, ``--video-zoom=0`` is unscaled,
+    ``--video-zoom=1`` is twice the size, ``--video-zoom=-2`` is one fourth of
+    the size, and so on.
+
+    This option is disabled if the ``--no-keepaspect`` option is used.
+
+``--video-scale-x=<value>``, ``--video-scale-y=<value>``
+    Multiply the video display size with the given value (default: 1.0). If a
+    non-default value is used, this will be different from the window size, so
+    video will be either cut off, or black bars are added.
+
+    This value is multiplied with the value derived from ``--video-zoom`` and
+    the normal video aspect ratio. This option is disabled if the
+    ``--no-keepaspect`` option is used.
+
+``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>``
+    Moves the video rectangle within the black borders, which are usually added
+    to pad the video to screen if video and screen aspect ratios are different.
+    ``--video-align-y=-1`` would move the video to the top of the screen
+    (leaving a border only on the bottom), a value of ``0`` centers it
+    (default), and a value of ``1`` would put the video at the bottom of the
+    screen.
+
+    If video and screen aspect match perfectly, these options do nothing.
+
+    This option is disabled if the ``--no-keepaspect`` option is used.
+
+``--video-margin-ratio-left=<val>``, ``--video-margin-ratio-right=<val>``, ``--video-margin-ratio-top=<val>``, ``--video-margin-ratio-bottom=<val>``
+    Set extra video margins on each border (default: 0). Each value is a ratio
+    of the window size, using a range 0.0-1.0. For example, setting the option
+    ``--video-margin-ratio-right=0.2`` at a window size of 1000 pixels will add
+    a 200 pixels border on the right side of the window.
+
+    The video is "boxed" by these margins. The window size is not changed. In
+    particular it does not enlarge the window, and the margins will cause the
+    video to be downscaled by default. This may or may not change in the future.
+
+    The margins are applied after 90° video rotation, but before any other video
+    transformations.
+
+    This option is disabled if the ``--no-keepaspect`` option is used.
+
+    Subtitles still may use the margins, depending on ``--sub-use-margins`` and
+    similar options.
+
+    These options were created for the OSC. Some odd decisions, such as making
+    the margin values a ratio (instead of pixels), were made for the sake of
+    the OSC. It's possible that these options may be replaced by ones that are
+    more generally useful. The behavior of these options may change to fit
+    OSC requirements better, too.
+
+``--correct-pts``, ``--no-correct-pts``
+    ``--no-correct-pts`` switches mpv to a mode where video timing is
+    determined using a fixed framerate value (either using the
+    ``--container-fps-override`` option, or using file information). Sometimes,
+    files with very broken timestamps can be played somewhat well in this mode.
+    Note that video filters, subtitle rendering, seeking (including hr-seeks and
+    backstepping), and audio synchronization can be completely broken in this mode.
+
+``--container-fps-override=<float>``
+    Override video framerate. Useful if the original value is wrong or missing.
+
+    .. note::
+
+        Works in ``--no-correct-pts`` mode only.
+
+``--deinterlace=<yes|no>``
+    Enable or disable interlacing (default: no).
+    Interlaced video shows ugly comb-like artifacts, which are visible on
+    fast movement. Enabling this typically inserts the yadif video filter in
+    order to deinterlace the video, or lets the video output apply deinterlacing
+    if supported.
+
+    This behaves exactly like the ``deinterlace`` input property (usually
+    mapped to ``d``).
+
+    Keep in mind that this **will** conflict with manually inserted
+    deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the
+    hardware deinterlace filters will conflict. Also since that version,
+    ``--deinterlace=auto`` was removed, which used to mean that the default
+    interlacing option of possibly inserted video filters was used.)
+
+    Note that this will make video look worse if it's not actually interlaced.
+
+``--frames=<number>``
+    Play/convert only first ``<number>`` video frames, then quit.
+
+    ``--frames=0`` loads the file, but immediately quits before initializing
+    playback. (Might be useful for scripts which just want to determine some
+    file properties.)
+
+    For audio-only playback, any value greater than 0 will quit playback
+    immediately after initialization. The value 0 works as with video.
+
+``--video-output-levels=<outputlevels>``
+    RGB color levels used with YUV to RGB conversion. Normally, output devices
+    such as PC monitors use full range color levels. However, some TVs and
+    video monitors expect studio RGB levels. Providing full range output to a
+    device expecting studio level input results in crushed blacks and whites,
+    the reverse in dim gray blacks and dim whites.
+
+    Not all VOs support this option. Some will silently ignore it.
+
+    Available color ranges are:
+
+    :auto:      automatic selection (equals to full range) (default)
+    :limited:   limited range (16-235 per component), studio levels
+    :full:      full range (0-255 per component), PC levels
+
+    .. note::
+
+        It is advisable to use your graphics driver's color range option
+        instead, if available.
+
+``--hwdec-codecs=<codec1,codec2,...|all>``
+    Allow hardware decoding for a given list of codecs only. The special value
+    ``all`` always allows all codecs.
+
+    You can get the list of allowed codecs with ``mpv --vd=help``. Remove the
+    prefix, e.g. instead of ``lavc:h264`` use ``h264``.
+
+    By default, this is set to ``h264,vc1,hevc,vp8,vp9,av1``. Note that
+    the hardware acceleration special codecs like ``h264_vdpau`` are not
+    relevant anymore, and in fact have been removed from Libav in this form.
+
+    This is usually only needed with broken GPUs, where a codec is reported
+    as supported, but decoding causes more problems than it solves.
+
+    .. admonition:: Example
+
+        ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video``
+            Enable vdpau decoding for h264 and mpeg2 only.
+
+``--vd-lavc-check-hw-profile=<yes|no>``
+    Check hardware decoder profile (default: yes). If ``no`` is set, the
+    highest profile of the hardware decoder is unconditionally selected, and
+    decoding is forced even if the profile of the video is higher than that.
+    The result is most likely broken decoding, but may also help if the
+    detected or reported profiles are somehow incorrect.
+
+``--vd-lavc-software-fallback=<yes|no|N>``
+    Fallback to software decoding if the hardware-accelerated decoder fails
+    (default: 3). If this is a number, then fallback will be triggered if
+    N frames fail to decode in a row. 1 is equivalent to ``yes``.
+
+    Setting this to a higher number might break the playback start fallback: if
+    a fallback happens, parts of the file will be skipped, approximately by to
+    the number of packets that could not be decoded. Values below an unspecified
+    count will not have this problem, because mpv retains the packets.
+
+``--vd-lavc-film-grain=<auto|cpu|gpu>``
+    Enables film grain application on the GPU. If video decoding is done on
+    the CPU, doing film grain application on the GPU can speed up decoding.
+    This option can also help hardware decoding, as it can reduce the number
+    of frame copies done.
+
+    By default, it's set to ``auto``, so if the VO supports film grain
+    application, then it will be treated as ``gpu``. If the VO does not
+    support this, then it will be treated as ``cpu``, regardless of the setting.
+    Currently, only ``gpu-next`` supports film grain application.
+
+``--vd-lavc-dr=<auto|yes|no>``
+    Enable direct rendering (default: auto). If this is set to ``yes``, the
+    video will be decoded directly to GPU video memory (or staging buffers).
+    This can speed up video upload, and may help with large resolutions or
+    slow hardware. This works only with the following VOs:
+
+        - ``gpu``: requires at least OpenGL 4.4 or Vulkan.
+        - ``libmpv``: The libmpv render API has optional support.
+
+    The ``auto`` option will try to guess whether DR can improve performance
+    on your particular hardware. Currently this enables it on AMD or NVIDIA
+    if using OpenGL or unconditionally if using Vulkan.
+
+    Using video filters of any kind that write to the image data (or output
+    newly allocated frames) will silently disable the DR code path.
+
+``--vd-lavc-bitexact``
+    Only use bit-exact algorithms in all decoding steps (for codec testing).
+
+``--vd-lavc-fast`` (MPEG-1/2 and H.264 only)
+    Enable optimizations which do not comply with the format specification and
+    potentially cause problems, like simpler dequantization, simpler motion
+    compensation, assuming use of the default quantization matrix, assuming YUV
+    4:2:0 and skipping a few checks to detect damaged bitstreams.
+
+``--vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]``
+    Pass AVOptions to libavcodec decoder. Note, a patch to make the ``o=``
+    unneeded and pass all unknown options through the AVOption system is
+    welcome. A full list of AVOptions can be found in the FFmpeg manual.
+
+    Some options which used to be direct options can be set with this
+    mechanism, like ``bug``, ``gray``, ``idct``, ``ec``, ``vismv``,
+    ``skip_top`` (was ``st``), ``skip_bottom`` (was ``sb``), ``debug``.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        ``--vd-lavc-o=debug=pict``
+
+``--vd-lavc-show-all=<yes|no>``
+    Show even broken/corrupt frames (default: no). If this option is set to
+    no, libavcodec won't output frames that were either decoded before an
+    initial keyframe was decoded, or frames that are recognized as corrupted.
+
+``--vd-lavc-skiploopfilter=<skipvalue>`` (H.264, HEVC only)
+    Skips the loop filter (AKA deblocking) during decoding. Since
+    the filtered frame is supposed to be used as reference for decoding
+    dependent frames, this has a worse effect on quality than not doing
+    deblocking on e.g. MPEG-2 video. But at least for high bitrate HDTV,
+    this provides a big speedup with little visible quality loss.
+    Codecs other than H.264 or HEVC may have partial support for this option
+    (often only ``all`` and ``none``).
+
+    ``<skipvalue>`` can be one of the following:
+
+    :none:    Never skip.
+    :default: Skip useless processing steps (e.g. 0 size packets in AVI).
+    :nonref:  Skip frames that are not referenced (i.e. not used for
+              decoding other frames, the error cannot "build up").
+    :bidir:   Skip B-Frames.
+    :nonkey:  Skip all frames except keyframes.
+    :all:     Skip all frames.
+
+``--vd-lavc-skipidct=<skipvalue>`` (MPEG-1/2/4 only)
+    Skips the IDCT step. This degrades quality a lot in almost all cases
+    (see skiploopfilter for available skip values).
+
+``--vd-lavc-skipframe=<skipvalue>``
+    Skips decoding of frames completely. Big speedup, but jerky motion and
+    sometimes bad artifacts (see skiploopfilter for available skip values).
+
+``--vd-lavc-framedrop=<skipvalue>``
+    Set framedropping mode used with ``--framedrop`` (see skiploopfilter for
+    available skip values).
+
+``--vd-lavc-threads=<N>``
+    Number of threads to use for decoding. Whether threading is actually
+    supported depends on codec (default: 0). 0 means autodetect number of cores
+    on the machine and use that, up to the maximum of 16. You can set more than
+    16 threads manually.
+
+``--vd-lavc-assume-old-x264=<yes|no>``
+    Assume the video was encoded by an old, buggy x264 version (default: no).
+    Normally, this is autodetected by libavcodec. But if the bitstream contains
+    no x264 version info (or it was somehow skipped), and the stream was in fact
+    encoded by an old x264 version (build 150 or earlier), and if the stream
+    uses 4:4:4 chroma, then libavcodec will by default show corrupted video.
+    This option sets the libavcodec ``x264_build`` option to ``150``, which
+    means that if the stream contains no version info, or was not encoded by
+    x264 at all, it assumes it was encoded by the old version. Enabling this
+    option is pretty safe if you want your broken files to work, but in theory
+    this can break on streams not encoded by x264, or if a stream encoded by a
+    newer x264 version contains no version info.
+
+``--vd-apply-cropping``
+    Certain video codecs support cropping, meaning that only a sub-rectangle of
+    the decoded frame is intended for display. This option controls how cropping
+    is handled by libavcodec. Cropping during decoding has certain limitations
+    with regards to alignment and hardware decoding. If this option is enabled,
+    decoder will apply the crop, else VO will handle it. Enabled by default.
+
+``--swapchain-depth=<N>``
+    Allow up to N in-flight frames. This essentially controls the frame
+    latency. Increasing the swapchain depth can improve pipelining and prevent
+    missed vsyncs, but increases visible latency. This option only mandates an
+    upper limit, the implementation can use a lower latency than requested
+    internally. A setting of 1 means that the VO will wait for every frame to
+    become visible before starting to render the next frame. (Default: 3)
+
+Audio
+-----
+
+``--audio-pitch-correction=<yes|no>``
+    If this is enabled (default), playing with a speed different from normal
+    automatically inserts the ``scaletempo2`` audio filter. You can insert
+    filters besides ``scaletempo2`` and modify their params using
+    `Conditional auto profiles`:
+
+    ::
+
+        [af_insert]
+        profile-cond=speed ~= 1
+        profile-restore=copy
+        af-add=scaletempo2=search-interval=50 # Insert filter and params here.
+
+    Filters set this way replace the ``scaletempo2`` default, instead of
+    overlapping with it. If there are multiple audio filters inserted that can do
+    pitch correction, then only the last one in the filter chain is used.
+    For details on the specifics of each available filter, see the audio filter
+    section.
+
+``--audio-device=<name>``
+    Use the given audio device. This consists of the audio output name, e.g.
+    ``alsa``, followed by ``/``, followed by the audio output specific device
+    name. The default value for this option is ``auto``, which tries every audio
+    output in preference order with the default device.
+
+    You can list audio devices with ``--audio-device=help``. This outputs the
+    device name in quotes, followed by a description. The device name is what
+    you have to pass to the ``--audio-device`` option. The list of audio devices
+    can be retrieved by API by using the ``audio-device-list`` property.
+
+    While the option normally takes one of the strings as indicated by the
+    methods above, you can also force the device for most AOs by building it
+    manually. For example ``name/foobar`` forces the AO ``name`` to use the
+    device ``foobar``. However, the ``--ao`` option will strictly force a
+    specific AO. To avoid confusion, don't use ``--ao`` and ``--audio-device``
+    together.
+
+    .. admonition:: Example for ALSA
+
+        MPlayer and mplayer2 required you to replace any ',' with '.' and
+        any ':' with '=' in the ALSA device name. For example, to use the
+        device named ``dmix:default``, you had to do:
+
+            ``-ao alsa:device=dmix=default``
+
+        In mpv you could instead use:
+
+            ``--audio-device=alsa/dmix:default``
+
+
+``--audio-exclusive=<yes|no>``
+    Enable exclusive output mode. In this mode, the system is usually locked
+    out, and only mpv will be able to output audio.
+
+    This only works for some audio outputs, such as ``wasapi``, ``coreaudio``
+    and ``pipewire``. Other audio outputs silently ignore this option.
+    They either have no concept of exclusive mode, or the mpv side of the
+    implementation is missing.
+
+``--audio-fallback-to-null=<yes|no>``
+    If no audio device can be opened, behave as if ``--ao=null`` was given. This
+    is useful in combination with ``--audio-device``: instead of causing an
+    error if the selected device does not exist, the client API user (or a
+    Lua script) could let playback continue normally, and check the
+    ``current-ao`` and ``audio-device-list`` properties to make high-level
+    decisions about how to continue.
+
+``--ao=<driver>``
+    Specify the audio output drivers to be used. See `AUDIO OUTPUT DRIVERS`_ for
+    details and descriptions of available drivers.
+
+``--af=<filter1[=parameter1:parameter2:...],filter2,...>``
+    Specify a list of audio filters to apply to the audio stream. See
+    `AUDIO FILTERS`_ for details and descriptions of the available filters.
+    The option variants ``--af-add``, ``--af-pre``, and ``--af-clr`` exist
+    to modify a previously specified list, but you should not need these for
+    typical use.
+
+``--audio-spdif=<codecs>``
+    List of codecs for which compressed audio passthrough should be used. This
+    works for both classic S/PDIF and HDMI.
+
+    Possible codecs are ``ac3``, ``dts``, ``dts-hd``, ``eac3``, ``truehd``.
+    Multiple codecs can be specified by separating them with ``,``. ``dts``
+    refers to low bitrate DTS core, while ``dts-hd`` refers to DTS MA (receiver
+    and OS support varies). If both ``dts`` and ``dts-hd`` are specified, it
+    behaves equivalent to specifying ``dts-hd`` only.
+
+    In earlier mpv versions you could use ``--ad`` to force the spdif wrapper.
+    This does not work anymore.
+
+    .. admonition:: Warning
+
+        There is not much reason to use this. HDMI supports uncompressed
+        multichannel PCM, and mpv supports lossless DTS-HD decoding via
+        FFmpeg's new DCA decoder (based on libdcadec).
+
+``--ad=<decoder1,decoder2,...[-]>``
+    Specify a priority list of audio decoders to be used, according to their
+    decoder name. When determining which decoder to use, the first decoder that
+    matches the audio format is selected. If that is unavailable, the next
+    decoder is used. Finally, it tries all other decoders that are not
+    explicitly selected or rejected by the option.
+
+    ``-`` at the end of the list suppresses fallback on other available
+    decoders not on the ``--ad`` list. ``+`` in front of an entry forces the
+    decoder. Both of these should not normally be used, because they break
+    normal decoder auto-selection! Both of these methods are deprecated.
+
+    .. admonition:: Examples
+
+        ``--ad=mp3float``
+            Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3
+            decoders.
+
+        ``--ad=help``
+            List all available decoders.
+
+    .. admonition:: Warning
+
+        Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with
+        this option is not possible. Use ``--audio-spdif`` instead.
+
+``--volume=<value>``
+    Set the startup volume. 0 means silence, 100 means no volume reduction or
+    amplification. Negative values can be passed for compatibility, but are
+    treated as 0.
+
+    Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
+
+``--replaygain=<no|track|album>``
+    Adjust volume gain according to replaygain values stored in the file
+    metadata. With ``--replaygain=no`` (the default), perform no adjustment.
+    With ``--replaygain=track``, apply track gain. With ``--replaygain=album``,
+    apply album gain if present and fall back to track gain otherwise.
+
+``--replaygain-preamp=<db>``
+    Pre-amplification gain in dB to apply to the selected replaygain gain
+    (default: 0).
+
+``--replaygain-clip=<yes|no>``
+    Prevent clipping caused by replaygain by automatically lowering the
+    gain (default). Use ``--replaygain-clip=no`` to disable this.
+
+``--replaygain-fallback=<db>``
+    Gain in dB to apply if the file has no replay gain tags. This option
+    is always applied if the replaygain logic is somehow inactive. If this
+    is applied, no other replaygain options are applied.
+
+``--audio-delay=<sec>``
+    Audio delay in seconds (positive or negative float value). Positive values
+    delay the audio, and negative values delay the video.
+
+``--mute=<yes|no|auto>``
+    Set startup audio mute status (default: no).
+
+    ``auto`` is a deprecated possible value that is equivalent to ``no``.
+
+    See also: ``--volume``.
+
+``--softvol=<no|yes|auto>``
+    Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether
+    to use the volume controls of the audio output driver or the internal mpv
+    volume filter.
+
+    The current behavior is that softvol is always enabled, i.e. as if this
+    option is set to ``yes``. The other behaviors are not available anymore,
+    although ``auto`` almost matches current behavior in most cases.
+
+    The ``no`` behavior is still partially available through the ``ao-volume``
+    and ``ao-mute`` properties. But there are no options to reset these.
+
+``--audio-demuxer=<[+]name>``
+    Use this audio demuxer type when using ``--audio-file``. Use a '+' before
+    the name to force it; this will skip some checks. Give the demuxer name as
+    printed by ``--audio-demuxer=help``.
+
+``--ad-lavc-ac3drc=<level>``
+    Select the Dynamic Range Compression level for AC-3 audio streams.
+    ``<level>`` is a float value ranging from 0 to 1, where 0 means no
+    compression (which is the default) and 1 means full compression (make loud
+    passages more silent and vice versa). Values up to 6 are also accepted, but
+    are purely experimental. This option only shows an effect if the AC-3 stream
+    contains the required range compression information.
+
+    The standard mandates that DRC is enabled by default, but mpv (and some
+    other players) ignore this for the sake of better audio quality.
+
+``--ad-lavc-downmix=<yes|no>``
+    Whether to request audio channel downmixing from the decoder (default: no).
+    Some decoders, like AC-3, AAC and DTS, can remix audio on decoding. The
+    requested number of output channels is set with the ``--audio-channels`` option.
+    Useful for playing surround audio on a stereo system.
+
+``--ad-lavc-threads=<0-16>``
+    Number of threads to use for decoding. Whether threading is actually
+    supported depends on codec. As of this writing, it's supported for some
+    lossless codecs only. 0 means autodetect number of cores on the
+    machine and use that, up to the maximum of 16 (default: 1).
+
+``--ad-lavc-o=<key>=<value>[,<key>=<value>[,...]]``
+    Pass AVOptions to libavcodec decoder. Note, a patch to make the o=
+    unneeded and pass all unknown options through the AVOption system is
+    welcome. A full list of AVOptions can be found in the FFmpeg manual.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd``
+    If DTS is passed through, use DTS-HD.
+
+    .. admonition:: Warning
+
+        This and enabling passthrough via ``--ad`` are deprecated in favor of
+        using ``--audio-spdif=dts-hd``.
+
+``--audio-channels=<auto-safe|auto|layouts>``
+    Control which audio channels are output (e.g. surround vs. stereo). There
+    are the following possibilities:
+
+    - ``--audio-channels=auto-safe``
+        Use the system's preferred channel layout. If there is none (such
+        as when accessing a hardware device instead of the system mixer),
+        force stereo. Some audio outputs might simply accept any layout and
+        do downmixing on their own.
+
+        This is the default.
+    - ``--audio-channels=auto``
+        Send the audio device whatever it accepts, preferring the audio's
+        original channel layout. Can cause issues with HDMI (see the warning
+        below).
+    - ``--audio-channels=layout1,layout2,...``
+        List of ``,``-separated channel layouts which should be allowed.
+        Technically, this only adjusts the filter chain output to the best
+        matching layout in the list, and passes the result to the audio API.
+        It's possible that the audio API will select a different channel
+        layout.
+
+        Using this mode is recommended for direct hardware output, especially
+        over HDMI (see HDMI warning below).
+    - ``--audio-channels=<stereo|mono>``
+        Force a downmix to stereo or mono. These are special-cases of the
+        previous item. (See paragraphs below for implications.)
+
+    If a list of layouts is given, each item can be either an explicit channel
+    layout name (like ``5.1``), or a channel number. Channel numbers refer to
+    default layouts, e.g. 2 channels refer to stereo, 6 refers to 5.1.
+
+    See ``--audio-channels=help`` output for defined default layouts. This also
+    lists speaker names, which can be used to express arbitrary channel
+    layouts (e.g. ``fl-fr-lfe`` is 2.1).
+
+    If the list of channel layouts has only 1 item, the decoder is asked to
+    produce according output. This sometimes triggers decoder-downmix, which
+    might be different from the normal mpv downmix. (Only some decoders support
+    remixing audio, like AC-3, AAC or DTS. You can use ``--ad-lavc-downmix=no``
+    to make the decoder always output its native layout.) One consequence is
+    that ``--audio-channels=stereo`` triggers decoder downmix, while ``auto``
+    or ``auto-safe`` never will, even if they end up selecting stereo. This
+    happens because the decision whether to use decoder downmix happens long
+    before the audio device is opened.
+
+    If the channel layout of the media file (i.e. the decoder) and the AO's
+    channel layout don't match, mpv will attempt to insert a conversion filter.
+    You may need to change the channel layout of the system mixer to achieve
+    your desired output as mpv does not have control over it. Another
+    work-around for this on some AOs is to use ``--audio-exclusive=yes`` to
+    circumvent the system mixer entirely.
+
+    .. admonition:: Warning
+
+        Using ``auto`` can cause issues when using audio over HDMI. The OS will
+        typically report all channel layouts that _can_ go over HDMI, even if
+        the receiver does not support them. If a receiver gets an unsupported
+        channel layout, random things can happen, such as dropping the
+        additional channels, or adding noise.
+
+        You are recommended to set an explicit whitelist of the layouts you
+        want. For example, most A/V receivers connected via HDMI and that can
+        do 7.1 would  be served by: ``--audio-channels=7.1,5.1,stereo``
+
+``--audio-display=<no|embedded-first|external-first>``
+    Determines whether to display cover art when playing audio files and with
+    what priority. It will display the first image found, and additional images
+    are available as video tracks.
+
+    :no:             Disable display of video entirely when playing audio
+                     files.
+    :embedded-first: Display embedded images and external cover art, giving
+                     priority to embedded images (default).
+    :external-first: Display embedded images and external cover art, giving
+                     priority to external files.
+
+    This option has no influence on files with normal video tracks.
+
+``--audio-files=<files>``
+    Play audio from an external file while viewing a video.
+
+    This is a path list option. See `List Options`_ for details.
+
+``--audio-file=<file>``
+    CLI/config file only alias for ``--audio-files-append``. Each use of this
+    option will add a new audio track. The details are similar to how
+    ``--sub-file`` works.
+
+``--audio-format=<format>``
+    Select the sample format used for output from the audio filter layer to
+    the sound card. The values that ``<format>`` can adopt are listed below in
+    the description of the ``format`` audio filter.
+
+``--audio-samplerate=<Hz>``
+    Select the output sample rate to be used (of course sound cards have
+    limits on this). If the sample frequency selected is different from that
+    of the current media, the lavrresample audio filter will be inserted into
+    the audio filter layer to compensate for the difference.
+
+``--gapless-audio=<no|yes|weak>``
+    Try to play consecutive audio files with no silence or disruption at the
+    point of file change. Default: ``weak``.
+
+    :no:    Disable gapless audio.
+    :yes:   The audio device is opened using parameters chosen for the first
+            file played and is then kept open for gapless playback. This
+            means that if the first file for example has a low sample rate, then
+            the following files may get resampled to the same low sample rate,
+            resulting in reduced sound quality. If you play files with different
+            parameters, consider using options such as ``--audio-samplerate``
+            and ``--audio-format`` to explicitly select what the shared output
+            format will be.
+    :weak:  Normally, the audio device is kept open (using the format it was
+            first initialized with). If the audio format the decoder output
+            changes, the audio device is closed and reopened. This means that
+            you will normally get gapless audio with files that were encoded
+            using the same settings, but might not be gapless in other cases.
+            The exact conditions under which the audio device is kept open is
+            an implementation detail, and can change from version to version.
+            Currently, the device is kept even if the sample format changes,
+            but the sample formats are convertible.
+            If video is still going on when there is still audio, trying to use
+            gapless is also explicitly given up.
+
+    .. note::
+
+        This feature is implemented in a simple manner and relies on audio
+        output device buffering to continue playback while moving from one file
+        to another. If playback of the new file starts slowly, for example
+        because it is played from a remote network location or because you have
+        specified cache settings that require time for the initial cache fill,
+        then the buffered audio may run out before playback of the new file
+        can start.
+
+``--initial-audio-sync``, ``--no-initial-audio-sync``
+    When starting a video file or after events such as seeking, mpv will by
+    default modify the audio stream to make it start from the same timestamp
+    as video, by either inserting silence at the start or cutting away the
+    first samples. Disabling this option makes the player behave like older
+    mpv versions did: video and audio are both started immediately even if
+    their start timestamps differ, and then video timing is gradually adjusted
+    if necessary to reach correct synchronization later.
+
+``--volume-max=<100.0-1000.0>``
+    Set the maximum amplification level in percent (default: 130). A value of
+    130 will allow you to adjust the volume up to about double the normal level.
+
+``--audio-file-auto=<no|exact|fuzzy|all>``, ``--no-audio-file-auto``
+    Load additional audio files matching the video filename. The parameter
+    specifies how external audio files are matched.
+
+    :no:    Don't automatically load external audio files (default).
+    :exact: Load the media filename with audio file extension.
+    :fuzzy: Load all audio files containing the media filename.
+    :all:   Load all audio files in the current and ``--audio-file-paths``
+            directories.
+
+``--audio-file-auto-exts=ext1,ext2,...``
+    Audio file extentions to try and match when using ``audio-file-auto``.
+
+    This is a string list option. See `List Options`_ for details.
+
+``--audio-file-paths=<path1:path2:...>``
+    Equivalent to ``--sub-file-paths`` option, but for auto-loaded audio files.
+
+    This is a path list option. See `List Options`_ for details.
+
+``--audio-client-name=<name>``
+    The application name the player reports to the audio API. Can be useful
+    if you want to force a different audio profile (e.g. with PulseAudio),
+    or to set your own application name when using libmpv.
+
+``--audio-buffer=<seconds>``
+    Set the audio output minimum buffer. The audio device might actually create
+    a larger buffer if it pleases. If the device creates a smaller buffer,
+    additional audio is buffered in an additional software buffer.
+
+    Making this larger will make soft-volume and other filters react slower,
+    introduce additional issues on playback speed change, and block the
+    player on audio format changes. A smaller buffer might lead to audio
+    dropouts.
+
+    This option should be used for testing only. If a non-default value helps
+    significantly, the mpv developers should be contacted.
+
+    Default: 0.2 (200 ms).
+
+``--audio-stream-silence=<yes|no>``
+    Cash-grab consumer audio hardware (such as A/V receivers) often ignore
+    initial audio sent over HDMI. This can happen every time audio over HDMI
+    is stopped and resumed. In order to compensate for this, you can enable
+    this option to not to stop and restart audio on seeks, and fill the gaps
+    with silence. Likewise, when pausing playback, audio is not stopped, and
+    silence is played while paused. Note that if no audio track is selected,
+    the audio device will still be closed immediately.
+
+    Not all AOs support this.
+
+    .. admonition:: Warning
+
+        This modifies certain subtle player behavior, like A/V-sync and underrun
+        handling. Enabling this option is strongly discouraged.
+
+``--audio-wait-open=<secs>``
+    This makes sense for use with ``--audio-stream-silence=yes``. If this option
+    is given, the player will wait for the given amount of seconds after opening
+    the audio device before sending actual audio data to it. Useful if your
+    expensive hardware discards the first 1 or 2 seconds of audio data sent to
+    it. If ``--audio-stream-silence=yes`` is not set, this option will likely
+    just waste time.
+
+Subtitles
+---------
+
+.. note::
+
+    Changing styling and position does not work with all subtitles. Image-based
+    subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons.
+    Subtitles in ASS format are normally not changed intentionally, but
+    overriding them can be controlled with ``--sub-ass-override``.
+
+``--sub-demuxer=<[+]name>``
+    Force subtitle demuxer type for ``--sub-file``. Give the demuxer name as
+    printed by ``--sub-demuxer=help``.
+
+``--sub-delay=<sec>``
+    Delays subtitles by ``<sec>`` seconds. Can be negative.
+
+``--sub-files=<file-list>``, ``--sub-file=<filename>``
+    Add a subtitle file to the list of external subtitles.
+
+    If you use ``--sub-file`` only once, this subtitle file is displayed by
+    default.
+
+    If ``--sub-file`` is used multiple times, the subtitle to use can be
+    switched at runtime by cycling subtitle tracks. It's possible to show
+    two subtitles at once: use ``--sid`` to select the first subtitle index,
+    and ``--secondary-sid`` to select the second index. (The index is printed
+    on the terminal output after the ``--sid=`` in the list of streams.)
+
+    ``--sub-files`` is a path list option (see `List Options`_  for details), and
+    can take multiple file names separated by ``:`` (Unix) or ``;`` (Windows),
+    while  ``--sub-file`` takes a single filename, but can be used multiple
+    times to add multiple files. Technically, ``--sub-file`` is a CLI/config
+    file only alias for  ``--sub-files-append``.
+
+``--secondary-sid=<ID|auto|no>``
+    Select a secondary subtitle stream. This is similar to ``--sid``. If a
+    secondary subtitle is selected, it will be rendered as toptitle (i.e. on
+    the top of the screen) alongside the normal subtitle, and provides a way
+    to render two subtitles at once.
+
+    There are some caveats associated with this feature. For example, bitmap
+    subtitles will always be rendered in their usual position, so selecting a
+    bitmap subtitle as secondary subtitle will result in overlapping subtitles.
+    Secondary subtitles are never shown on the terminal if video is disabled.
+
+    .. note::
+
+        Styling and interpretation of any formatting tags is disabled for the
+        secondary subtitle. Internally, the same mechanism as ``--no-sub-ass``
+        is used to strip the styling.
+
+    .. note::
+
+        If the main subtitle stream contains formatting tags which display the
+        subtitle at the top of the screen, it will overlap with the secondary
+        subtitle. To prevent this, you could use ``--no-sub-ass`` to disable
+        styling in the main subtitle stream.
+
+``--sub-scale=<0-100>``
+    Factor for the text subtitle font size (default: 1).
+
+    .. note::
+
+        This affects ASS subtitles as well, and may lead to incorrect subtitle
+        rendering. Use with care, or use ``--sub-font-size`` instead.
+
+``--sub-scale-by-window=<yes|no>``
+    Whether to scale subtitles with the window size (default: yes). If this is
+    disabled, changing the window size won't change the subtitle font size.
+
+    Like ``--sub-scale``, this can break ASS subtitles.
+
+``--sub-scale-with-window=<yes|no>``
+    Make the subtitle font size relative to the window, instead of the video.
+    This is useful if you always want the same font size, even if the video
+    doesn't cover the window fully, e.g. because screen aspect and window
+    aspect mismatch (and the player adds black bars).
+
+    Default: yes.
+
+    This option is misnamed. The difference to the confusingly similar sounding
+    option ``--sub-scale-by-window`` is that ``--sub-scale-with-window`` still
+    scales with the approximate window size, while the other option disables
+    this scaling.
+
+    Affects plain text subtitles only (or ASS if ``--sub-ass-override`` is set
+    high enough).
+
+``--sub-ass-scale-with-window=<yes|no>``
+    Like ``--sub-scale-with-window``, but affects subtitles in ASS format only.
+    Like ``--sub-scale``, this can break ASS subtitles.
+
+    Default: no.
+
+``--embeddedfonts=<yes|no>``
+    Use fonts embedded in Matroska container files and ASS scripts (default:
+    yes). These fonts can be used for SSA/ASS subtitle rendering.
+
+``--sub-pos=<0-150>``
+    Specify the position of subtitles on the screen. The value is the vertical
+    position of the subtitle in % of the screen height. 100 is the original
+    position, which is often not the absolute bottom of the screen, but with
+    some margin between the bottom and the subtitle. Values above 100 move the
+    subtitle further down.
+
+    .. admonition:: Warning
+
+        Text subtitles (as opposed to image subtitles) may be cut off if the
+        value of the option is above 100. This is a libass restriction.
+
+        This affects ASS subtitles as well, and may lead to incorrect subtitle
+        rendering in addition to the problem above.
+
+        Using ``--sub-margin-y`` can achieve this in a better way.
+
+``--sub-speed=<0.1-10.0>``
+    Multiply the subtitle event timestamps with the given value. Can be used
+    to fix the playback speed for frame-based subtitle formats. Affects text
+    subtitles only.
+
+    .. admonition:: Example
+
+        ``--sub-speed=25/23.976`` plays frame based subtitles which have been
+        loaded assuming a framerate of 23.976 at 25 FPS.
+
+``--sub-ass-style-overrides=<[Style.]Param=Value[,...]>``
+    Override some style or script info parameters.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``--sub-ass-style-overrides=FontName=Arial,Default.Bold=1``
+        - ``--sub-ass-style-overrides=PlayResY=768``
+
+    .. note::
+
+        Using this option may lead to incorrect subtitle rendering.
+
+``--sub-ass-hinting=<none|light|normal|native>``
+    Set font hinting type. <type> can be:
+
+    :none:       no hinting (default)
+    :light:      FreeType autohinter, light mode
+    :normal:     FreeType autohinter, normal mode
+    :native:     font native hinter
+
+    .. admonition:: Warning
+
+        Enabling hinting can lead to mispositioned text (in situations it's
+        supposed to match up video background), or reduce the smoothness
+        of animations with some badly authored ASS scripts. It is recommended
+        to not use this option, unless really needed.
+
+``--sub-ass-line-spacing=<value>``
+    Set line spacing value for SSA/ASS renderer.
+
+``--sub-ass-shaper=<simple|complex>``
+    Set the text layout engine used by libass.
+
+    :simple:   uses Fribidi only, fast, doesn't render some languages correctly
+    :complex:  uses HarfBuzz, slower, wider language support
+
+    ``complex`` is the default. If libass hasn't been compiled against HarfBuzz,
+    libass silently reverts to ``simple``.
+
+``--sub-ass-styles=<filename>``
+    Load all SSA/ASS styles found in the specified file and use them for
+    rendering text subtitles. The syntax of the file is exactly like the ``[V4
+    Styles]`` / ``[V4+ Styles]`` section of SSA/ASS.
+
+    .. note::
+
+        Using this option may lead to incorrect subtitle rendering.
+
+``--sub-ass-override=<yes|no|force|scale|strip>``
+    Control whether user style overrides should be applied. Note that all of
+    these overrides try to be somewhat smart about figuring out whether or not
+    a subtitle is considered a "sign".
+
+    :no:    Render subtitles as specified by the subtitle scripts, without
+            overrides.
+    :yes:   Apply all the ``--sub-ass-*`` style override options. Changing the
+            default for any of these options can lead to incorrect subtitle
+            rendering (default).
+    :force: Like ``yes``, but also force all ``--sub-*`` options. Can break
+            rendering easily.
+    :scale: Like ``yes``, but also apply ``--sub-scale``.
+    :strip: Radically strip all ASS tags and styles from the subtitle. This
+            is equivalent to the old ``--no-ass`` / ``--no-sub-ass`` options.
+
+    This also controls some bitmap subtitle overrides, as well as HTML tags in
+    formats like SRT, despite the name of the option.
+
+``--sub-ass-force-margins``
+    Enables placing toptitles and subtitles in black borders when they are
+    available, if the subtitles are in the ASS format.
+
+    Default: no.
+
+``--sub-use-margins``
+    Enables placing toptitles and subtitles in black borders when they are
+    available, if the subtitles are in a plain text format  (or ASS if
+    ``--sub-ass-override`` is set high enough).
+
+    Default: yes.
+
+``--sub-ass-vsfilter-aspect-compat=<yes|no>``
+    Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility
+    with traditional VSFilter behavior. This switch has no effect when the
+    video is stored with square pixels.
+
+    The renderer historically most commonly used for the SSA/ASS subtitle
+    formats, VSFilter, had questionable behavior that resulted in subtitles
+    being stretched too if the video was stored in anamorphic format that
+    required scaling for display.  This behavior is usually undesirable and
+    newer VSFilter versions may behave differently. However, many existing
+    scripts compensate for the stretching by modifying things in the opposite
+    direction.  Thus, if such scripts are displayed "correctly", they will not
+    appear as intended.  This switch enables emulation of the old VSFilter
+    behavior (undesirable but expected by many existing scripts).
+
+    Enabled by default.
+
+``--sub-ass-vsfilter-blur-compat=<yes|no>``
+    Scale ``\blur`` tags by video resolution instead of script resolution
+    (enabled by default). This is bug in VSFilter, which according to some,
+    can't be fixed anymore in the name of compatibility.
+
+    Note that this uses the actual video resolution for calculating the
+    offset scale factor, not what the video filter chain or the video output
+    use.
+
+``--sub-ass-vsfilter-color-compat=<basic|full|force-601|no>``
+    Mangle colors like (xy-)vsfilter do (default: basic). Historically, VSFilter
+    was not color space aware. This was no problem as long as the color space
+    used for SD video (BT.601) was used. But when everything switched to HD
+    (BT.709), VSFilter was still converting RGB colors to BT.601, rendered
+    them into the video frame, and handled the frame to the video output, which
+    would use BT.709 for conversion to RGB. The result were mangled subtitle
+    colors. Later on, bad hacks were added on top of the ASS format to control
+    how colors are to be mangled.
+
+    :basic: Handle only BT.601->BT.709 mangling, if the subtitles seem to
+            indicate that this is required (default).
+    :full:  Handle the full ``YCbCr Matrix`` header with all video color spaces
+            supported by libass and mpv. This might lead to bad breakages in
+            corner cases and is not strictly needed for compatibility
+            (hopefully), which is why this is not default.
+    :force-601: Force BT.601->BT.709 mangling, regardless of subtitle headers
+            or video color space.
+    :no:    Disable color mangling completely. All colors are RGB.
+
+    Choosing anything other than ``no`` will make the subtitle color depend on
+    the video color space, and it's for example in theory not possible to reuse
+    a subtitle script with another video file. The ``--sub-ass-override``
+    option doesn't affect how this option is interpreted.
+
+``--stretch-dvd-subs=<yes|no>``
+    Stretch DVD subtitles when playing anamorphic videos for better looking
+    fonts on badly mastered DVDs. This switch has no effect when the
+    video is stored with square pixels - which for DVD input cannot be the case
+    though.
+
+    Many studios tend to use bitmap fonts designed for square pixels when
+    authoring DVDs, causing the fonts to look stretched on playback on DVD
+    players. This option fixes them, however at the price of possibly
+    misaligning some subtitles (e.g. sign translations).
+
+    Disabled by default.
+
+``--stretch-image-subs-to-screen=<yes|no>``
+    Stretch DVD and other image subtitles to the screen, ignoring the video
+    margins. This has a similar effect as ``--sub-use-margins`` for text
+    subtitles, except that the text itself will be stretched, not only just
+    repositioned. (At least in general it is unavoidable, as an image bitmap
+    can in theory consist of a single bitmap covering the whole screen, and
+    the player won't know where exactly the text parts are located.)
+
+    This option does not display subtitles correctly. Use with care.
+
+    Disabled by default.
+
+``--image-subs-video-resolution=<yes|no>``
+    Override the image subtitle resolution with the video resolution
+    (default: no). Normally, the subtitle canvas is fit into the video canvas
+    (e.g. letterboxed). Setting this option uses the video size as subtitle
+    canvas size. Can be useful to test broken subtitles, which often happen
+    when the video was trancoded, while attempting to keep the old subtitles.
+
+``--sub-ass``, ``--no-sub-ass``
+    Render ASS subtitles natively (enabled by default).
+
+    .. note::
+
+        This has been deprecated by ``--sub-ass-override=strip``. You also
+        may need ``--embeddedfonts=no`` to get the same behavior. Also,
+        using ``--sub-ass-override=style`` should give better results
+        without breaking subtitles too much.
+
+    If ``--no-sub-ass`` is specified, all tags and style declarations are
+    stripped and ignored on display. The subtitle renderer uses the font style
+    as specified by the ``--sub-`` options instead.
+
+    .. note::
+
+        Using ``--no-sub-ass`` may lead to incorrect or completely broken
+        rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly
+        override the styling of ASS subtitles, but should be avoided in general.
+
+``--sub-auto=<no|exact|fuzzy|all>``, ``--no-sub-auto``
+    Load additional subtitle files matching the video filename. The parameter
+    specifies how external subtitle files are matched. ``exact`` is enabled by
+    default.
+
+    :no:    Don't automatically load external subtitle files.
+    :exact: Load the media filename with subtitle file extension and possibly
+            language suffixes (default).
+    :fuzzy: Load all subs containing the media filename.
+    :all:   Load all subs in the current and ``--sub-file-paths`` directories.
+
+``--sub-auto-exts=ext1,ext2,...``
+    Subtitle extentions to try and match when using ``--sub-auto``. Note that
+    modifying this list will also affect what mpv recognizes as subtitles when
+    using drag and drop.
+
+    This is a string list option. See `List Options`_ for details.
+
+``--sub-codepage=<codepage>``
+    You can use this option to specify the subtitle codepage. uchardet will be
+    used to guess the charset. (If mpv was not compiled with uchardet, then
+    ``utf-8`` is the effective default.)
+
+    The default value for this option is ``auto``, which enables autodetection.
+
+    The following steps are taken to determine the final codepage, in order:
+
+    - if the specific codepage has a ``+``, use that codepage
+    - if the data looks like UTF-8, assume it is UTF-8
+    - if ``--sub-codepage`` is set to a specific codepage, use that
+    - run uchardet, and if successful, use that
+    - otherwise, use ``UTF-8-BROKEN``
+
+    .. admonition:: Examples
+
+        - ``--sub-codepage=latin2`` Use Latin 2 if input is not UTF-8.
+        - ``--sub-codepage=+cp1250`` Always force recoding to cp1250.
+
+    The pseudo codepage ``UTF-8-BROKEN`` is used internally. If it's set,
+    subtitles are interpreted as UTF-8 with "Latin 1" as fallback for bytes
+    which are not valid UTF-8 sequences. iconv is never involved in this mode.
+
+    .. note::
+
+        This works for text subtitle files only. Other types of subtitles (in
+        particular subtitles in mkv files) are always assumed to be UTF-8.
+
+
+``--sub-stretch-durations=<yes|no>``
+    Stretch a subtitle duration so it ends when the next one starts.
+    Should help with subtitles which erroneously have zero durations.
+
+    .. note::
+
+        Only applies to text subtitles.
+
+``--sub-fix-timing=<yes|no>``
+    Adjust subtitle timing is to remove minor gaps or overlaps between
+    subtitles (if the difference is smaller than 210 ms, the gap or overlap
+    is removed).
+
+``--sub-forced-events-only=<yes|no>``
+    Enabling this displays only forced events within subtitle streams. Only
+    some bitmap subtitle formats (such as DVD or PGS) are capable of having a
+    mixture of forced and unforced events within the stream. Enabling this on
+    text subtitles will cause no subtitles to be displayed (default: ``no``).
+
+``--sub-fps=<rate>``
+    Specify the framerate of the subtitle file (default: video fps). Affects
+    text subtitles only.
+
+    .. note::
+
+        ``<rate>`` > video fps speeds the subtitles up for frame-based
+        subtitle files and slows them down for time-based ones.
+
+    See also: ``--sub-speed``.
+
+``--sub-gauss=<0.0-3.0>``
+    Apply Gaussian blur to image subtitles (default: 0). This can help to make
+    pixelated DVD/Vobsubs look nicer. A value other than 0 also switches to
+    software subtitle scaling. Might be slow.
+
+    .. note::
+
+        Never applied to text subtitles.
+
+``--sub-gray``
+    Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs
+    look nicer.
+
+    .. note::
+
+        Never applied to text subtitles.
+
+``--sub-file-paths=<path-list>``
+    Specify extra directories to search for subtitles matching the video.
+    Multiple directories can be separated by ":" (";" on Windows).
+    Paths can be relative or absolute. Relative paths are interpreted relative
+    to video file directory.
+    If the file is a URL, only absolute paths and ``sub`` configuration
+    subdirectory will be scanned.
+
+    .. admonition:: Example
+
+        Assuming that ``/path/to/video/video.avi`` is played and
+        ``--sub-file-paths=sub:subtitles`` is specified, mpv
+        searches for subtitle files in these directories:
+
+        - ``/path/to/video/``
+        - ``/path/to/video/sub/``
+        - ``/path/to/video/subtitles/``
+        -  the ``sub`` configuration subdirectory (usually ``~/.config/mpv/sub/``)
+
+    This is a path list option. See `List Options`_ for details.
+
+``--sub-visibility``, ``--no-sub-visibility``
+    Can be used to disable display of subtitles, but still select and decode
+    them.
+
+``--secondary-sub-visibility``, ``--no-secondary-sub-visibility``
+    Can be used to disable display of secondary subtitles, but still select and
+    decode them.
+
+``--sub-clear-on-seek``
+    (Obscure, rarely useful.) Can be used to play broken mkv files with
+    duplicate ReadOrder fields. ReadOrder is the first field in a
+    Matroska-style ASS subtitle packets. It should be unique, and libass
+    uses it for fast elimination of duplicates. This option disables caching
+    of subtitles across seeks, so after a seek libass can't eliminate subtitle
+    packets with the same ReadOrder as earlier packets.
+
+``--teletext-page=<1-999>``
+    This works for ``dvb_teletext`` subtitle streams, and if FFmpeg has been
+    compiled with support for it.
+
+``--sub-past-video-end``
+    After the last frame of video, if this option is enabled, subtitles will
+    continue to update based on audio timestamps. Otherwise, the subtitles
+    for the last video frame will stay onscreen.
+
+    Default: disabled
+
+``--sub-font=<name>``
+    Specify font to use for subtitles that do not themselves
+    specify a particular font. The default is ``sans-serif``.
+
+    .. admonition:: Examples
+
+        - ``--sub-font='Bitstream Vera Sans'``
+        - ``--sub-font='Comic Sans MS'``
+
+    .. note::
+
+        The ``--sub-font`` option (and many other style related ``--sub-``
+        options) are ignored when ASS-subtitles are rendered, unless the
+        ``--no-sub-ass`` option is specified.
+
+        This used to support fontconfig patterns. Starting with libass 0.13.0,
+        this stopped working.
+
+``--sub-font-size=<size>``
+    Specify the sub font size. The unit is the size in scaled pixels at a
+    window height of 720. The actual pixel size is scaled with the window
+    height: if the window height is larger or smaller than 720, the actual size
+    of the text increases or decreases as well.
+
+    Default: 55.
+
+``--sub-back-color=<color>``
+    See ``--sub-color``. Color used for sub text background. You can use
+    ``--sub-shadow-offset`` to change its size relative to the text.
+
+``--sub-blur=<0..20.0>``
+    Gaussian blur factor. 0 means no blur applied (default).
+
+``--sub-bold=<yes|no>``
+    Format text on bold.
+
+``--sub-italic=<yes|no>``
+    Format text on italic.
+
+``--sub-border-color=<color>``
+    See ``--sub-color``. Color used for the sub font border.
+
+``--sub-border-size=<size>``
+    Size of the sub font border in scaled pixels (see ``--sub-font-size``
+    for details). A value of 0 disables borders.
+
+    Default: 3.
+
+``--sub-color=<color>``
+    Specify the color used for unstyled text subtitles.
+
+    The color is specified in the form ``r/g/b``, where each color component
+    is specified as number in the range 0.0 to 1.0. It's also possible to
+    specify the transparency by using ``r/g/b/a``, where the alpha value 0
+    means fully transparent, and 1.0 means opaque. If the alpha component is
+    not given, the color is 100% opaque.
+
+    Passing a single number to the option sets the sub to gray, and the form
+    ``gray/a`` lets you specify alpha additionally.
+
+    .. admonition:: Examples
+
+        - ``--sub-color=1.0/0.0/0.0`` set sub to opaque red
+        - ``--sub-color=1.0/0.0/0.0/0.75`` set sub to opaque red with 75% alpha
+        - ``--sub-color=0.5/0.75`` set sub to 50% gray with 75% alpha
+
+    Alternatively, the color can be specified as a RGB hex triplet in the form
+    ``#RRGGBB``, where each 2-digit group expresses a color value in the
+    range 0 (``00``) to 255 (``FF``). For example, ``#FF0000`` is red.
+    This is similar to web colors. Alpha is given with ``#AARRGGBB``.
+
+    .. admonition:: Examples
+
+        - ``--sub-color='#FF0000'`` set sub to opaque red
+        - ``--sub-color='#C0808080'`` set sub to 50% gray with 75% alpha
+
+``--sub-margin-x=<size>``
+    Left and right screen margin for the subs in scaled pixels (see
+    ``--sub-font-size`` for details).
+
+    This option specifies the distance of the sub to the left, as well as at
+    which distance from the right border long sub text will be broken.
+
+    Default: 25.
+
+``--sub-margin-y=<size>``
+    Top and bottom screen margin for the subs in scaled pixels (see
+    ``--sub-font-size`` for details).
+
+    This option specifies the vertical margins of unstyled text subtitles.
+    If you just want to raise the vertical subtitle position, use ``--sub-pos``.
+
+    Default: 22.
+
+``--sub-align-x=<left|center|right>``
+    Control to which corner of the screen text subtitles should be
+    aligned to (default: ``center``).
+
+    Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise,
+    this does not apply to image subtitles.
+
+``--sub-align-y=<top|center|bottom>``
+    Vertical position (default: ``bottom``).
+    Details see ``--sub-align-x``.
+
+``--sub-justify=<auto|left|center|right>``
+    Control how multi line subs are justified irrespective of where they
+    are aligned (default: ``auto`` which justifies as defined by
+    ``--sub-align-x``).
+    Left justification is recommended to make the subs easier to read
+    as it is easier for the eyes.
+
+``--sub-ass-justify=<yes|no>``
+    Applies justification as defined by ``--sub-justify`` on ASS subtitles
+    if ``--sub-ass-override`` is not set to ``no``.
+    Default: ``no``.
+
+``--sub-shadow-color=<color>``
+    See ``--sub-color``. Color used for sub text shadow.
+
+    .. note::
+
+        ignored when ``--sub-back-color`` is
+        specified (or more exactly: when that option is not set to completely
+        transparent).
+
+``--sub-shadow-offset=<size>``
+    Displacement of the sub text shadow in scaled pixels (see
+    ``--sub-font-size`` for details). A value of 0 disables shadows.
+
+    Default: 0.
+
+``--sub-spacing=<size>``
+    Horizontal sub font spacing in scaled pixels (see ``--sub-font-size``
+    for details). This value is added to the normal letter spacing. Negative
+    values are allowed.
+
+    Default: 0.
+
+``--sub-filter-sdh=<yes|no>``
+    Applies filter removing subtitle additions for the deaf or hard-of-hearing (SDH).
+    This is intended for English, but may in part work for other languages too.
+    The intention is that it can be always enabled so may not remove
+    all parts added.
+    It removes speaker labels (like MAN:), upper case text in parentheses and
+    any text in brackets.
+
+    Default: ``no``.
+
+``--sub-filter-sdh-harder=<yes|no>``
+    Do harder SDH filtering (if enabled by ``--sub-filter-sdh``).
+    Will also remove speaker labels and text within parentheses using both
+    lower and upper case letters.
+
+    Default: ``no``.
+
+``--sub-filter-regex-...=...``
+    Set a list of regular expressions to match on text subtitles, and remove any
+    lines that match (default: empty). This is a string list option. See
+    `List Options`_ for details. Normally, you should use
+    ``--sub-filter-regex-append=<regex>``, where each option use will append a
+    new regular expression, without having to fight escaping problems.
+
+    List items are matched in order. If a regular expression matches, the
+    process is stopped, and the subtitle line is discarded. The text matched
+    against is, by default, the ``Text`` field of ASS events (if the
+    subtitle format is different, it is always converted). This may include
+    formatting tags. Matching is case-insensitive, but how this is done depends
+    on the libc, and most likely works in ASCII only. It does not work on
+    bitmap/image subtitles. Unavailable on inferior OSes (requires POSIX regex
+    support).
+
+    .. admonition:: Example
+
+        ``--sub-filter-regex-append=opensubtitles\.org`` filters some ads.
+
+    Technically, using a list for matching is redundant, since you could just
+    use a single combined regular expression. But it helps with diagnosis,
+    ease of use, and temporarily disabling or enabling individual filters.
+
+    .. warning::
+
+        This is experimental. The semantics most likely will change, and if you
+        use this, you should be prepared to update the option later. Ideas
+        include replacing the regexes with a very primitive and small subset of
+        sed, or some method to control case-sensitivity.
+
+``--sub-filter-jsre-...=...``
+    Same as ``--sub-filter-regex`` but with JavaScript regular expressions.
+    Shares/affected-by all ``--sub-filter-regex-*`` control options (see below),
+    and also experimental. Requires only JavaScript support.
+
+``--sub-filter-regex-plain=<yes|no>``
+    Whether to first convert the ASS "Text" field to plain-text (default: no).
+    This strips ASS tags and applies ASS directives, like ``\N`` to new-line.
+    If the result is multi-line then the regexp anchors ``^`` and ``$`` match
+    each line, but still any match discards all lines.
+
+``--sub-filter-regex-warn=<yes|no>``
+    Log dropped lines with warning log level, instead of verbose (default: no).
+    Helpful for testing.
+
+``--sub-filter-regex-enable=<yes|no>``
+    Whether to enable regex filtering (default: yes). Note that if no regexes
+    are added to the ``--sub-filter-regex`` list, setting this option to ``yes``
+    has no effect. It's meant to easily disable or enable filtering
+    temporarily.
+
+``--sub-create-cc-track=<yes|no>``
+    For every video stream, create a closed captions track (default: no). The
+    only purpose is to make the track available for selection at the start of
+    playback, instead of creating it lazily. This applies only to
+    ``ATSC A53 Part 4 Closed Captions`` (displayed by mpv as subtitle tracks
+    using the codec ``eia_608``). The CC track is marked "default" and selected
+    according to the normal subtitle track selection rules. You can then use
+    ``--sid`` to explicitly select the correct track too.
+
+    If the video stream contains no closed captions, or if no video is being
+    decoded, the CC track will remain empty and will not show any text.
+
+``--sub-font-provider=<auto|none|fontconfig>``
+    Which libass font provider backend to use (default: auto). ``auto`` will
+    attempt to use the native font provider: fontconfig on Linux, CoreText on
+    macOS, DirectWrite on Windows. ``fontconfig`` forces fontconfig, if libass
+    was built with support (if not, it behaves like ``none``).
+
+    The ``none`` font provider effectively disables system fonts. It will still
+    attempt to use embedded fonts (unless ``--embeddedfonts=no`` is set; this is
+    the same behavior as with all other font providers), ``subfont.ttf`` if
+    provided, and fonts in  the ``fonts`` sub-directory if provided. (The
+    fallback is more strict than that of other font providers, and if a font
+    name does not match, it may prefer not to render any text that uses the
+    missing font.)
+
+``--sub-fonts-dir=<path>``
+    Font files in this directory are used by mpv/libass for subtitles. Useful
+    if you do not want to install fonts to your system. Note that files in this
+    directory are loaded into memory before being used by mpv. If you have a
+    lot of fonts, consider using fonts.conf (see `FILES`_ section) to include
+    additional mpv user settings.
+
+    If this option is not specified, ``~~/fonts`` will be used by default.
+
+Window
+------
+
+``--title=<string>``
+    Set the window title. This is used for the video window, and if possible,
+    also sets the audio stream title.
+
+    Properties are expanded. (See `Property Expansion`_.)
+
+    .. warning::
+
+        There is a danger of this causing significant CPU usage, depending on
+        the properties used. Changing the window title is often a slow
+        operation, and if the title changes every frame, playback can be ruined.
+
+``--screen=<default|0-32>``
+    In multi-monitor configurations (i.e. a single desktop that spans across
+    multiple displays), this option tells mpv which screen to display the
+    video on.
+
+    .. admonition:: Note (X11)
+
+        This option does not work properly with all window managers. In these
+        cases, you can try to use ``--geometry`` to position the window
+        explicitly. It's also possible that the window manager provides native
+        features to control which screens application windows should use.
+
+    .. admonition:: Note (Wayland)
+
+        This option does not actually work on wayland since window placement is
+        not allowed. However setting this option does influence mpv's initial
+        guess at finding an output which may be useful for options like
+        ``--geometry`` or ``--autofit`` which depend on the monitor resolution.
+
+    See also ``--fs-screen``.
+
+``--screen-name=<string>``
+    In multi-monitor configurations, this option tells mpv which screen to
+    display the video on based on the screen name from the video backend. The
+    same caveats in the ``--screen`` option also apply here. This option is
+    ignored and does nothing if ``--screen`` is explicitly set.
+
+``--fullscreen``, ``--fs``
+    Fullscreen playback.
+
+``--fs-screen=<all|current|0-32>``
+    In multi-monitor configurations (i.e. a single desktop that spans across
+    multiple displays), this option tells mpv which screen to go fullscreen to.
+    If ``current`` is used mpv will fallback on what the user provided with
+    the ``screen`` option.
+
+    .. admonition:: Note (X11)
+
+        This option works properly only with window managers which
+        understand the EWMH ``_NET_WM_FULLSCREEN_MONITORS`` hint.
+
+    .. admonition:: Note (macOS)
+
+        ``all`` does not work on macOS and will behave like ``current``.
+
+    See also ``--screen``.
+
+``--fs-screen-name=<string>``
+    In multi-monitor configurations, this option tells mpv which screen to go
+    fullscreen to based on the screen name from the video backend. The same
+    caveats in the ``--fs-screen`` option also apply here. This option is
+    ignored and does nothing if ``--fs-screen`` is explicitly set.
+
+``--keep-open=<yes|no|always>``
+    Do not terminate when playing or seeking beyond the end of the file, and
+    there is no next file to be played (and ``--loop`` is not used).
+    Instead, pause the player. When trying to seek beyond end of the file, the
+    player will attempt to seek to the last frame.
+
+    Normally, this will act like ``set pause yes`` on EOF, unless the
+    ``--keep-open-pause=no`` option is set.
+
+    The following arguments can be given:
+
+    :no:        If the current file ends, go to the next file or terminate.
+                (Default.)
+    :yes:       Don't terminate if the current file is the last playlist entry.
+                Equivalent to ``--keep-open`` without arguments.
+    :always:    Like ``yes``, but also applies to files before the last playlist
+                entry. This means playback will never automatically advance to
+                the next file.
+
+    .. note::
+
+        This option is not respected when using ``--frames``. Explicitly
+        skipping to the next file if the binding uses ``force`` will terminate
+        playback as well.
+
+        Also, if errors or unusual circumstances happen, the player can quit
+        anyway.
+
+    Since mpv 0.6.0, this doesn't pause if there is a next file in the playlist,
+    or the playlist is looped. Approximately, this will pause when the player
+    would normally exit, but in practice there are corner cases in which this
+    is not the case (e.g. ``mpv --keep-open file.mkv /dev/null`` will play
+    file.mkv normally, then fail to open ``/dev/null``, then exit). (In
+    mpv 0.8.0, ``always`` was introduced, which restores the old behavior.)
+
+``--keep-open-pause=<yes|no>``
+    If set to ``no``, instead of pausing when ``--keep-open`` is active, just
+    stop at end of file and continue playing forward when you seek backwards
+    until end where it stops again. Default: ``yes``.
+
+``--image-display-duration=<seconds|inf>``
+    If the current file is an image, play the image for the given amount of
+    seconds (default: 1). ``inf`` means the file is kept open forever (until
+    the user stops playback manually).
+
+    Unlike ``--keep-open``, the player is not paused, but simply continues
+    playback until the time has elapsed. (It should not use any resources
+    during "playback".)
+
+    This affects image files, which are defined as having only 1 video frame
+    and no audio. The player may recognize certain non-images as images, for
+    example if ``--length`` is used to reduce the length to 1 frame, or if
+    you seek to the last frame.
+
+    This option does not affect the framerate used for ``mf://`` or
+    ``--merge-files``. For that, use ``--mf-fps`` instead.
+
+    Setting ``--image-display-duration`` hides the OSC and does not track
+    playback time on the command-line output, and also does not duplicate
+    the image frame when encoding. To force the player into "dumb mode"
+    and actually count out seconds, or to duplicate the image when
+    encoding, you need to use ``--demuxer=lavf --demuxer-lavf-o=loop=1``,
+    and use ``--length`` or ``--frames`` to stop after a particular time.
+
+``--force-window=<yes|no|immediate>``
+    Create a video output window even if there is no video. This can be useful
+    when pretending that mpv is a GUI application. Currently, the window
+    always has the size 640x480, and is subject to ``--geometry``,
+    ``--autofit``, and similar options.
+
+    .. warning::
+
+        The window is created only after initialization (to make sure default
+        window placement still works if the video size is different from the
+        ``--force-window`` default window size). This can be a problem if
+        initialization doesn't work perfectly, such as when opening URLs with
+        bad network connection, or opening broken video files. The ``immediate``
+        mode can be used to create the window always on program start, but this
+        may cause other issues.
+
+``--taskbar-progress``, ``--no-taskbar-progress``
+    (Windows only)
+    Enable/disable playback progress rendering in taskbar (Windows 7 and above).
+
+    Enabled by default.
+
+``--snap-window``
+    (Windows only) Snap the player window to screen edges.
+
+``--drag-and-drop=<no|auto|replace|append>``
+    (X11, Wayland and Windows only)
+    Controls the default behavior of drag and drop on platforms that support this.
+    ``auto`` will obey what the underlying os/platform gives mpv. Typically, holding
+    shift during the drag and drop will append the item to the playlist. Otherwise,
+    it will completely replace it. ``replace`` and ``append`` always force replacing
+    and appending to the playlist respectively. ``no`` disables all drag and drop
+    behavior.
+
+``--ontop``
+    Makes the player window stay on top of other windows.
+
+    On Windows, if combined with fullscreen mode, this causes mpv to be
+    treated as exclusive fullscreen window that bypasses the Desktop Window
+    Manager.
+
+``--ontop-level=<window|system|desktop|level>``
+    (macOS only)
+    Sets the level of an ontop window (default: window).
+
+    :window:  On top of all other windows.
+    :system:  On top of system elements like Taskbar, Menubar and Dock.
+    :desktop: On top of the Desktop behind windows and Desktop icons.
+    :level:   A level as integer.
+
+``--focus-on-open``, ``--no-focus-on-open``
+    (macOS only)
+    Focus the video window on creation and makes it the front most window. This
+    is on by default.
+
+``--window-corners=<default|donotround|round|roundsmall>``
+    (Windows only)
+    Set the preference for window corner rounding.
+
+    :default: Let the system decide whether or not to round window corners
+    :donotround: Never round window corners
+    :round: Round the corners if appropriate
+    :roundsmall: Round the corners if appropriate, with a small radius
+
+``--border``, ``--no-border``
+    Play video with window border and decorations. Since this is on by
+    default, use ``--no-border`` to disable the standard window decorations.
+
+``--title-bar``, ``--no-title-bar``
+    (Windows only)
+    Play video with the window title bar. Since this is on by default,
+    use --no-title-bar to hide the title bar. The --no-border option takes
+    precedence.
+
+``--on-all-workspaces``
+    (X11 and macOS only)
+    Show the video window on all virtual desktops.
+
+``--geometry=<[W[xH]][+-x+-y][/WS]>``, ``--geometry=<x:y>``
+    Adjust the initial window position or size. ``W`` and ``H`` set the window
+    size in pixels. ``x`` and ``y`` set the window position, measured in pixels
+    from the top-left corner of the screen to the top-left corner of the image
+    being displayed. If a percentage sign (``%``) is given after the argument,
+    it turns the value into a percentage of the screen size in that direction.
+    Positions are specified similar to the standard X11 ``--geometry`` option
+    format, in which e.g. +10-50 means "place 10 pixels from the left border and
+    50 pixels from the lower border" and "--20+-10" means "place 20 pixels
+    beyond the right and 10 pixels beyond the top border". A trailing ``/``
+    followed by an integer denotes on which workspace (virtual desktop) the
+    window should appear (X11 only).
+
+    If an external window is specified using the ``--wid`` option, this
+    option is ignored.
+
+    The coordinates are relative to the screen given with ``--screen`` for the
+    video output drivers that fully support ``--screen``.
+
+    .. note::
+
+        Generally only supported by GUI VOs. Ignored for encoding.
+
+    .. admonition:: Note (macOS)
+
+        On macOS, the origin of the screen coordinate system is located on the
+        bottom-left corner. For instance, ``0:0`` will place the window at the
+        bottom-left of the screen.
+
+    .. admonition:: Note (X11)
+
+        This option does not work properly with all window managers.
+
+    .. admonition:: Examples
+
+        ``50:40``
+            Places the window at x=50, y=40.
+        ``50%:50%``
+            Places the window in the middle of the screen.
+        ``100%:100%``
+            Places the window at the bottom right corner of the screen.
+        ``50%``
+            Sets the window width to half the screen width. Window height is set
+            so that the window has the video aspect ratio.
+        ``50%x50%``
+            Forces the window width and height to half the screen width and
+            height. Will show black borders to compensate for the video aspect
+            ratio (with most VOs and without ``--no-keepaspect``).
+        ``50%+10+10/2``
+            Sets the window to half the screen widths, and positions it 10
+            pixels below/left of the top left corner of the screen, on the
+            second workspace.
+
+    See also ``--autofit`` and ``--autofit-larger`` for fitting the window into
+    a given size without changing aspect ratio.
+
+``--autofit=<[W[xH]]>``
+    Set the initial window size to a maximum size specified by ``WxH``, without
+    changing the window's aspect ratio. The size is measured in pixels, or if
+    a number is followed by a percentage sign (``%``), in percents of the
+    screen size.
+
+    This option never changes the aspect ratio of the window. If the aspect
+    ratio mismatches, the window's size is reduced until it fits into the
+    specified size.
+
+    Window position is not taken into account, nor is it modified by this
+    option (the window manager still may place the window differently depending
+    on size). Use ``--geometry`` to change the window position. Its effects
+    are applied after this option.
+
+    See ``--geometry`` for details how this is handled with multi-monitor
+    setups.
+
+    Use ``--autofit-larger`` instead if you just want to limit the maximum size
+    of the window, rather than always forcing a window size.
+
+    Use ``--geometry`` if you want to force both window width and height to a
+    specific size.
+
+    .. note::
+
+        Generally only supported by GUI VOs. Ignored for encoding.
+
+    .. admonition:: Examples
+
+        ``70%``
+            Make the window width 70% of the screen size, keeping aspect ratio.
+        ``1000``
+            Set the window width to 1000 pixels, keeping aspect ratio.
+        ``70%x60%``
+            Make the window as large as possible, without being wider than 70%
+            of the screen width, or higher than 60% of the screen height.
+
+``--autofit-larger=<[W[xH]]>``
+    This option behaves exactly like ``--autofit``, except the window size is
+    only changed if the window would be larger than the specified size.
+
+    .. admonition:: Example
+
+        ``90%x80%``
+            If the video is larger than 90% of the screen width or 80% of the
+            screen height, make the window smaller until either its width is 90%
+            of the screen, or its height is 80% of the screen.
+
+``--autofit-smaller=<[W[xH]]>``
+    This option behaves exactly like ``--autofit``, except that it sets the
+    minimum size of the window (just as ``--autofit-larger`` sets the maximum).
+
+    .. admonition:: Example
+
+        ``500x500``
+            Make the window at least 500 pixels wide and 500 pixels high
+            (depending on the video aspect ratio, the width or height will be
+            larger than 500 in order to keep the aspect ratio the same).
+
+``--window-scale=<factor>``
+    Resize the video window to a multiple (or fraction) of the video size. This
+    option is applied before ``--autofit`` and other options are applied (so
+    they override this option).
+
+    For example, ``--window-scale=0.5`` would show the window at half the
+    video size.
+
+``--window-minimized=<yes|no>``
+    Whether the video window is minimized or not. Setting this will minimize,
+    or unminimize, the video window if the current VO supports it. Note that
+    some VOs may support minimization while not supporting unminimization
+    (eg: Wayland).
+
+    Whether this option and ``--window-maximized`` work on program start or
+    at runtime, and whether they're (at runtime) updated to reflect the actual
+    window state, heavily depends on the VO and the windowing system. Some VOs
+    simply do not implement them or parts of them, while other VOs may be
+    restricted by the windowing systems (especially Wayland).
+
+``--window-maximized=<yes|no>``
+    Whether the video window is maximized or not. Setting this will maximize,
+    or unmaximize, the video window if the current VO supports it. See
+    ``--window-minimized`` for further remarks.
+
+``--cursor-autohide=<number|no|always>``
+    Make mouse cursor automatically hide after given number of milliseconds
+    (default: 1000 ms). ``no`` will disable cursor autohide. ``always``
+    means the cursor will stay hidden.
+
+``--cursor-autohide-fs-only``
+    If this option is given, the cursor is always visible in windowed mode. In
+    fullscreen mode, the cursor is shown or hidden according to
+    ``--cursor-autohide``.
+
+``--force-rgba-osd-rendering``
+    Change how some video outputs render the OSD and text subtitles. This
+    does not change appearance of the subtitles and only has performance
+    implications. For VOs which support native ASS rendering (like ``gpu``,
+    ``vdpau``, ``direct3d``), this can be slightly faster or slower,
+    depending on GPU drivers and hardware. For other VOs, this just makes
+    rendering slower.
+
+``--force-render``
+    Forces mpv to always render frames regardless of the visibility of the
+    window. Currently only affects X11 and Wayland VOs since they are the
+    only ones that have this optimization (i.e. everything else always renders
+    regardless of visibility).
+
+``--force-window-position``
+    Forcefully move mpv's video output window to default location whenever
+    there is a change in video parameters, video stream or file. This used to
+    be the default behavior. Currently only affects X11 and SDL VOs.
+
+``--auto-window-resize=<yes|no>``
+    (Wayland, Win32, and X11)
+    By default, mpv will automatically resize itself if the video's size changes
+    (i.e. advancing forward in a playlist). Setting this to ``no`` disables this
+    behavior so the window size never changes automatically. This option does
+    not have any impact on the ``--autofit`` or ``--geometry`` options.
+
+``--no-keepaspect``, ``--keepaspect``
+    ``--no-keepaspect`` will always stretch the video to window size, and will
+    disable the window manager hints that force the window aspect ratio.
+    (Ignored in fullscreen mode.)
+
+``--no-keepaspect-window``, ``--keepaspect-window``
+    ``--keepaspect-window`` (the default) will lock the window size to the
+    video aspect. ``--no-keepaspect-window`` disables this behavior, and will
+    instead add black bars if window aspect and video aspect mismatch. Whether
+    this actually works depends on the VO backend.
+    (Ignored in fullscreen mode.)
+
+``--monitoraspect=<ratio>``
+    Set the aspect ratio of your monitor or TV screen. A value of 0 disables a
+    previous setting (e.g. in the config file). Overrides the
+    ``--monitorpixelaspect`` setting if enabled.
+
+    See also ``--monitorpixelaspect`` and ``--video-aspect-override``.
+
+    .. admonition:: Examples
+
+        - ``--monitoraspect=4:3``  or ``--monitoraspect=1.3333``
+        - ``--monitoraspect=16:9`` or ``--monitoraspect=1.7777``
+
+``--hidpi-window-scale``, ``--no-hidpi-window-scale``
+    (macOS, Windows, X11, and Wayland only)
+    Scale the window size according to the backing scale factor (default: yes).
+    On regular HiDPI resolutions the window opens with double the size but appears
+    as having the same size as on non-HiDPI resolutions.
+
+``--native-fs``, ``--no-native-fs``
+    (macOS only)
+    Uses the native fullscreen mechanism of the OS (default: yes).
+
+``--monitorpixelaspect=<ratio>``
+    Set the aspect of a single pixel of your monitor or TV screen (default:
+    1). A value of 1 means square pixels (correct for (almost?) all LCDs). See
+    also ``--monitoraspect`` and ``--video-aspect-override``.
+
+``--stop-screensaver=<yes|no|always>``
+    Turns off the screensaver (or screen blanker and similar mechanisms) at
+    startup and turns it on again on exit (default: yes). When using ``yes``,
+    the screensaver will re-enable when playback is not active. ``always`` will
+    always disable the screensaver. Note that stopping the screensaver is only
+    possible if a video output is available (i.e. there is an open mpv window).
+
+    This is not supported on all video outputs or platforms. Sometimes it is
+    implemented, but does not work (especially with Linux "desktops"). Read the
+    `Disabling Screensaver`_ section very carefully.
+
+``--wid=<ID>``
+    This tells mpv to attach to an existing window. If a VO is selected that
+    supports this option, it will use that window for video output. mpv will
+    scale the video to the size of this window, and will add black bars to
+    compensate if the aspect ratio of the video is different.
+
+    On X11, the ID is interpreted as a ``Window`` on X11. Unlike
+    MPlayer/mplayer2, mpv always creates its own window, and sets the wid
+    window as parent. The window will always be resized to cover the parent
+    window fully. The value ``0`` is interpreted specially, and mpv will
+    draw directly on the root window.
+
+    On win32, the ID is interpreted as ``HWND``. Pass it as value cast to
+    ``uint32_t`` (all Windows handles are 32-bit), this is important as mpv will
+    not accept negative values. mpv will create its own window and set the
+    wid window as parent, like with X11.
+
+    On macOS/Cocoa, the ID is interpreted as ``NSView*``. Pass it as value cast
+    to ``intptr_t``. mpv will create its own sub-view. Because macOS does not
+    support window embedding of foreign processes, this works only with libmpv,
+    and will crash when used from the command line.
+
+    On Android, the ID is interpreted as ``android.view.Surface``. Pass it as a
+    value cast to ``intptr_t``. Use with ``--vo=mediacodec_embed`` and
+    ``--hwdec=mediacodec`` for direct rendering using MediaCodec, or with
+    ``--vo=gpu --gpu-context=android`` (with or without ``--hwdec=mediacodec``).
+
+``--no-window-dragging``
+    Don't move the window when clicking on it and moving the mouse pointer.
+
+``--x11-name=<string>``
+    Set the window class name for X11-based video output methods.
+
+``--x11-netwm=<yes|no|auto>``
+    (X11 only)
+    Control the use of NetWM protocol features.
+
+    This may or may not help with broken window managers. This provides some
+    functionality that was implemented by the now removed ``--fstype`` option.
+    Actually, it is not known to the developers to which degree this option
+    was needed, so feedback is welcome.
+
+    Specifically, ``yes`` will force use of NetWM fullscreen support, even if
+    not advertised by the WM. This can be useful for WMs that are broken on
+    purpose, like XMonad. (XMonad supposedly doesn't advertise fullscreen
+    support, because Flash uses it. Apparently, applications which want to
+    use fullscreen anyway are supposed to either ignore the NetWM support hints,
+    or provide a workaround. Shame on XMonad for deliberately breaking X
+    protocols (as if X isn't bad enough already).
+
+    By default, NetWM support is autodetected (``auto``).
+
+    This option might be removed in the future.
+
+``--x11-bypass-compositor=<yes|no|fs-only|never>``
+    If set to ``yes``, then ask the compositor to unredirect the mpv window
+    (default: ``fs-only``). This uses the ``_NET_WM_BYPASS_COMPOSITOR`` hint.
+
+    ``fs-only`` asks the window manager to disable the compositor only in
+    fullscreen mode.
+
+    ``no`` sets ``_NET_WM_BYPASS_COMPOSITOR`` to 0, which is the default value
+    as declared by the EWMH specification, i.e. no change is done.
+
+    ``never`` asks the window manager to never disable the compositor.
+
+``--x11-present=<no|auto|yes>``
+    Whether or not to use presentation statistics from X11's presentation
+    extension (default: ``auto``).
+
+    mpv asks X11 for present events which it then may use for more accurate
+    frame presentation. This only has an effect if ``--video-sync=display-...``
+    is being used.
+
+    The auto option enumerates XRandr providers for autodetection. If amd, radeon,
+    intel, or nouveau (the standard x86 Mesa drivers) is found and nvidia is NOT
+    found, presentation feedback is enabled. Other drivers are not assumed to
+    work, so they are not enabled automatically.
+
+    ``yes`` or ``no`` can still be passed regardless to enable/disable this
+    mechanism in case there is good/bad behavior with whatever your combination
+    of hardware/drivers/etc. happens to be.
+
+``--x11-wid-title`` ``--no-x11-wid-title``
+    Whether or not to set the window title when mpv is embedded on X11 (default:
+    ``no``).
+
+
+Disc Devices
+------------
+
+``--cdda-device=<path>``
+    Specify the CD device for CDDA playback (default: ``/dev/cdrom``).
+
+``--dvd-device=<path>``
+    Specify the DVD device or .iso filename (default: ``/dev/dvd``). You can
+    also specify a directory that contains files previously copied directly
+    from a DVD (with e.g. vobcopy).
+
+    .. admonition:: Example
+
+        ``mpv dvd:// --dvd-device=/path/to/dvd/``
+
+``--bluray-device=<path>``
+    (Blu-ray only)
+    Specify the Blu-ray disc location. Must be a directory with Blu-ray
+    structure.
+
+    .. admonition:: Example
+
+        ``mpv bd:// --bluray-device=/path/to/bd/``
+
+``--cdda-...``
+    These options can be used to tune the CD Audio reading feature of mpv.
+
+``--cdda-speed=<value>``
+    Set CD spin speed.
+
+``--cdda-paranoia=<0-2>``
+    Set paranoia level. Values other than 0 seem to break playback of
+    anything but the first track.
+
+    :0: disable checking (default)
+    :1: overlap checking only
+    :2: full data correction and verification
+
+``--cdda-sector-size=<value>``
+    Set atomic read size.
+
+``--cdda-overlap=<value>``
+    Force minimum overlap search during verification to <value> sectors.
+
+``--cdda-toc-offset=<value>``
+    Add ``<value>`` sectors to the values reported when addressing tracks.
+    May be negative.
+
+``--cdda-skip=<yes|no>``
+    (Never) accept imperfect data reconstruction.
+
+``--cdda-cdtext=<yes|no>``
+    Print CD text. This is disabled by default, because it ruins performance
+    with CD-ROM drives for unknown reasons.
+
+``--dvd-speed=<speed>``
+    Try to limit DVD speed (default: 0, no change). DVD base speed is 1385
+    kB/s, so an 8x drive can read at speeds up to 11080 kB/s. Slower speeds
+    make the drive more quiet. For watching DVDs, 2700 kB/s should be quiet and
+    fast enough. mpv resets the speed to the drive default value on close.
+    Values of at least 100 mean speed in kB/s. Values less than 100 mean
+    multiples of 1385 kB/s, i.e. ``--dvd-speed=8`` selects 11080 kB/s.
+
+    .. note::
+
+        You need write access to the DVD device to change the speed.
+
+``--dvd-angle=<ID>``
+    Some DVDs contain scenes that can be viewed from multiple angles.
+    This option tells mpv which angle to use (default: 1).
+
+
+
+Equalizer
+---------
+
+``--brightness=<-100-100>``
+    Adjust the brightness of the video signal (default: 0). Not supported by
+    all video output drivers.
+
+``--contrast=<-100-100>``
+    Adjust the contrast of the video signal (default: 0). Not supported by all
+    video output drivers.
+
+``--saturation=<-100-100>``
+    Adjust the saturation of the video signal (default: 0). You can get
+    grayscale output with this option. Not supported by all video output
+    drivers.
+
+``--gamma=<-100-100>``
+    Adjust the gamma of the video signal (default: 0). Not supported by all
+    video output drivers.
+
+``--hue=<-100-100>``
+    Adjust the hue of the video signal (default: 0). You can get a colored
+    negative of the image with this option. Not supported by all video output
+    drivers.
+
+Demuxer
+-------
+
+``--demuxer=<[+]name>``
+    Force demuxer type. Use a '+' before the name to force it; this will skip
+    some checks. Give the demuxer name as printed by ``--demuxer=help``.
+
+``--demuxer-lavf-analyzeduration=<value>``
+    Maximum length in seconds to analyze the stream properties.
+
+``--demuxer-lavf-probe-info=<yes|no|auto|nostreams>``
+    Whether to probe stream information (default: auto). Technically, this
+    controls whether libavformat's ``avformat_find_stream_info()`` function
+    is called. Usually it's safer to call it, but it can also make startup
+    slower.
+
+    The ``auto`` choice (the default) tries to skip this for a few know-safe
+    whitelisted formats, while calling it for everything else.
+
+    The ``nostreams`` choice only calls it if and only if the file seems to
+    contain no streams after opening (helpful in cases when calling the function
+    is needed to detect streams at all, such as with FLV files).
+
+``--demuxer-lavf-probescore=<1-100>``
+    Minimum required libavformat probe score. Lower values will require
+    less data to be loaded (makes streams start faster), but makes file
+    format detection less reliable. Can be used to force auto-detected
+    libavformat demuxers, even if libavformat considers the detection not
+    reliable enough. (Default: 26.)
+
+``--demuxer-lavf-allow-mimetype=<yes|no>``
+    Allow deriving the format from the HTTP MIME type (default: yes). Set
+    this to no in case playing things from HTTP mysteriously fails, even
+    though the same files work from local disk.
+
+    This is default in order to reduce latency when opening HTTP streams.
+
+``--demuxer-lavf-format=<name>``
+    Force a specific libavformat demuxer.
+
+``--demuxer-lavf-hacks=<yes|no>``
+    By default, some formats will be handled differently from other formats
+    by explicitly checking for them. Most of these compensate for weird or
+    imperfect behavior from libavformat demuxers. Passing ``no`` disables
+    these. For debugging and testing only.
+
+``--demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]``
+    Pass AVOptions to libavformat demuxer.
+
+    Note, a patch to make the *o=* unneeded and pass all unknown options
+    through the AVOption system is welcome. A full list of AVOptions can
+    be found in the FFmpeg manual. Note that some options may conflict
+    with mpv options.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        ``--demuxer-lavf-o=fflags=+ignidx``
+
+``--demuxer-lavf-probesize=<value>``
+    Maximum amount of data to probe during the detection phase. In the
+    case of MPEG-TS this value identifies the maximum number of TS packets
+    to scan.
+
+``--demuxer-lavf-buffersize=<value>``
+    Size of the stream read buffer allocated for libavformat in bytes
+    (default: 32768). Lowering the size could lower latency. Note that
+    libavformat might reallocate the buffer internally, or not fully use all
+    of it.
+
+``--demuxer-lavf-linearize-timestamps=<yes|no|auto>``
+    Attempt to linearize timestamp resets in demuxed streams (default: auto).
+    This was tested only for single audio streams. It's unknown whether it
+    works correctly for video (but likely won't). Note that the implementation
+    is slightly incorrect either way, and will introduce a discontinuity by
+    about 1 codec frame size.
+
+    The ``auto`` mode enables this for OGG audio stream. This covers the common
+    and annoying case of OGG web radio streams. Some of these will reset
+    timestamps to 0 every time a new song begins. This breaks the mpv seekable
+    cache, which can't deal with timestamp resets. Note that FFmpeg/libavformat's
+    seeking API can't deal with this either; it's likely that if this option
+    breaks this even more, while if it's disabled, you can at least seek within
+    the first song in the stream. Well, you won't get anything useful either
+    way if the seek is outside of mpv's cache.
+
+``--demuxer-lavf-propagate-opts=<yes|no>``
+    Propagate FFmpeg-level options to recursively opened connections (default:
+    yes). This is needed because FFmpeg will apply these settings to nested
+    AVIO contexts automatically. On the other hand, this could break in certain
+    situations - it's the FFmpeg API, you just can't win.
+
+    This affects in particular the ``--timeout`` option and anything passed
+    with ``--demuxer-lavf-o``.
+
+    If this option is deemed unnecessary at some point in the future, it will
+    be removed without notice.
+
+``--demuxer-mkv-subtitle-preroll=<yes|index|no>``
+    Try harder to show embedded soft subtitles when seeking somewhere. Normally,
+    it can happen that the subtitle at the seek target is not shown due to how
+    some container file formats are designed. The subtitles appear only if
+    seeking before or exactly to the position a subtitle first appears. To
+    make this worse, subtitles are often timed to appear a very small amount
+    before the associated video frame, so that seeking to the video frame
+    typically does not demux the subtitle at that position.
+
+    Enabling this option makes the demuxer start reading data a bit before the
+    seek target, so that subtitles appear correctly. Note that this makes
+    seeking slower, and is not guaranteed to always work. It only works if the
+    subtitle is close enough to the seek target.
+
+    Works with the internal Matroska demuxer only. Always enabled for absolute
+    and hr-seeks, and this option changes behavior with relative or imprecise
+    seeks only.
+
+    You can use the ``--demuxer-mkv-subtitle-preroll-secs`` option to specify
+    how much data the demuxer should pre-read at most in order to find subtitle
+    packets that may overlap. Setting this to 0 will effectively disable this
+    preroll mechanism. Setting a very large value can make seeking very slow,
+    and an extremely large value would completely reread the entire file from
+    start to seek target on every seek - seeking can become slower towards the
+    end of the file. The details are messy, and the value is actually rounded
+    down to the cluster with the previous video keyframe.
+
+    Some files, especially files muxed with newer mkvmerge versions, have
+    information embedded that can be used to determine what subtitle packets
+    overlap with a seek target. In these cases, mpv will reduce the amount
+    of data read to a minimum. (Although it will still read *all* data between
+    the cluster that contains the first wanted subtitle packet, and the seek
+    target.) If the ``index`` choice (which is the default) is specified, then
+    prerolling will be done only if this information is actually available. If
+    this method is used, the maximum amount of data to skip can be additionally
+    controlled by ``--demuxer-mkv-subtitle-preroll-secs-index`` (it still uses
+    the value of the option without ``-index`` if that is higher).
+
+    See also ``--hr-seek-demuxer-offset`` option. This option can achieve a
+    similar effect, but only if hr-seek is active. It works with any demuxer,
+    but makes seeking much slower, as it has to decode audio and video data
+    instead of just skipping over it.
+
+``--demuxer-mkv-subtitle-preroll-secs=<value>``
+    See ``--demuxer-mkv-subtitle-preroll``.
+
+``--demuxer-mkv-subtitle-preroll-secs-index=<value>``
+    See ``--demuxer-mkv-subtitle-preroll``.
+
+``--demuxer-mkv-probe-start-time=<yes|no>``
+    Check the start time of Matroska files (default: yes). This simply reads the
+    first cluster timestamps and assumes it is the start time. Technically, this
+    also reads the first timestamp, which may increase latency by one frame
+    (which may be relevant for live streams).
+
+``--demuxer-mkv-probe-video-duration=<yes|no|full>``
+    When opening the file, seek to the end of it, and check what timestamp the
+    last video packet has, and report that as file duration. This is strictly
+    for compatibility with Haali only. In this mode, it's possible that opening
+    will be slower (especially when playing over http), or that behavior with
+    broken files is much worse. So don't use this option.
+
+    The ``yes`` mode merely uses the index and reads a small number of blocks
+    from the end of the file. The ``full`` mode actually traverses the entire
+    file and can make a reliable estimate even without an index present (such
+    as partial files).
+
+``--demuxer-rawaudio-channels=<value>``
+    Number of channels (or channel layout) if ``--demuxer=rawaudio`` is used
+    (default: stereo).
+
+``--demuxer-rawaudio-format=<value>``
+    Sample format for ``--demuxer=rawaudio`` (default: s16le).
+    Use ``--demuxer-rawaudio-format=help`` to get a list of all formats.
+
+``--demuxer-rawaudio-rate=<value>``
+    Sample rate for ``--demuxer=rawaudio`` (default: 44 kHz).
+
+``--demuxer-rawvideo-fps=<value>``
+    Rate in frames per second for ``--demuxer=rawvideo`` (default: 25.0).
+
+``--demuxer-rawvideo-w=<value>``, ``--demuxer-rawvideo-h=<value>``
+    Image dimension in pixels for ``--demuxer=rawvideo``.
+
+    .. admonition:: Example
+
+        Play a raw YUV sample::
+
+            mpv sample-720x576.yuv --demuxer=rawvideo \
+            --demuxer-rawvideo-w=720 --demuxer-rawvideo-h=576
+
+``--demuxer-rawvideo-format=<value>``
+    Color space (fourcc) in hex or string for ``--demuxer=rawvideo``
+    (default: ``YV12``).
+
+``--demuxer-rawvideo-mp-format=<value>``
+    Color space by internal video format for ``--demuxer=rawvideo``. Use
+    ``--demuxer-rawvideo-mp-format=help`` for a list of possible formats.
+
+``--demuxer-rawvideo-codec=<value>``
+    Set the video codec instead of selecting the rawvideo codec when using
+    ``--demuxer=rawvideo``. This uses the same values as codec names in
+    ``--vd`` (but it does not accept decoder names).
+
+``--demuxer-rawvideo-size=<value>``
+    Frame size in bytes when using ``--demuxer=rawvideo``.
+
+``--demuxer-max-bytes=<bytesize>``
+    This controls how much the demuxer is allowed to buffer ahead. The demuxer
+    will normally try to read ahead as much as necessary, or as much is
+    requested with ``--demuxer-readahead-secs``. The option can be used to
+    restrict the maximum readahead. This limits excessive readahead in case of
+    broken files or desynced playback. The demuxer will stop reading additional
+    packets as soon as one of the limits is reached. (The limits still can be
+    slightly overstepped due to technical reasons.)
+
+    Set these limits higher if you get a packet queue overflow warning, and
+    you think normal playback would be possible with a larger packet queue.
+
+    See ``--list-options`` for defaults and value range. ``<bytesize>`` options
+    accept suffixes such as ``KiB`` and ``MiB``.
+
+``--demuxer-max-back-bytes=<bytesize>``
+    This controls how much past data the demuxer is allowed to preserve. This
+    is useful only if the cache is enabled.
+
+    Unlike the forward cache, there is no control how many seconds are actually
+    cached - it will simply use as much memory this option allows. Setting this
+    option to 0 will strictly disable any back buffer, but this will lead to
+    the situation that the forward seek range starts after the current playback
+    position (as it removes past packets that are seek points).
+
+    If the end of the file is reached, the remaining unused forward buffer space
+    is "donated" to the backbuffer (unless the backbuffer size is set to 0, or
+    ``--demuxer-donate-buffer`` is set to ``no``).
+    This still limits the total cache usage to the sum of the forward and
+    backward cache, and effectively makes better use of the total allowed memory
+    budget. (The opposite does not happen: free backward buffer is never
+    "donated" to the forward buffer.)
+
+    Keep in mind that other buffers in the player (like decoders) will cause the
+    demuxer to cache "future" frames in the back buffer, which can skew the
+    impression about how much data the backbuffer contains.
+
+    See ``--list-options`` for defaults and value range.
+
+``--demuxer-donate-buffer=<yes|no>``
+    Whether to let the back buffer use part of the forward buffer (default: yes).
+    If set to ``yes``, the "donation" behavior described in the option
+    description for ``--demuxer-max-back-bytes`` is enabled. This means the
+    back buffer may use up memory up to the sum of the forward and back buffer
+    options, minus the active size of the forward buffer. If set to ``no``, the
+    options strictly limit the forward and back buffer sizes separately.
+
+    Note that if the end of the file is reached, the buffered data stays the
+    same, even if you seek back within the cache. This is because the back
+    buffer is only reduced when new data is read.
+
+``--demuxer-seekable-cache=<yes|no|auto>``
+    Debugging option to control whether seeking can use the demuxer cache
+    (default: auto). Normally you don't ever need to set this; the default
+    ``auto`` does the right thing and enables cache seeking it if ``--cache``
+    is set to ``yes`` (or is implied ``yes`` if ``--cache=auto``).
+
+    If enabled, short seek offsets will not trigger a low level demuxer seek
+    (which means for example that slow network round trips or FFmpeg seek bugs
+    can be avoided). If a seek cannot happen within the cached range, a low
+    level seek will be triggered. Seeking outside of the cache will start a new
+    cached range, but can discard the old cache range if the demuxer exhibits
+    certain unsupported behavior.
+
+    The special value ``auto`` means ``yes`` in the same situation as
+    ``--cache-secs`` is used (i.e. when the stream appears to be a network
+    stream or the stream cache is enabled).
+
+``--demuxer-thread=<yes|no>``
+    Run the demuxer in a separate thread, and let it prefetch a certain amount
+    of packets (default: yes). Having this enabled leads to smoother playback,
+    enables features like prefetching, and prevents that stuck network freezes
+    the player. On the other hand, it can add overhead, or the background
+    prefetching can hog CPU resources.
+
+    Disabling this option is not recommended. Use it for debugging only.
+
+``--demuxer-termination-timeout=<seconds>``
+    Number of seconds the player should wait to shutdown the demuxer (default:
+    0.1). The player will wait up to this much time before it closes the
+    stream layer forcefully. Forceful closing usually means the network I/O is
+    given no chance to close its connections gracefully (of course the OS can
+    still close TCP connections properly), and might result in annoying messages
+    being logged, and in some cases, confused remote servers.
+
+    This timeout is usually only applied when loading has finished properly. If
+    loading is aborted by the user, or in some corner cases like removing
+    external tracks sourced from network during playback, forceful closing is
+    always used.
+
+``--demuxer-readahead-secs=<seconds>``
+    If ``--demuxer-thread`` is enabled, this controls how much the demuxer
+    should buffer ahead in seconds (default: 1). As long as no packet has
+    a timestamp difference higher than the readahead amount relative to the
+    last packet returned to the decoder, the demuxer keeps reading.
+
+    Note that enabling the cache (such as ``--cache=yes``, or if the input
+    is considered a network stream, and ``--cache=auto`` is used), this option
+    is mostly ignored. (``--cache-secs`` will override this. Technically, the
+    maximum of both options is used.)
+
+    The main purpose of this option is to limit the readhead for local playback,
+    since a large readahead value is not overly useful in this case.
+
+    (This value tends to be fuzzy, because many file formats don't store linear
+    timestamps.)
+
+``--demuxer-hysteresis-secs=<seconds>``
+    Once the demuxer limit is reached (``--demuxer-max-bytes``,
+    ``--demuxer-readahead-secs`` or ``--cache-secs``), this value can be used
+    to specify a hysteresis before the demuxer will buffer ahead again. This
+    specifies the maximum number of seconds from the current playback position
+    that needs to be remaining in the cache before the demuxer will continue
+    buffering ahead.
+
+    For example, with a value of 10 seconds specified, the demuxer will buffer
+    ahead up to the demuxer limit and won't start buffering ahead again until
+    there is only 10 seconds of content left in the cache.
+
+    This can provide significant power savings and reduce load by making the
+    demuxer only buffer ahead in chunks at a time rather than buffering ahead
+    nonstop to keep the cache filled.
+
+    If you want to save power and reduce load, configure this to a small number
+    that's much lower than ``--cache-secs`` or ``--demuxer-readahead-secs``.
+    If it takes a long time to buffer anything at all for a given stream (like
+    when reading from a very slow disk is involved), then the hysteresis value
+    should be larger to compensate.
+
+    The default value is 0 seconds, which disables the caching hysteresis. A
+    value of 10 seconds probably works well for most usecases.
+
+``--prefetch-playlist=<yes|no>``
+    Prefetch next playlist entry while playback of the current entry is ending
+    (default: no).
+
+    This does not prefill the cache with the video data of the next URL.
+    Prefetching video data is supported only for the current playlist entry,
+    and depends on the demuxer cache settings (on by default). This merely
+    opens the URL of the next playlist entry as soon the current URL is fully
+    read.
+
+    This does **not** work with URLs resolved by the ``youtube-dl`` wrapper,
+    and it won't.
+
+    This can give subtly wrong results if per-file options are used, or if
+    options are changed in the time window between prefetching start and next
+    file played.
+
+    This can occasionally make wrong prefetching decisions. For example, it
+    can't predict whether you go backwards in the playlist, and assumes you
+    won't edit the playlist.
+
+    Highly experimental.
+
+``--force-seekable=<yes|no>``
+    If the player thinks that the media is not seekable (e.g. playing from a
+    pipe, or it's an http stream with a server that doesn't support range
+    requests), seeking will be disabled. This option can forcibly enable it.
+    For seeks within the cache, there's a good chance of success.
+
+``--demuxer-cache-wait=<yes|no>``
+    Before starting playback, read data until either the end of the file was
+    reached, or the demuxer cache has reached maximum capacity. Only once this
+    is done, playback starts. This intentionally happens before the initial
+    seek triggered with ``--start``. This does not change any runtime behavior
+    after the initial caching. This option is useless if the file cannot be
+    cached completely.
+
+``--rar-list-all-volumes=<yes|no>``
+    When opening multi-volume rar files, open all volumes to create a full list
+    of contained files (default: no). If disabled, only the archive entries
+    whose headers are located within the first volume are listed (and thus
+    played when opening a .rar file with mpv). Doing so speeds up opening, and
+    the typical idiotic use-case of playing uncompressed multi-volume rar files
+    that contain a single media file is made faster.
+
+    Opening is still slow, because for unknown, idiotic, and unnecessary reasons
+    libarchive opens all volumes anyway when playing the main file, even though
+    mpv iterated no archive entries yet.
+
+``--directory-mode=<auto|lazy|recursive|ignore>``
+    When opening a directory, open subdirectories lazily, recursively or not at
+    all. The default is ``auto``, which behaves like ``recursive`` with
+    ``--shuffle``, and like ``lazy`` otherwise.
+
+Input
+-----
+
+``--native-keyrepeat``
+    Use system settings for keyrepeat delay and rate, instead of
+    ``--input-ar-delay`` and ``--input-ar-rate``. (Whether this applies
+    depends on the VO backend and how it handles keyboard input. Does not
+    apply to terminal input.)
+
+``--input-ar-delay``
+    Delay in milliseconds before we start to autorepeat a key (0 to disable).
+
+``--input-ar-rate``
+    Number of key presses to generate per second on autorepeat.
+
+``--input-conf=<filename>``
+    Specify input configuration file other than the default location in the mpv
+    configuration directory (usually ``~/.config/mpv/input.conf``).
+
+``--no-input-default-bindings``
+    Disable default-level ("weak") key bindings. These are bindings which config
+    files like ``input.conf`` can override. It currently affects the builtin key
+    bindings, and keys which scripts bind using ``mp.add_key_binding`` (but not
+    ``mp.add_forced_key_binding`` because this overrides ``input.conf``).
+
+``--no-input-builtin-bindings``
+    Disable loading of built-in key bindings during start-up. This option is
+    applied only during (lib)mpv initialization, and if used then it will not
+    be not possible to enable them later. May be useful to libmpv clients.
+
+``--input-cmdlist``
+    Prints all commands that can be bound to keys.
+
+``--input-doubleclick-time=<milliseconds>``
+    Time in milliseconds to recognize two consecutive button presses as a
+    double-click (default: 300).
+
+``--input-keylist``
+    Prints all keys that can be bound to commands.
+
+``--input-key-fifo-size=<2-65000>``
+    Specify the size of the FIFO that buffers key events (default: 7). If it
+    is too small, some events may be lost. The main disadvantage of setting it
+    to a very large value is that if you hold down a key triggering some
+    particularly slow command then the player may be unresponsive while it
+    processes all the queued commands.
+
+``--input-test``
+    Input test mode. Instead of executing commands on key presses, mpv
+    will show the keys and the bound commands on the OSD. Has to be used
+    with a dummy video, and the normal ways to quit the player will not
+    work (key bindings that normally quit will be shown on OSD only, just
+    like any other binding). See `INPUT.CONF`_.
+
+``--input-terminal``, ``--no-input-terminal``
+    ``--no-input-terminal`` prevents the player from reading key events from
+    standard input. Useful when reading data from standard input. This is
+    automatically enabled when ``-`` is found on the command line. There are
+    situations where you have to set it manually, e.g. if you open
+    ``/dev/stdin`` (or the equivalent on your system), use stdin in a playlist
+    or intend to read from stdin later on via the loadfile or loadlist input
+    commands.
+
+``--input-ipc-server=<filename>``
+    Enable the IPC support and create the listening socket at the given path.
+
+    On Linux and Unix, the given path is a regular filesystem path. On Windows,
+    named pipes are used, so the path refers to the pipe namespace
+    (``\\.\pipe\<name>``). If the ``\\.\pipe\`` prefix is missing, mpv will add
+    it automatically before creating the pipe, so
+    ``--input-ipc-server=/tmp/mpv-socket`` and
+    ``--input-ipc-server=\\.\pipe\tmp\mpv-socket`` are equivalent for IPC on
+    Windows.
+
+    See `JSON IPC`_ for details.
+
+``--input-ipc-client=fd://<N>``
+    Connect a single IPC client to the given FD. This is somewhat similar to
+    ``--input-ipc-server``, except no socket is created, and instead the passed
+    FD is treated like a socket connection received from ``accept()``. In
+    practice, you could pass either a FD created by ``socketpair()``, or a pipe.
+    In both cases, you must sure the FD is actually inherited by mpv (do not
+    set the POSIX ``CLOEXEC`` flag).
+
+    The player quits when the connection is closed.
+
+    This is somewhat similar to the removed ``--input-file`` option, except it
+    supports only integer FDs, and cannot open actual paths.
+
+    .. admonition:: Example
+
+        ``--input-ipc-client=fd://123``
+
+    .. note::
+
+        Does not and will not work on Windows.
+
+    .. warning::
+
+        Writing to the ``input-ipc-server`` option at runtime will start another
+        instance of an IPC client handler for the ``input-ipc-client`` option,
+        because initialization is bundled, and this thing is stupid. This is a
+        bug. Writing to ``input-ipc-client`` at runtime will start another IPC
+        client handler for the new value, without stopping the old one, even if
+        the FD value is the same (but the string is different e.g. due to
+        whitespace). This is not a bug.
+
+``--input-gamepad=<yes|no>``
+    Enable/disable SDL2 Gamepad support. Disabled by default.
+
+``--input-cursor``, ``--no-input-cursor``
+    Permit mpv to receive pointer events reported by the video output
+    driver. Necessary to use the OSC, or to select the buttons in DVD menus.
+    Support depends on the VO in use.
+
+``--input-cursor-passthrough``, ``--no-input-cursor-passthrough``
+    (X11 and Wayland only)
+    Tell the backend windowing system to allow pointer events to passthrough
+    the mpv window. This allows windows under mpv to instead receive pointer
+    events as if the mpv window was never there.
+
+``--input-media-keys=<yes|no>``
+    On systems where mpv can choose between receiving media keys or letting
+    the system handle them - this option controls whether mpv should receive
+    them.
+
+    Default: yes (except for libmpv). macOS and Windows only, because elsewhere
+    mpv doesn't have a choice - the system decides whether to send media keys
+    to mpv. For instance, on X11 or Wayland, system-wide media keys are not
+    implemented. Whether media keys work when the mpv window is focused is
+    implementation-defined.
+
+``--input-right-alt-gr``, ``--no-input-right-alt-gr``
+    (Cocoa and Windows only)
+    Use the right Alt key as Alt Gr to produce special characters. If disabled,
+    count the right Alt as an Alt modifier key. Enabled by default.
+
+``--input-vo-keyboard=<yes|no>``
+    Disable all keyboard input on for VOs which can't participate in proper
+    keyboard input dispatching. May not affect all VOs. Generally useful for
+    embedding only.
+
+    On X11, a sub-window with input enabled grabs all keyboard input as long
+    as it is 1. a child of a focused window, and 2. the mouse is inside of
+    the sub-window. It can steal away all keyboard input from the
+    application embedding the mpv window, and on the other hand, the mpv
+    window will receive no input if the mouse is outside of the mpv window,
+    even though mpv has focus. Modern toolkits work around this weird X11
+    behavior, but naively embedding foreign windows breaks it.
+
+    The only way to handle this reasonably is using the XEmbed protocol, which
+    was designed to solve these problems. GTK provides ``GtkSocket``, which
+    supports XEmbed. Qt doesn't seem to provide anything working in newer
+    versions.
+
+    If the embedder supports XEmbed, input should work with default settings
+    and with this option disabled. Note that ``input-default-bindings`` is
+    disabled by default in libmpv as well - it should be enabled if you want
+    the mpv default key bindings.
+
+OSD
+---
+
+``--osc``, ``--no-osc``
+    Whether to load the on-screen-controller (default: yes).
+
+``--no-osd-bar``, ``--osd-bar``
+    Disable display of the OSD bar.
+
+    You can configure this on a per-command basis in input.conf using ``osd-``
+    prefixes, see ``Input Command Prefixes``. If you want to disable the OSD
+    completely, use ``--osd-level=0``.
+
+``--osd-on-seek=<no,bar,msg,msg-bar>``
+    Set what is displayed on the OSD during seeks. The default is ``bar``.
+
+    You can configure this on a per-command basis in input.conf using ``osd-``
+    prefixes, see ``Input Command Prefixes``.
+
+``--osd-duration=<time>``
+    Set the duration of the OSD messages in ms (default: 1000).
+
+``--osd-font=<name>``
+    Specify font to use for OSD. The default is ``sans-serif``.
+
+    .. admonition:: Examples
+
+        - ``--osd-font='Bitstream Vera Sans'``
+        - ``--osd-font='Comic Sans MS'``
+
+``--osd-font-size=<size>``
+    Specify the OSD font size. See ``--sub-font-size`` for details.
+
+    Default: 55.
+
+``--osd-msg1=<string>``
+    Show this string as message on OSD with OSD level 1 (visible by default).
+    The message will be visible by default, and as long as no other message
+    covers it, and the OSD level isn't changed (see ``--osd-level``).
+    Expands properties; see `Property Expansion`_.
+
+``--osd-msg2=<string>``
+    Similar to ``--osd-msg1``, but for OSD level 2. If this is an empty string
+    (default), then the playback time is shown.
+
+``--osd-msg3=<string>``
+    Similar to ``--osd-msg1``, but for OSD level 3. If this is an empty string
+    (default), then the playback time, duration, and some more information is
+    shown.
+
+    This is used for the ``show-progress`` command (by default mapped to ``P``),
+    and when seeking if enabled with ``--osd-on-seek`` or by ``osd-`` prefixes
+    in input.conf (see ``Input Command Prefixes``).
+
+    ``--osd-status-msg`` is a legacy equivalent (but with a minor difference).
+
+``--osd-status-msg=<string>``
+    Show a custom string during playback instead of the standard status text.
+    This overrides the status text used for ``--osd-level=3``, when using the
+    ``show-progress`` command (by default mapped to ``P``), and when seeking if
+    enabled with ``--osd-on-seek`` or ``osd-`` prefixes in input.conf (see
+    ``Input Command Prefixes``). Expands properties. See `Property Expansion`_.
+
+    This option has been replaced with ``--osd-msg3``. The only difference is
+    that this option implicitly includes ``${osd-sym-cc}``. This option is
+    ignored if ``--osd-msg3`` is not empty.
+
+``--osd-playing-msg=<string>``
+    Show a message on OSD when playback starts. The string is expanded for
+    properties, e.g. ``--osd-playing-msg='file: ${filename}'`` will show the
+    message ``file:`` followed by a space and the currently played filename.
+
+    See `Property Expansion`_.
+
+``--osd-playing-msg-duration=<time>``
+    Set the duration of ``osd-playing-msg`` in ms. If this is unset,
+    ``osd-playing-msg`` stays on screen for the duration of ``osd-duration``.
+
+``--osd-bar-align-x=<-1-1>``
+    Position of the OSD bar. -1 is far left, 0 is centered, 1 is far right.
+    Fractional values (like 0.5) are allowed.
+
+``--osd-bar-align-y=<-1-1>``
+    Position of the OSD bar. -1 is top, 0 is centered, 1 is bottom.
+    Fractional values (like 0.5) are allowed.
+
+``--osd-bar-w=<1-100>``
+    Width of the OSD bar, in percentage of the screen width (default: 75).
+    A value of 50 means the bar is half the screen wide.
+
+``--osd-bar-h=<0.1-50>``
+    Height of the OSD bar, in percentage of the screen height (default: 3.125).
+
+``--osd-back-color=<color>``
+    See ``--sub-color``. Color used for OSD text background.
+
+``--osd-blur=<0..20.0>``
+    Gaussian blur factor. 0 means no blur applied (default).
+
+``--osd-bold=<yes|no>``
+    Format text on bold.
+
+``--osd-italic=<yes|no>``
+    Format text on italic.
+
+``--osd-border-color=<color>``
+    See ``--sub-color``. Color used for the OSD font border.
+
+``--osd-border-size=<size>``
+    Size of the OSD font border in scaled pixels (see ``--sub-font-size``
+    for details). A value of 0 disables borders.
+
+    Default: 3.
+
+``--osd-color=<color>``
+    Specify the color used for OSD.
+    See ``--sub-color`` for details.
+
+``--osd-fractions``
+    Show OSD times with fractions of seconds (in millisecond precision). Useful
+    to see the exact timestamp of a video frame.
+
+``--osd-level=<0-3>``
+    Specifies which mode the OSD should start in.
+
+    :0: OSD completely disabled (subtitles only)
+    :1: enabled (shows up only on user interaction)
+    :2: enabled + current time visible by default
+    :3: enabled + ``--osd-status-msg`` (current time and status by default)
+
+``--osd-margin-x=<size>``
+    Left and right screen margin for the OSD in scaled pixels (see
+    ``--sub-font-size`` for details).
+
+    This option specifies the distance of the OSD to the left, as well as at
+    which distance from the right border long OSD text will be broken.
+
+    Default: 25.
+
+``--osd-margin-y=<size>``
+    Top and bottom screen margin for the OSD in scaled pixels (see
+    ``--sub-font-size`` for details).
+
+    This option specifies the vertical margins of the OSD.
+
+    Default: 22.
+
+``--osd-align-x=<left|center|right>``
+    Control to which corner of the screen OSD should be
+    aligned to (default: ``left``).
+
+``--osd-align-y=<top|center|bottom>``
+    Vertical position (default: ``top``).
+    Details see ``--osd-align-x``.
+
+``--osd-scale=<factor>``
+    OSD font size multiplier, multiplied with ``--osd-font-size`` value.
+
+``--osd-scale-by-window=<yes|no>``
+    Whether to scale the OSD with the window size (default: yes). If this is
+    disabled, ``--osd-font-size`` and other OSD options that use scaled pixels
+    are always in actual pixels. The effect is that changing the window size
+    won't change the OSD font size.
+
+``--osd-shadow-color=<color>``
+    See ``--sub-color``. Color used for OSD shadow.
+
+    .. note::
+
+        ignored when ``--osd-back-color`` is specified (or more exactly: when
+        that option is not set to completely transparent).
+
+``--osd-shadow-offset=<size>``
+    Displacement of the OSD shadow in scaled pixels (see
+    ``--sub-font-size`` for details). A value of 0 disables shadows.
+
+    Default: 0.
+
+``--osd-spacing=<size>``
+    Horizontal OSD/sub font spacing in scaled pixels (see ``--sub-font-size``
+    for details). This value is added to the normal letter spacing. Negative
+    values are allowed.
+
+    Default: 0.
+
+``--video-osd=<yes|no>``
+    Enabled OSD rendering on the video window (default: yes). This can be used
+    in situations where terminal OSD is preferred. If you just want to disable
+    all OSD rendering, use ``--osd-level=0``.
+
+    It does not affect subtitles or overlays created by scripts (in particular,
+    the OSC needs to be disabled with ``--no-osc``).
+
+    This option is somewhat experimental and could be replaced by another
+    mechanism in the future.
+
+``--osd-font-provider=<...>``
+    See ``--sub-font-provider`` for details and accepted values. Note that
+    unlike subtitles, OSD never uses embedded fonts from media files.
+
+``--osd-fonts-dir=<path>``
+    See ``--sub-fonts-dir`` for details.  Defaults to ``~~/fonts``.
+
+Screenshot
+----------
+
+``--screenshot-format=<type>``
+    Set the image file type used for saving screenshots.
+
+    Available choices:
+
+    :png:       PNG
+    :jpg:       JPEG (default)
+    :jpeg:      JPEG (alias for jpg)
+    :webp:      WebP
+    :jxl:       JPEG XL
+    :avif:      AVIF
+
+``--screenshot-tag-colorspace=<yes|no>``
+    Tag screenshots with the appropriate colorspace (default: yes).
+
+    Note that not all formats support this. When it is unsupported, or when
+    this option is disabled, screenshots will be converted to sRGB before
+    being written.
+
+``--screenshot-high-bit-depth=<yes|no>``
+    If possible, write screenshots with a bit depth similar to the source
+    video (default: yes). This is interesting in particular for PNG, as this
+    sometimes triggers writing 16 bit PNGs with huge file sizes. This will also
+    include an unused alpha channel in the resulting files if 16 bit is used.
+
+``--screenshot-template=<template>``
+    Specify the filename template used to save screenshots. The template
+    specifies the filename without file extension, and can contain format
+    specifiers, which will be substituted when taking a screenshot.
+    By default, the template is ``mpv-shot%n``, which results in filenames like
+    ``mpv-shot0012.png`` for example.
+
+    The template can start with a relative or absolute path, in order to
+    specify a directory location where screenshots should be saved.
+
+    If the final screenshot filename points to an already existing file, the
+    file will not be overwritten. The screenshot will either not be saved, or if
+    the template contains ``%n``, saved using different, newly generated
+    filename.
+
+    Allowed format specifiers:
+
+    ``%[#][0X]n``
+        A sequence number, padded with zeros to length X (default: 04). E.g.
+        passing the format ``%04n`` will yield ``0012`` on the 12th screenshot.
+        The number is incremented every time a screenshot is taken or if the
+        file already exists. The length ``X`` must be in the range 0-9. With
+        the optional # sign, mpv will use the lowest available number. For
+        example, if you take three screenshots--0001, 0002, 0003--and delete
+        the first two, the next two screenshots will not be 0004 and 0005, but
+        0001 and 0002 again.
+    ``%f``
+        Filename of the currently played video.
+    ``%F``
+        Same as ``%f``, but strip the file extension, including the dot.
+    ``%x``
+        Directory path of the currently played video. If the video is not on
+        the filesystem (but e.g. ``http://``), this expand to an empty string.
+    ``%X{fallback}``
+        Same as ``%x``, but if the video file is not on the filesystem, return
+        the fallback string inside the ``{...}``.
+    ``%p``
+        Current playback time, in the same format as used in the OSD. The
+        result is a string of the form "HH:MM:SS". For example, if the video is
+        at the time position 5 minutes and 34 seconds, ``%p`` will be replaced
+        with "00:05:34".
+    ``%P``
+        Similar to ``%p``, but extended with the playback time in milliseconds.
+        It is formatted as "HH:MM:SS.mmm", with "mmm" being the millisecond
+        part of the playback time.
+
+        .. note::
+
+            This is a simple way for getting unique per-frame timestamps. (Frame
+            numbers would be more intuitive, but are not easily implementable
+            because container formats usually use time stamps for identifying
+            frames.)
+    ``%wX``
+        Specify the current playback time using the format string ``X``.
+        ``%p`` is like ``%wH:%wM:%wS``, and ``%P`` is like ``%wH:%wM:%wS.%wT``.
+
+        Valid format specifiers:
+            ``%wH``
+                hour (padded with 0 to two digits)
+            ``%wh``
+                hour (not padded)
+            ``%wM``
+                minutes (00-59)
+            ``%wm``
+                total minutes (includes hours, unlike ``%wM``)
+            ``%wS``
+                seconds (00-59)
+            ``%ws``
+                total seconds (includes hours and minutes)
+            ``%wf``
+                like ``%ws``, but as float
+            ``%wT``
+                milliseconds (000-999)
+
+    ``%tX``
+        Specify the current local date/time using the format ``X``. This format
+        specifier uses the UNIX ``strftime()`` function internally, and inserts
+        the result of passing "%X" to ``strftime``. For example, ``%tm`` will
+        insert the number of the current month as number. You have to use
+        multiple ``%tX`` specifiers to build a full date/time string.
+    ``%{prop[:fallback text]}``
+        Insert the value of the input property 'prop'. E.g. ``%{filename}`` is
+        the same as ``%f``. If the property does not exist or is not available,
+        an error text is inserted, unless a fallback is specified.
+    ``%%``
+        Replaced with the ``%`` character itself.
+
+``--screenshot-dir=<path>``
+    Store screenshots in this directory. This path is joined with the filename
+    generated by ``--screenshot-template``. If the template filename is already
+    absolute, the directory is ignored.
+
+    ``--screenshot-directory`` is an alias for ``--screenshot-dir``.
+
+    If the directory does not exist, it is created on the first screenshot. If
+    it is not a directory, an error is generated when trying to write a
+    screenshot.
+
+    This option is not set by default, and thus will write screenshots to the
+    directory from which mpv was started. In pseudo-gui mode
+    (see `PSEUDO GUI MODE`_), this is set to the desktop.
+
+``--screenshot-jpeg-quality=<0-100>``
+    Set the JPEG quality level. Higher means better quality. The default is 90.
+
+``--screenshot-jpeg-source-chroma=<yes|no>``
+    Write JPEG files with the same chroma subsampling as the video
+    (default: yes). If disabled, the libjpeg default is used.
+
+``--screenshot-png-compression=<0-9>``
+    Set the PNG compression level. Higher means better compression. This will
+    affect the file size of the written screenshot file and the time it takes
+    to write a screenshot. Too high compression might occupy enough CPU time to
+    interrupt playback. The default is 7.
+
+``--screenshot-png-filter=<0-5>``
+    Set the filter applied prior to PNG compression. 0 is none, 1 is "sub", 2 is
+    "up", 3 is "average", 4 is "Paeth", and 5 is "mixed". This affects the level
+    of compression that can be achieved. For most images, "mixed" achieves the
+    best compression ratio, hence it is the default.
+
+``--screenshot-webp-lossless=<yes|no>``
+    Write lossless WebP files. ``--screenshot-webp-quality`` is ignored if this
+    is set. The default is no.
+
+``--screenshot-webp-quality=<0-100>``
+    Set the WebP quality level. Higher means better quality. The default is 75.
+
+``--screenshot-webp-compression=<0-6>``
+    Set the WebP compression level. Higher means better compression, but takes
+    more CPU time. Note that this also affects the screenshot quality when used
+    with lossy WebP files. The default is 4.
+
+``--screenshot-jxl-distance=<0-15>``
+    Set the JPEG XL Butteraugli distance. Lower means better quality. Lossless
+    is 0.0, and 1.0 is approximately equivalent to JPEG quality 90 for
+    photographic content. Use 0.1 for "visually lossless" screenshots. The
+    default is 1.0.
+
+``--screenshot-jxl-effort=<1-9>``
+    Set the JPEG XL compression effort. Higher effort (usually) means better
+    compression, but takes more CPU time. The default is 4.
+
+``--screenshot-avif-encoder=<encoder>``
+    Specify the AV1 encoder to be used by libavcodec for encoding avif
+    screenshots.
+
+    Default: ``libaom-av1``
+
+``--screenshot-avif-pixfmt=<format>``
+    Specify the pixel format to the libavcodec encoder.
+
+    Default: ``yuv420p``
+
+``--screenshot-avif-opts=key1=value1,key2=value2,...``
+    Specifies libavcodec options for selected encoder. For more information,
+    consult the FFmpeg documentation.
+
+    Default: ``usage=allintra,crf=32,cpu-used=8,tune=ssim``
+
+    Note: the default is only guaranteed to work with the libaom-av1 encoder.
+    Above options may not be valid and or optimal for other encoders.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        "``--screenshot-avif-opts=crf=32,aq-mode=complexity``"
+            sets the crf to 32 and quantization (aq-mode) to complexity based.
+
+``--screenshot-sw=<yes|no>``
+    Whether to use software rendering for screenshots (default: no).
+
+    If set to no, the screenshot will be rendered by the current VO (only vo_gpu
+    or vo_gpu_next currently). The advantage is that this will (probably) always
+    show up as in the video window, because the same code is used for rendering.
+    But since the renderer needs to be reinitialized, this can be slow and
+    interrupt playback.
+
+    If set to yes, the software scaler is used to convert the video to RGB (or
+    whatever the target screenshot requires). In this case, conversion will
+    run in a separate thread and will probably not interrupt playback. The
+    software renderer may lack some capabilities, such as HDR rendering.
+    If ``window`` mode is used, the image will also be scaled in software
+    which may not accurately reflect the actual visible result.
+
+Software Scaler
+---------------
+
+``--sws-scaler=<name>``
+    Specify the software scaler algorithm to be used with ``--vf=scale``. This
+    also affects video output drivers which lack hardware acceleration,
+    e.g. ``x11``. See also ``--vf=scale``.
+
+    To get a list of available scalers, run ``--sws-scaler=help``.
+
+    Default: ``bicubic``.
+
+``--sws-lgb=<0-100>``
+    Software scaler Gaussian blur filter (luma). See ``--sws-scaler``.
+
+``--sws-cgb=<0-100>``
+    Software scaler Gaussian blur filter (chroma). See ``--sws-scaler``.
+
+``--sws-ls=<-100-100>``
+    Software scaler sharpen filter (luma). See ``--sws-scaler``.
+
+``--sws-cs=<-100-100>``
+    Software scaler sharpen filter (chroma). See ``--sws-scaler``.
+
+``--sws-chs=<h>``
+    Software scaler chroma horizontal shifting. See ``--sws-scaler``.
+
+``--sws-cvs=<v>``
+    Software scaler chroma vertical shifting. See ``--sws-scaler``.
+
+``--sws-bitexact=<yes|no>``
+    Unknown functionality (default: no). Consult libswscale source code. The
+    primary purpose of this, as far as libswscale API goes), is to produce
+    exactly the same output for the same input on all platforms (output has the
+    same "bits" everywhere, thus "bitexact"). Typically disables optimizations.
+
+``--sws-fast=<yes|no>``
+    Allow optimizations that help with performance, but reduce quality (default:
+    no).
+
+    VOs like ``drm`` and ``x11`` will benefit a lot from using ``--sws-fast``.
+    You may need to set other options, like ``--sws-scaler``. The builtin
+    ``sws-fast`` profile sets this option and some others to gain performance
+    for reduced quality. Also see ``--sws-allow-zimg``.
+
+``--sws-allow-zimg=<yes|no>``
+    Allow using zimg (if the component using the internal swscale wrapper
+    explicitly allows so) (default: yes). In this case, zimg *may* be used, if
+    the internal zimg wrapper supports the input and output formats. It will
+    silently or noisily fall back to libswscale if one of these conditions does
+    not apply.
+
+    If zimg is used, the other ``--sws-`` options are ignored, and the
+    ``--zimg-`` options are used instead.
+
+    If the internal component using the swscale wrapper hooks up logging
+    correctly, a verbose priority log message will indicate whether zimg is
+    being used.
+
+    Most things which need software conversion can make use of this.
+
+    .. note::
+
+        Do note that zimg *may* be slower than libswscale. Usually,
+        it's faster on x86 platforms, but slower on ARM (due to lack of ARM
+        specific optimizations). The mpv zimg wrapper uses unoptimized repacking
+        for some formats, for which zimg cannot be blamed.
+
+``--zimg-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>``
+    Zimg luma scaler to use (default: lanczos).
+
+``--zimg-scaler-param-a=<default|float>``, ``--zimg-scaler-param-b=<default|float>``
+    Set scaler parameters. By default, these are set to the special string
+    ``default``, which maps to a scaler-specific default value. Ignored if the
+    scaler is not tunable.
+
+    ``lanczos``
+        ``--zimg-scaler-param-a`` is the number of taps.
+
+    ``bicubic``
+        a and b are the bicubic b and c parameters.
+
+``--zimg-scaler-chroma=...``
+    Same as ``--zimg-scaler``, for for chroma interpolation (default: bilinear).
+
+``--zimg-scaler-chroma-param-a``, ``--zimg-scaler-chroma-param-b``
+    Same as ``--zimg-scaler-param-a`` / ``--zimg-scaler-param-b``, for chroma.
+
+``--zimg-dither=<no|ordered|random|error-diffusion>``
+    Dithering (default: random).
+
+``--zimg-threads=<auto|integer>``
+    Set the maximum number of threads to use for scaling (default: auto).
+    ``auto`` uses the number of logical cores on the current machine. Note that
+    the scaler may use less threads (or even just 1 thread) depending on stuff.
+    Passing a value of 1 disables threading and always scales the image in a
+    single operation. Higher thread counts waste resources, but make it
+    typically faster.
+
+    Note that some zimg git versions had bugs that will corrupt the output if
+    threads are used.
+
+``--zimg-fast=<yes|no>``
+    Allow optimizations that help with performance, but reduce quality (default:
+    yes). Currently, this may simplify gamma conversion operations.
+
+
+Audio Resampler
+---------------
+
+This controls the default options of any resampling done by mpv (but not within
+libavfilter, within the system audio API resampler, or any other places).
+
+It also sets the defaults for the ``lavrresample`` audio filter.
+
+``--audio-resample-filter-size=<length>``
+    Length of the filter with respect to the lower sampling rate. (default:
+    16)
+
+``--audio-resample-phase-shift=<count>``
+    Log2 of the number of polyphase entries. (..., 10->1024, 11->2048,
+    12->4096, ...) (default: 10->1024)
+
+``--audio-resample-cutoff=<cutoff>``
+    Cutoff frequency (0.0-1.0), default set depending upon filter length.
+
+``--audio-resample-linear=<yes|no>``
+    If set then filters will be linearly interpolated between polyphase
+    entries. (default: no)
+
+``--audio-normalize-downmix=<yes|no>``
+    Enable/disable normalization if surround audio is downmixed to stereo
+    (default: no). If this is disabled, downmix can cause clipping. If it's
+    enabled, the output might be too quiet. It depends on the source audio.
+
+    Technically, this changes the ``normalize`` suboption of the
+    ``lavrresample`` audio filter, which performs the downmixing.
+
+    If downmix happens outside of mpv for some reason, or in the decoder
+    (decoder downmixing), or in the audio output (system mixer), this has no
+    effect.
+
+``--audio-resample-max-output-size=<length>``
+    Limit maximum size of audio frames filtered at once, in ms (default: 40).
+    The output size size is limited in order to make resample speed changes
+    react faster. This is necessary especially if decoders or filters output
+    very large frame sizes (like some lossless codecs or some DRC filters).
+    This option does not affect the resampling algorithm in any way.
+
+    For testing/debugging only. Can be removed or changed any time.
+
+``--audio-swresample-o=<string>``
+    Set AVOptions on the SwrContext or AVAudioResampleContext. These should
+    be documented by FFmpeg or Libav.
+
+    This is a key/value list option. See `List Options`_ for details.
+
+Terminal
+--------
+
+``--quiet``
+    Make console output less verbose; in particular, prevents the status line
+    (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being displayed.
+    Particularly useful on slow terminals or broken ones which do not properly
+    handle carriage return (i.e. ``\r``).
+
+    See also: ``--really-quiet`` and ``--msg-level``.
+
+``--really-quiet``
+    Display even less output and status messages than with ``--quiet``.
+
+``--no-terminal``, ``--terminal``
+    Disable any use of the terminal and stdin/stdout/stderr. This completely
+    silences any message output.
+
+    Unlike ``--really-quiet``, this disables input and terminal initialization
+    as well.
+
+``--no-msg-color``
+    Disable colorful console output on terminals.
+
+``--msg-level=<module1=level1,module2=level2,...>``
+    Control verbosity directly for each module. The ``all`` module changes the
+    verbosity of all the modules. The verbosity changes from this option are
+    applied in order from left to right, and each item can override a previous
+    one.
+
+    Run mpv with ``--msg-level=all=trace`` to see all messages mpv outputs. You
+    can use the module names printed in the output (prefixed to each line in
+    ``[...]``) to limit the output to interesting modules.
+
+    This also affects ``--log-file``, and in certain cases libmpv API logging.
+
+    .. note::
+
+        Some messages are printed before the command line is parsed and are
+        therefore not affected by ``--msg-level``. To control these messages,
+        you have to use the ``MPV_VERBOSE`` environment variable; see
+        `ENVIRONMENT VARIABLES`_ for details.
+
+    Available levels:
+
+        :no:        complete silence
+        :fatal:     fatal messages only
+        :error:     error messages
+        :warn:      warning messages
+        :info:      informational messages
+        :status:    status messages (default)
+        :v:         verbose messages
+        :debug:     debug messages
+        :trace:     very noisy debug messages
+
+    .. admonition:: Example
+
+        ::
+
+            mpv --msg-level=ao/sndio=no
+
+        Completely silences the output of ao_sndio, which uses the log
+        prefix ``[ao/sndio]``.
+
+        ::
+
+            mpv --msg-level=all=warn,ao/alsa=error
+
+        Only show warnings or worse, and let the ao_alsa output show errors
+        only.
+
+``--term-osd=<auto|no|force>``
+    Control whether OSD messages are shown on the console when no video output
+    is available (default: auto).
+
+    :auto:      use terminal OSD if no video output active
+    :no:        disable terminal OSD
+    :force:     use terminal OSD even if video output active
+
+    The ``auto`` mode also enables terminal OSD if ``--video-osd=no`` was set.
+
+``--term-osd-bar``, ``--no-term-osd-bar``
+    Enable printing a progress bar under the status line on the terminal.
+    (Disabled by default.)
+
+``--term-osd-bar-chars=<string>``
+    Customize the ``--term-osd-bar`` feature. The string is expected to
+    consist of 5 characters (start, left space, position indicator,
+    right space, end). You can use Unicode characters, but note that double-
+    width characters will not be treated correctly.
+
+    Default: ``[-+-]``.
+
+``--term-playing-msg=<string>``
+    Print out a string after starting playback. The string is expanded for
+    properties, e.g. ``--term-playing-msg='file: ${filename}'`` will print the string
+    ``file:`` followed by a space and the currently played filename.
+
+    See `Property Expansion`_.
+
+``--term-remaining-playtime``, ``--no-term-remaining-playtime``
+    When printing out the time on the terminal, show the remaining time adjusted by
+    playback speed. Default: ``yes``
+
+``--term-status-msg=<string>``
+    Print out a custom string during playback instead of the standard status
+    line. Expands properties. See `Property Expansion`_.
+
+``--term-title=<string>``
+    Set the terminal title. Currently, this simply concatenates the escape
+    sequence setting the window title with the provided (property expanded)
+    string. This will mess up if the expanded string contain bytes that end the
+    escape sequence, or if the terminal does not understand the sequence. The
+    latter probably includes the regrettable win32.
+
+    Expands properties. See `Property Expansion`_.
+
+``--msg-module``
+    Prepend module name to each console message.
+
+``--msg-time``
+    Prepend timing information to each console message. The time is in
+    seconds since the player process was started (technically, slightly
+    later actually), using a monotonic time source depending on the OS. This
+    is ``CLOCK_MONOTONIC`` on sane UNIX variants.
+
+Cache
+-----
+
+``--cache=<yes|no|auto>``
+    Decide whether to use network cache settings (default: auto).
+
+    If enabled, use up to ``--cache-secs`` for the cache size (but still limited
+    to ``--demuxer-max-bytes``), and make the cached data seekable (if possible).
+    If disabled, ``--cache-pause`` and related are implicitly disabled.
+
+    The ``auto`` choice enables this depending on whether the stream is thought
+    to involve network accesses or other slow media (this is an imperfect
+    heuristic).
+
+    Before mpv 0.30.0, this used to accept a number, which specified the size
+    of the cache in kilobytes. Use e.g. ``--cache --demuxer-max-bytes=123k``
+    instead.
+
+``--no-cache``
+    Turn off input stream caching. See ``--cache``.
+
+``--cache-secs=<seconds>``
+    How many seconds of audio/video to prefetch if the cache is active. This
+    overrides the ``--demuxer-readahead-secs`` option if and only if the cache
+    is enabled and the value is larger. The default value is set to something
+    very high, so the actually achieved readahead will usually be limited by
+    the value of the ``--demuxer-max-bytes`` option. Setting this option is
+    usually only useful for limiting readahead.
+
+``--cache-on-disk=<yes|no>``
+    Write packet data to a temporary file, instead of keeping them in memory.
+    This makes sense only with ``--cache``. If the normal cache is disabled,
+    this option is ignored.
+
+    The cache file is append-only. Even if the player appears to prune data, the
+    file space freed by it is not reused. The cache file is deleted when
+    playback is closed.
+
+    Note that packet metadata is still kept in memory. ``--demuxer-max-bytes``
+    and related options are applied to metadata *only*. The size of this
+    metadata  varies, but 50 MB per hour of media is typical. The cache
+    statistics will report this metadats size, instead of the size of the cache
+    file. If the metadata hits the size limits, the metadata is pruned (but not
+    the cache file).
+
+    When the media is closed, the cache file is deleted. A cache file is
+    generally worthless after the media is closed, and it's hard to retrieve
+    any media data from it (it's not supported by design).
+
+    If the option is enabled at runtime, the cache file is created, but old data
+    will remain in the memory cache. If the option is disabled at runtime, old
+    data remains in the disk cache, and the cache file is not closed until the
+    media is closed. If the option is disabled and enabled again, it will
+    continue to use the cache file that was opened first.
+
+``--demuxer-cache-dir=<path>``
+    Directory where to create temporary files. Cache is stored in the system's
+    cache directory (usually ``~/.cache/mpv``) if this is unset.
+
+    Currently, this is used for ``--cache-on-disk`` only.
+
+``--cache-pause=<yes|no>``
+    Whether the player should automatically pause when the cache runs out of
+    data and stalls decoding/playback (default: yes). If enabled, it will
+    pause and unpause once more data is available, aka "buffering".
+
+``--cache-pause-wait=<seconds>``
+    Number of seconds the packet cache should have buffered before starting
+    playback again if "buffering" was entered (default: 1). This can be used
+    to control how long the player rebuffers if ``--cache-pause`` is enabled,
+    and the demuxer underruns. If the given time is higher than the maximum
+    set with ``--cache-secs`` or  ``--demuxer-readahead-secs``, or prefetching
+    ends before that for some other reason (like file end or maximum configured
+    cache size reached), playback resumes earlier.
+
+``--cache-pause-initial=<yes|no>``
+    Enter "buffering" mode before starting playback (default: no). This can be
+    used to ensure playback starts smoothly, in exchange for waiting some time
+    to prefetch network data (as controlled by ``--cache-pause-wait``). For
+    example, some common behavior is that playback starts, but network caches
+    immediately underrun when trying to decode more data as playback progresses.
+
+    Another thing that can happen is that the network prefetching is so CPU
+    demanding (due to demuxing in the background) that playback drops frames
+    at first. In these cases, it helps enabling this option, and setting
+    ``--cache-secs`` and ``--cache-pause-wait`` to roughly the same value.
+
+    This option also triggers when playback is restarted after seeking.
+
+``--demuxer-cache-unlink-files=<immediate|whendone|no>``
+    Whether or when to unlink cache files (default: immediate). This affects
+    cache files which are inherently temporary, and which make no sense to
+    remain on disk after the player terminates. This is a debugging option.
+
+    ``immediate``
+        Unlink cache file after they were created. The cache files won't be
+        visible anymore, even though they're in use. This ensures they are
+        guaranteed to be removed from disk when the player terminates, even if
+        it crashes.
+
+    ``whendone``
+        Delete cache files after they are closed.
+
+    ``no``
+        Don't delete cache files. They will consume disk space without having a
+        use.
+
+    Currently, this is used for ``--cache-on-disk`` only.
+
+``--stream-buffer-size=<bytesize>``
+    Size of the low level stream byte buffer (default: 128KB). This is used as
+    buffer between demuxer and low level I/O (e.g. sockets). Generally, this
+    can be very small, and the main purpose is similar to the internal buffer
+    FILE in the C standard library will have.
+
+    Half of the buffer is always used for guaranteed seek back, which is
+    important for unseekable input.
+
+    There are known cases where this can help performance to set a large buffer:
+
+        1. mp4 files. libavformat may trigger many small seeks in both
+           directions, depending on how the file was muxed.
+
+        2. Certain network filesystems, which do not have a cache, and where
+           small reads can be inefficient.
+
+    In other cases, setting this to a large value can reduce performance.
+
+    Usually, read accesses are at half the buffer size, but it may happen that
+    accesses are done alternating with smaller and larger sizes (this is due to
+    the internal ring buffer wrap-around).
+
+    See ``--list-options`` for defaults and value range. ``<bytesize>`` options
+    accept suffixes such as ``KiB`` and ``MiB``.
+
+``--vd-queue-enable=<yes|no>, --ad-queue-enable``
+    Enable running the video/audio decoder on a separate thread (default: no).
+    If enabled, the decoder is run on a separate thread, and a frame queue is
+    put between decoder and higher level playback logic. The size of the frame
+    queue is defined by the other options below.
+
+    This is probably quite pointless. libavcodec already has multithreaded
+    decoding (enabled by default), which makes this largely unnecessary. It
+    might help in some corner cases with high bandwidth video that is slow to
+    decode (in these cases libavcodec would block the playback logic, while
+    using a decoding thread would distribute the decoding time evenly without
+    affecting the playback logic). In other situations, it will simply make
+    seeking slower and use significantly more memory.
+
+    The queue size is restricted by the other ``--vd-queue-...`` options. The
+    final queue size is the minimum as indicated by the option with the lowest
+    limit. Each decoder/track has its own queue that may use the full configured
+    queue size.
+
+    Most queue options can be changed at runtime. ``--vd-queue-enable`` itself
+    (and the audio equivalent) update only if decoding is completely
+    reinitialized. However, setting ``--vd-queue-max-samples=1`` should almost
+    lead to the same behavior as ``--vd-queue-enable=no``, so that value can
+    be used for effectively runtime enabling/disabling the queue.
+
+    This should not be used with hardware decoding. It is possible to enable
+    this for audio, but it makes even less sense.
+
+``--vd-queue-max-bytes=<bytesize>``, ``--ad-queue-max-bytes``
+    Maximum approximate allowed size of the queue. If exceeded, decoding will
+    be stopped. The maximum size can be exceeded by about 1 frame.
+
+    See ``--list-options`` for defaults and value range. ``<bytesize>`` options
+    accept suffixes such as ``KiB`` and ``MiB``.
+
+``--vd-queue-max-samples=<int>``, ``--ad-queue-max-samples``
+    Maximum number of frames (video) or samples (audio) of the queue. The audio
+    size may be exceeded by about 1 frame.
+
+    See ``--list-options`` for defaults and value range.
+
+``--vd-queue-max-secs=<seconds>``, ``--ad-queue-max-secs``
+    Maximum number of seconds of media in the queue. The special value 0 means
+    no limit is set. The queue size may be exceeded by about 2 frames. Timestamp
+    resets may lead to random queue size usage.
+
+    See ``--list-options`` for defaults and value range.
+
+Network
+-------
+
+``--user-agent=<string>``
+    Use ``<string>`` as user agent for HTTP streaming.
+
+``--cookies``, ``--no-cookies``
+    Support cookies when making HTTP requests. Disabled by default.
+
+``--cookies-file=<filename>``
+    Read HTTP cookies from <filename>. The file is assumed to be in Netscape
+    format.
+
+``--http-header-fields=<field1,field2>``
+    Set custom HTTP fields when accessing HTTP stream.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Example
+
+        ::
+
+            mpv --http-header-fields='Field1: value1','Field2: value2' \
+            http://localhost:1234
+
+        Will generate HTTP request::
+
+            GET / HTTP/1.0
+            Host: localhost:1234
+            User-Agent: MPlayer
+            Icy-MetaData: 1
+            Field1: value1
+            Field2: value2
+            Connection: close
+
+``--http-proxy=<proxy>``
+    URL of the HTTP/HTTPS proxy. If this is set, the ``http_proxy`` environment
+    is ignored. The ``no_proxy`` environment variable is still respected. This
+    option is silently ignored if it does not start with ``http://``. Proxies
+    are not used for https URLs. Setting this option does not try to make the
+    ytdl script use the proxy.
+
+``--tls-ca-file=<filename>``
+    Certificate authority database file for use with TLS. (Silently fails with
+    older FFmpeg or Libav versions.)
+
+``--tls-verify``
+    Verify peer certificates when using TLS (e.g. with ``https://...``).
+    (Silently fails with older FFmpeg or Libav versions.)
+
+``--tls-cert-file``
+    A file containing a certificate to use in the handshake with the
+    peer.
+
+``--tls-key-file``
+    A file containing the private key for the certificate.
+
+``--referrer=<string>``
+    Specify a referrer path or URL for HTTP requests.
+
+``--network-timeout=<seconds>``
+    Specify the network timeout in seconds (default: 60 seconds). This affects
+    at least HTTP. The special value 0 uses the FFmpeg/Libav defaults. If a
+    protocol is used which does not support timeouts, this option is silently
+    ignored.
+
+    .. warning::
+
+        This breaks the RTSP protocol, because of inconsistent FFmpeg API
+        regarding its internal timeout option. Not only does the RTSP timeout
+        option accept different units (seconds instead of microseconds, causing
+        mpv to pass it huge values), it will also overflow FFmpeg internal
+        calculations. The worst is that merely setting the option will put RTSP
+        into listening mode, which breaks any client uses. At time of this
+        writing, the fix was not made effective yet. For this reason, this
+        option is ignored (or should be ignored) on RTSP URLs. You can still
+        set the timeout option directly with ``--demuxer-lavf-o``.
+
+``--rtsp-transport=<lavf|udp|udp_multicast|tcp|http>``
+    Select RTSP transport method (default: tcp). This selects the underlying
+    network transport when playing ``rtsp://...`` URLs. The value ``lavf``
+    leaves the decision to libavformat.
+
+``--hls-bitrate=<no|min|max|<rate>>``
+    If HLS streams are played, this option controls what streams are selected
+    by default. The option allows the following parameters:
+
+    :no:        Don't do anything special. Typically, this will simply pick the
+                first audio/video streams it can find.
+    :min:       Pick the streams with the lowest bitrate.
+    :max:       Same, but highest bitrate. (Default.)
+
+    Additionally, if the option is a number, the stream with the highest rate
+    equal or below the option value is selected.
+
+    The bitrate as used is sent by the server, and there's no guarantee it's
+    actually meaningful.
+
+DVB
+---
+
+``--dvbin-prog=<string>``
+    This defines the program to tune to. Usually, you may specify this
+    by using a stream URI like ``"dvb://ZDF HD"``, but you can tune to a
+    different channel by writing to this property at runtime.
+    Also see ``dvbin-channel-switch-offset`` for more useful channel
+    switching functionality.
+
+``--dvbin-card=<0-15>``
+    Specifies using card number 0-15 (default: 0).
+
+``--dvbin-file=<filename>``
+    Instructs mpv to read the channels list from ``<filename>``. The default is
+    in the mpv configuration directory (usually ``~/.config/mpv``) with the
+    filename ``channels.conf.{sat,ter,cbl,atsc,isdbt}`` (based on your card
+    type) or ``channels.conf`` as a last resort.
+    Please note that using specific file name with card type is recommended,
+    since the legacy channel format is not fully standardized
+    so autodetection of the delivery system may fail otherwise.
+    For DVB-S/2 cards, a VDR 1.7.x format channel list is recommended
+    as it allows tuning to DVB-S2 channels, enabling subtitles and
+    decoding the PMT (which largely improves the demuxing).
+    Classic mplayer format channel lists are still supported (without
+    these improvements), and for other card types, only limited VDR
+    format channel list support is implemented (patches welcome).
+    For channels with dynamic PID switching or incomplete
+    ``channels.conf``, ``--dvbin-full-transponder`` or the magic PID
+    ``8192`` are recommended.
+
+``--dvbin-timeout=<1-30>``
+    Maximum number of seconds to wait when trying to tune a frequency before
+    giving up (default: 30).
+
+``--dvbin-full-transponder=<yes|no>``
+    Apply no filters on program PIDs, only tune to frequency and pass full
+    transponder to demuxer.
+    The player frontend selects the streams from the full TS in this case,
+    so the program which is shown initially may not match the chosen channel.
+    Switching between the programs is possible by cycling the ``program``
+    property.
+    This is useful to record multiple programs on a single transponder,
+    or to work around issues in the ``channels.conf``.
+    It is also recommended to use this for channels which switch PIDs
+    on-the-fly, e.g. for regional news.
+
+    Default: ``no``
+
+``--dvbin-channel-switch-offset=<integer>``
+    This value is not meant for setting via configuration, but used in channel
+    switching. An ``input.conf`` can ``cycle`` this value ``up`` and ``down``
+    to perform channel switching. This number effectively gives the offset
+    to the initially tuned to channel in the channel list.
+
+    An example ``input.conf`` could contain:
+    ``H cycle dvbin-channel-switch-offset up``, ``K cycle dvbin-channel-switch-offset down``
+
+ALSA audio output options
+-------------------------
+
+
+``--alsa-device=<device>``
+    Deprecated, use ``--audio-device`` (requires ``alsa/`` prefix).
+
+``--alsa-resample=yes``
+    Enable ALSA resampling plugin. (This is disabled by default, because
+    some drivers report incorrect audio delay in some cases.)
+
+``--alsa-mixer-device=<device>``
+    Set the mixer device used with ``ao-volume`` (default: ``default``).
+
+``--alsa-mixer-name=<name>``
+    Set the name of the mixer element (default: ``Master``). This is for
+    example ``PCM`` or ``Master``.
+
+``--alsa-mixer-index=<number>``
+    Set the index of the mixer channel (default: 0). Consider the output of
+    "``amixer scontrols``", then the index is the number that follows the
+    name of the element.
+
+``--alsa-non-interleaved``
+    Allow output of non-interleaved formats (if the audio decoder uses
+    this format). Currently disabled by default, because some popular
+    ALSA plugins are utterly broken with non-interleaved formats.
+
+``--alsa-ignore-chmap``
+    Don't read or set the channel map of the ALSA device - only request the
+    required number of channels, and then pass the audio as-is to it. This
+    option most likely should not be used. It can be useful for debugging,
+    or for static setups with a specially engineered ALSA configuration (in
+    this case you should always force the same layout with ``--audio-channels``,
+    or it will work only for files which use the layout implicit to your
+    ALSA device).
+
+``--alsa-buffer-time=<microseconds>``
+    Set the requested buffer time in microseconds. A value of 0 skips requesting
+    anything from the ALSA API. This and the ``--alsa-periods`` option uses the
+    ALSA ``near`` functions to set the requested parameters. If doing so results
+    in an empty configuration set, setting these parameters is skipped.
+
+    Both options control the buffer size. A low buffer size can lead to higher
+    CPU usage and audio dropouts, while a high buffer size can lead to higher
+    latency in volume changes and other filtering.
+
+``--alsa-periods=<number>``
+    Number of periods requested from the ALSA API. See ``--alsa-buffer-time``
+    for further remarks.
+
+
+GPU renderer options
+-----------------------
+
+The following video options are currently all specific to ``--vo=gpu``,
+``--vo=libmpv`` and ``--vo=gpu-next``, which are the only VOs that implement
+them.
+
+``--scale=<filter>``
+    The filter function to use when upscaling video.
+
+    ``bilinear``
+        Bilinear hardware texture filtering (fastest, very low quality). This is
+        the default when using the ``fast`` profile.
+
+    ``lanczos``
+        Lanczos scaling. Provides good balance between quality and performance.
+        This is the default for ``scale``. The number of taps can be controlled
+        with ``scale-radius``, but is best left unchanged.
+
+        (This filter is an alias for ``sinc``-windowed ``sinc``)
+
+    ``ewa_lanczos``
+        Elliptic weighted average Lanczos scaling. Also known as Jinc.
+        Relatively slow, but very good quality. The radius can be controlled
+        with ``scale-radius``. Increasing the radius makes the filter sharper
+        but adds more ringing.
+
+        (This filter is an alias for ``jinc``-windowed ``jinc``)
+
+    ``ewa_lanczossharp``
+        A slightly sharpened version of ewa_lanczos. This is the default when
+        using the ``high-quality`` profile.
+
+    ``ewa_lanczos4sharpest``
+        Very sharp scaler, but also slightly slower than ``ewa_lanczossharp``.
+        Prone to ringing, so it's recommended to combine this with an
+        anti-ringing shader. On ``--vo=gpu-next``, setting this filter enables
+        built-in anti-ringing, so no extra action needs to be taken.
+
+    ``mitchell``
+        Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with
+        ``--scale-param1`` and ``--scale-param2``.
+
+    ``hermite``
+        Hermite spline. Similar to ``bicubic`` but with ``B`` set to ``0.0``.
+        This filter has the special property of having a support of radius 1.0,
+        making it very fast in comparison, but prone to blocking. This is the
+        default for ``--dscale``.
+
+    ``catmull_rom``
+        Catmull-Rom. A Cubic filter in the same vein as ``mitchell``, where
+        the ``B`` and ``C`` parameters are ``0.0`` and ``0.5`` respectively.
+        This filter is sharper than ``mitchell``, but it results in more
+        ringing.
+
+    ``oversample``
+        A version of nearest neighbour that (naively) oversamples pixels, so
+        that pixels overlapping edges get linearly interpolated instead of
+        rounded. This essentially removes the small imperfections and judder
+        artifacts caused by nearest-neighbour interpolation, in exchange for
+        adding some blur. This can also be used for frame mixing, where it
+        is commonly known as "smoothmotion" (see ``--tscale``).
+
+    ``linear``
+        A ``--tscale`` filter.
+
+    There are some more filters, but most are not as useful. For a complete
+    list, pass ``help`` as value, e.g.::
+
+        mpv --scale=help
+
+``--cscale=<filter>``
+    As ``--scale``, but for interpolating chroma information. If the image is
+    not subsampled, this option is ignored entirely. If this option is unset,
+    the filter implied by ``--scale`` will be applied.
+
+``--dscale=<filter>``
+    Like ``--scale``, but apply these filters on downscaling instead.
+
+``--tscale=<filter>``
+    The filter used for interpolating the temporal axis (frames). This is only
+    used if ``--interpolation`` is enabled. The only valid choices for
+    ``--tscale`` are separable convolution filters (use ``--tscale=help`` to
+    get a list). The default is ``oversample``.
+
+    Common ``--tscale`` choices include ``oversample``, ``linear``,
+    ``catmull_rom``, ``mitchell``, ``gaussian``, or ``bicubic``. These are
+    listed in increasing order of smoothness/blurriness, with ``bicubic``
+    being the smoothest/blurriest and ``oversample`` being the sharpest/least
+    smooth.
+
+``--scale-param1=<value>``, ``--scale-param2=<value>``, ``--cscale-param1=<value>``, ``--cscale-param2=<value>``, ``--dscale-param1=<value>``, ``--dscale-param2=<value>``, ``--tscale-param1=<value>``, ``--tscale-param2=<value>``
+    Set filter parameters. By default, these are set to the special string
+    ``default``, which maps to a scaler-specific default value. Ignored if the
+    filter is not tunable. Currently, this affects the following filter
+    parameters:
+
+    bicubic
+        Spline parameters (``B`` and ``C``). Defaults to B=1 and C=0.
+
+    gaussian
+        Scale parameter (``t``). Increasing this makes the result blurrier.
+        Defaults to 1.
+
+    oversample
+        Minimum distance to an edge before interpolation is used. Setting this
+        to 0 will always interpolate edges, whereas setting it to 0.5 will
+        never interpolate, thus behaving as if the regular nearest neighbour
+        algorithm was used. Defaults to 0.0.
+
+``--scale-blur=<value>``, ``--cscale-blur=<value>``, ``--dscale-blur=<value>``, ``--tscale-blur=<value>``
+    Kernel scaling factor (also known as a blur factor). Decreasing this makes
+    the result sharper, increasing it makes it blurrier (default 0). If set to
+    0, the kernel's preferred blur factor is used. Note that setting this too
+    low (eg. 0.5) leads to bad results. It's generally recommended to stick to
+    values between 0.8 and 1.2.
+
+``--scale-clamp=<0.0-1.0>``, ``--cscale-clamp``, ``--dscale-clamp``, ``--tscale-clamp``
+    Specifies a weight bias to multiply into negative coefficients. Specifying
+    ``--scale-clamp=1`` has the effect of removing negative weights completely,
+    thus effectively clamping the value range to [0-1]. Values between 0.0 and
+    1.0 can be specified to apply only a moderate diminishment of negative
+    weights. This is especially useful for ``--tscale``, where it reduces
+    excessive ringing artifacts in the temporal domain (which typically
+    manifest themselves as short flashes or fringes of black, mostly around
+    moving edges) in exchange for potentially adding more blur. The default for
+    ``--tscale-clamp`` is 1.0, the others default to 0.0.
+
+``--scale-taper=<value>``, ``--scale-wtaper=<value>``, ``--dscale-taper=<value>``, ``--dscale-wtaper=<value>``, ``--cscale-taper=<value>``, ``--cscale-wtaper=<value>``, ``--tscale-taper=<value>``, ``--tscale-wtaper=<value>``
+    Kernel/window taper factor. Increasing this flattens the filter function.
+    Value range is 0 to 1. A value of 0 (the default) means no flattening, a
+    value of 1 makes the filter completely flat (equivalent to a box function).
+    Values in between mean that some portion will be flat and the actual filter
+    function will be squeezed into the space in between.
+
+``--scale-radius=<value>``, ``--cscale-radius=<value>``, ``--dscale-radius=<value>``, ``--tscale-radius=<value>``
+    Set radius for tunable filters, must be a float number between 0.5 and
+    16.0. Defaults to the filter's preferred radius if not specified. Doesn't
+    work for every scaler and VO combination.
+
+    Note that depending on filter implementation details and video scaling
+    ratio, the radius that actually being used might be different (most likely
+    being increased a bit).
+
+``--scale-antiring=<value>``, ``--cscale-antiring=<value>``, ``--dscale-antiring=<value>``, ``--tscale-antiring=<value>``
+    Set the antiringing strength. This tries to eliminate ringing, but can
+    introduce other artifacts in the process. Must be a float number between
+    0.0 and 1.0. The default value of 0.0 disables antiringing entirely.
+
+    Note that this doesn't affect the special filters ``bilinear`` and
+    ``bicubic_fast``, nor does it affect any polar (EWA) scalers.
+
+``--scale-window=<window>``, ``--cscale-window=<window>``, ``--dscale-window=<window>``, ``--tscale-window=<window>``
+    (Advanced users only) Choose a custom windowing function for the kernel.
+    Defaults to the filter's preferred window if unset. Use
+    ``--scale-window=help`` to get a list of supported windowing functions.
+
+``--scale-wparam=<window>``, ``--cscale-wparam=<window>``, ``--cscale-wparam=<window>``, ``--tscale-wparam=<window>``
+    (Advanced users only) Configure the parameter for the window function given
+    by ``--scale-window`` etc. By default, these are set to the special string
+    ``default``, which maps to a window-specific default value. Ignored if the
+    window is not tunable. Currently, this affects the following window
+    parameters:
+
+    kaiser
+        Window parameter (alpha). Defaults to 6.33.
+    blackman
+        Window parameter (alpha). Defaults to 0.16.
+    gaussian
+        Scale parameter (t). Increasing this makes the window wider. Defaults
+        to 1.
+
+``--scaler-resizes-only``
+    Disable the scaler if the video image is not resized. In that case,
+    ``bilinear`` is used instead of whatever is set with ``--scale``. Bilinear
+    will reproduce the source image perfectly if no scaling is performed.
+    Enabled by default. Note that this option never affects ``--cscale``.
+
+``--correct-downscaling``
+    When using convolution based filters, extend the filter size when
+    downscaling. Increases quality, but reduces performance while downscaling.
+    Enabled by default.
+
+    This will perform slightly sub-optimally for anamorphic video (but still
+    better than without it) since it will extend the size to match only the
+    milder of the scale factors between the axes.
+
+    Note: this option is ignored when using bilinear downscaling with ``--vo=gpu``.
+
+``--linear-downscaling``
+    Scale in linear light when downscaling. It should only be used with a
+    ``--fbo-format`` that has at least 16 bit precision. This option
+    has no effect on HDR content. Enabled by default.
+
+``--linear-upscaling``
+    Scale in linear light when upscaling. Like ``--linear-downscaling``, it
+    should only be used with a ``--fbo-format`` that has at least 16 bits
+    precisions. This is not usually recommended except for testing/specific
+    purposes. Users are advised to either enable ``--sigmoid-upscaling`` or
+    keep both options disabled (i.e. scaling in gamma light).
+
+``--sigmoid-upscaling``
+    When upscaling, use a sigmoidal color transform to avoid emphasizing
+    ringing artifacts. Enabled by default. This is incompatible with and replaces
+    ``--linear-upscaling``. (Note that sigmoidization also requires
+    linearization, so the ``LINEAR`` rendering step fires in both cases)
+
+``--sigmoid-center``
+    The center of the sigmoid curve used for ``--sigmoid-upscaling``, must be a
+    float between 0.0 and 1.0. Defaults to 0.75 if not specified.
+
+``--sigmoid-slope``
+    The slope of the sigmoid curve used for ``--sigmoid-upscaling``, must be a
+    float between 1.0 and 20.0. Defaults to 6.5 if not specified.
+
+``--interpolation``
+    Reduce stuttering caused by mismatches in the video fps and display refresh
+    rate (also known as judder).
+
+    .. warning:: This requires setting the ``--video-sync`` option to one
+                 of the ``display-`` modes, or it will be silently disabled.
+                 This was not required before mpv 0.14.0.
+
+    This essentially attempts to interpolate the missing frames by convoluting
+    the video along the temporal axis. The filter used can be controlled using
+    the ``--tscale`` setting.
+
+``--interpolation-threshold=<0..1,-1>``
+    Threshold below which frame ratio interpolation gets disabled (default:
+    ``0.01``). This is calculated as ``abs(disphz/vfps - 1) < threshold``,
+    where ``vfps`` is the speed-adjusted video FPS, and ``disphz`` the
+    display refresh rate. (The speed-adjusted video FPS is roughly equal to
+    the normal video FPS, but with slowdown and speedup applied. This matters
+    if you use ``--video-sync=display-resample`` to make video run synchronously
+    to the display FPS, or if you change the ``speed`` property.)
+
+    The default is intended to enable interpolation in scenarios where
+    retiming with the ``--video-sync=display-*`` cannot adjust the speed of
+    the video sufficiently for smooth playback. For example if a video is
+    60.00 FPS and your display refresh rate is 59.94 Hz, interpolation will
+    never be activated, since the mismatch is within 1% of the refresh
+    rate. The default also handles the scenario when mpv cannot determine the
+    container FPS, such as during certain live streams, and may dynamically
+    toggle interpolation on and off. In this scenario, the default would be to
+    not use interpolation but rather to allow ``--video-sync=display-*`` to
+    retime the video to match display refresh rate. See
+    ``--video-sync-max-video-change`` for more information about how mpv
+    will retime video.
+
+    Also note that if you use e.g. ``--video-sync=display-vdrop``, small
+    deviations in the rate can disable interpolation and introduce a
+    discontinuity every other minute.
+
+    Set this to ``-1`` to disable this logic.
+
+``--interpolation-preserve``
+    Preserve the previous frames' interpolated results even when renderer
+    parameters are changed - with the exception of options related to
+    cropping and video placement, which always invalidate the cache. Enabling
+    this option makes dynamic updates of renderer settings slightly smoother at
+    the cost of slightly higher latency in response to such changes. Defaults
+    to on. (Only affects ``--vo=gpu-next``, note that ``--vo=gpu`` always
+    invalidates interpolated frames)
+
+``--opengl-pbo``
+    Enable use of PBOs. On some drivers this can be faster, especially if the
+    source video size is huge (e.g. so called "4K" video). On other drivers it
+    might be slower or cause latency issues.
+
+``--dither-depth=<N|no|auto>``
+    Set dither target depth to N. Default: auto.
+
+    no
+        Disable any dithering done by mpv.
+    auto
+        Automatic selection. If output bit depth cannot be detected, 8 bits per
+        component are assumed.
+    8
+        Dither to 8 bit output.
+
+    Note that the depth of the connected video display device cannot be
+    detected. Often, LCD panels will do dithering on their own, which conflicts
+    with this option and leads to ugly output.
+
+``--dither-size-fruit=<2-8>``
+    Set the size of the dither matrix (default: 6). The actual size of the
+    matrix is ``(2^N) x (2^N)`` for an option value of ``N``, so a value of 6
+    gives a size of 64x64. The matrix is generated at startup time, and a large
+    matrix can take rather long to compute (seconds).
+
+    Used in ``--dither=fruit`` mode only.
+
+``--dither=<fruit|ordered|error-diffusion|no>``
+    Select dithering algorithm (default: fruit). (Normally, the
+    ``--dither-depth`` option controls whether dithering is enabled.)
+
+    The ``error-diffusion`` option requires compute shader support. It also
+    requires large amount of shared memory to run, the size of which depends on
+    both the kernel (see ``--error-diffusion`` option below) and the height of
+    video window. It will fallback to ``fruit`` dithering if there is no enough
+    shared memory to run the shader.
+
+``--temporal-dither``
+    Enable temporal dithering. (Only active if dithering is enabled in
+    general.) This changes between 8 different dithering patterns on each frame
+    by changing the orientation of the tiled dithering matrix. Unfortunately,
+    this can lead to flicker on LCD displays, since these have a high reaction
+    time.
+
+``--temporal-dither-period=<1-128>``
+    Determines how often the dithering pattern is updated when
+    ``--temporal-dither`` is in use. 1 (the default) will update on every video
+    frame, 2 on every other frame, etc.
+
+``--error-diffusion=<kernel>``
+    The error diffusion kernel to use when ``--dither=error-diffusion`` is set.
+
+    ``simple``
+        Propagate error to only two adjacent pixels. Fastest but low quality.
+
+    ``sierra-lite``
+        Fast with reasonable quality. This is the default.
+
+    ``floyd-steinberg``
+        Most notable error diffusion kernel.
+
+    ``atkinson``
+        Looks different from other kernels because only fraction of errors will
+        be propagated during dithering. A typical use case of this kernel is
+        saving dithered screenshot (in window mode). This kernel produces
+        slightly smaller file, with still reasonable dithering quality.
+
+    There are other kernels (use ``--error-diffusion=help`` to list) but most of
+    them are much slower and demanding even larger amount of shared memory.
+    Among these kernels, ``burkes`` achieves a good balance between performance
+    and quality, and probably is the one you want to try first.
+
+``--gpu-debug``
+    Enables GPU debugging. What this means depends on the API type. For OpenGL,
+    it calls ``glGetError()``, and requests a debug context. For Vulkan, it
+    enables validation layers.
+
+``--opengl-swapinterval=<n>``
+    Interval in displayed frames between two buffer swaps. 1 is equivalent to
+    enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified.
+
+    Note that this depends on proper OpenGL vsync support. On some platforms
+    and drivers, this only works reliably when in fullscreen mode. It may also
+    require driver-specific hacks if using multiple monitors, to ensure mpv
+    syncs to the right one. Compositing window managers can also lead to bad
+    results, as can missing or incorrect display FPS information (see
+    ``--display-fps-override``).
+
+``--vulkan-device=<device name|UUID>``
+    The name or UUID of the Vulkan device to use for rendering and presentation. Use
+    ``--vulkan-device=help`` to see the list of available devices and their
+    names and UUIDs. If left unspecified, the first enumerated hardware Vulkan
+    device will be used.
+
+``--vulkan-swap-mode=<mode>``
+    Controls the presentation mode of the vulkan swapchain. This is similar
+    to the ``--opengl-swapinterval`` option.
+
+    auto
+        Use the preferred swapchain mode for the vulkan context. (Default)
+    fifo
+        Non-tearing, vsync blocked. Similar to "VSync on".
+    fifo-relaxed
+        Tearing, vsync blocked. Late frames will tear instead of stuttering.
+    mailbox
+        Non-tearing, not vsync blocked. Similar to "triple buffering".
+    immediate
+        Tearing, not vsync blocked. Similar to "VSync off".
+
+``--vulkan-queue-count=<1..8>``
+    Controls the number of VkQueues used for rendering (limited by how many
+    your device supports). In theory, using more queues could enable some
+    parallelism between frames (when using a ``--swapchain-depth`` higher than
+    1), but it can also slow things down on hardware where there's no true
+    parallelism between queues. (Default: 1)
+
+``--vulkan-async-transfer``
+    Enables the use of async transfer queues on supported vulkan devices. Using
+    them allows transfer operations like texture uploads and blits to happen
+    concurrently with the actual rendering, thus improving overall throughput
+    and power consumption. Enabled by default, and should be relatively safe.
+
+``--vulkan-async-compute``
+    Enables the use of async compute queues on supported vulkan devices. Using
+    this, in theory, allows out-of-order scheduling of compute shaders with
+    graphics shaders, thus enabling the hardware to do more effective work while
+    waiting for pipeline bubbles and memory operations. Not beneficial on all
+    GPUs. It's worth noting that if async compute is enabled, and the device
+    supports more compute queues than graphics queues (bound by the restrictions
+    set by ``--vulkan-queue-count``), mpv will internally try and prefer the
+    use of compute shaders over fragment shaders wherever possible. Enabled by
+    default, although Nvidia users may want to disable it.
+
+``--vulkan-display-display=<n>``
+    The index of the display, on the selected Vulkan device, to present on when
+    using the ``displayvk`` GPU context. Use ``--vulkan-display-display=help``
+    to see the list of available displays. If left unspecified, the first
+    enumerated display will be used.
+
+
+``--vulkan-display-mode=<n>``
+    The index of the display mode, of the selected Vulkan display, to use when
+    using the ``displayvk`` GPU context. Use ``--vulkan-display-mode=help``
+    to see the list of available modes. If left unspecified, the first
+    enumerated mode will be used.
+
+``--vulkan-display-plane=<n>``
+    The index of the plane, on the selected Vulkan device, to present on when
+    using the ``displayvk`` GPU context. Use ``--vulkan-display-plane=help``
+    to see the list of available planes. If left unspecified, the first
+    enumerated plane will be used.
+
+``--d3d11-exclusive-fs=<yes|no>``
+    Switches the D3D11 swap chain fullscreen state to 'fullscreen' when
+    fullscreen video is requested. Also known as "exclusive fullscreen" or
+    "D3D fullscreen" in other applications. Gives mpv full control of
+    rendering on the swap chain's screen. Off by default.
+
+``--d3d11-warp=<yes|no|auto>``
+    Use WARP (Windows Advanced Rasterization Platform) with the D3D11 GPU
+    backend (default: auto). This is a high performance software renderer. By
+    default, it is only used when the system has no hardware adapters that
+    support D3D11. While the extended GPU features will work with WARP, they
+    can be very slow.
+
+``--d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>``
+    Select a specific feature level when using the D3D11 GPU backend. By
+    default, the highest available feature level is used. This option can be
+    used to select a lower feature level, which is mainly useful for debugging.
+    Most extended GPU features will not work at 9_x feature levels.
+
+``--d3d11-flip=<yes|no>``
+    Enable flip-model presentation, which avoids unnecessarily copying the
+    backbuffer by sharing surfaces with the DWM (default: yes). This may cause
+    performance issues with older drivers. If flip-model presentation is not
+    supported (for example, on Windows 7 without the platform update), mpv will
+    automatically fall back to the older bitblt presentation model.
+
+``--d3d11-sync-interval=<0..4>``
+    Schedule each frame to be presented for this number of VBlank intervals.
+    (default: 1) Setting to 1 will enable VSync, setting to 0 will disable it.
+
+``--d3d11-adapter=<adapter name|help>``
+    Select a specific D3D11 adapter to utilize for D3D11 rendering.
+    Will pick the default adapter if unset. Alternatives are listed
+    when the name "help" is given.
+
+    Checks for matches based on the start of the string, case
+    insensitive. Thus, if the description of the adapter starts with
+    the vendor name, that can be utilized as the selection parameter.
+
+    Hardware decoders utilizing the D3D11 rendering abstraction's helper
+    functionality to receive a device, such as D3D11VA or DXVA2's DXGI
+    mode, will be affected by this choice.
+
+``--d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>``
+    Select a specific D3D11 output format to utilize for D3D11 rendering.
+    "auto" is the default, which will pick either rgba8 or rgb10_a2 depending
+    on the configured desktop bit depth. rgba16f and bgra8 are left out of
+    the autodetection logic, and are available for manual testing.
+
+    .. note::
+
+        Desktop bit depth querying is only available from an API available
+        from Windows 10. Thus on older systems it will only automatically
+        utilize the rgba8 output format.
+
+``--d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>``
+    Select a specific D3D11 output color space to utilize for D3D11 rendering.
+    "auto" is the default, which will select the color space of the desktop
+    on which the swap chain is located.
+
+    Values other than "srgb" and "pq" have had issues in testing, so they
+    are mostly available for manual testing.
+
+    .. note::
+
+        Swap chain color space configuration is only available from an API
+        available from Windows 10. Thus on older systems it will not work.
+
+``--d3d11va-zero-copy=<yes|no>``
+    By default, when using hardware decoding with ``--gpu-api=d3d11``, the
+    video image will be copied (GPU-to-GPU) from the decoder surface to a
+    shader resource. Set this option to avoid that copy by sampling directly
+    from the decoder image. This may increase performance and reduce power
+    usage, but can cause the image to be sampled incorrectly on the bottom and
+    right edges due to padding, and may invoke driver bugs, since Direct3D 11
+    technically does not allow sampling from a decoder surface (though most
+    drivers support it.)
+
+    Currently only relevant for ``--gpu-api=d3d11``.
+
+``--wayland-app-id=<string>``
+    Set the client app id for Wayland-based video output methods (default: ``mpv``).
+
+``--wayland-configure-bounds=<auto|yes|no>``
+    Controls whether or not mpv opts into the configure bounds event if sent by the
+    compositor (default: auto). This restricts the initial size of the mpv window to
+    a certain maximum size intended by the compositor. In most cases, this simply
+    just prevents the mpv window from being larger than the size of the monitor when
+    it first renders. With the default value of ``auto``, configure-bounds will
+    silently be ignored if any ``autofit`` or ``geometry`` type option is also set.
+
+``--wayland-content-type=<auto|none|photo|video|game>``
+    If supported by the compositor, mpv will send a hint using the content-type
+    protocol telling the compositor what type of content is being displayed. ``auto``
+    (default) will automatically switch between telling the compositor the content
+    is a photo, video or possibly none depending on internal heuristics.
+
+``--wayland-disable-vsync=<yes|no>``
+    Disable mpv's internal vsync for Wayland-based video output (default: no).
+    This is mainly useful for benchmarking wayland VOs when combined with
+    ``video-sync=display-desync``, ``--no-audio``, and ``--untimed=yes``.
+
+``--wayland-edge-pixels-pointer=<value>``
+    Defines the size of an edge border (default: 16) to initiate client side
+    resize events in the wayland contexts with the mouse. This is only active if
+    there are no server side decorations from the compositor.
+
+``--wayland-edge-pixels-touch=<value>``
+    Defines the size of an edge border (default: 32) to initiate client side
+    resizes events in the wayland contexts with touch events.
+
+``--spirv-compiler=<compiler>``
+    Controls which compiler is used to translate GLSL to SPIR-V. This is
+    (currently) only relevant for ``--gpu-api=vulkan`` and `--gpu-api=d3d11`.
+    The possible choices are currently only:
+
+    auto
+        Use the first available compiler. (Default)
+    shaderc
+        Use libshaderc, which is an API wrapper around glslang. This is
+        generally the most preferred, if available.
+
+    .. note::
+
+        This option is deprecated, since there is only one reasonable value.
+        It may be removed in the future.
+
+``--glsl-shader=<file>``, ``--glsl-shaders=<file-list>``
+    Custom GLSL hooks. These are a flexible way to add custom fragment shaders,
+    which can be injected at almost arbitrary points in the rendering pipeline,
+    and access all previous intermediate textures.
+
+    Each use of the ``--glsl-shader`` option will add another file to the
+    internal list of shaders, while ``--glsl-shaders`` takes a list of files,
+    and overwrites the internal list with it. The latter is a path list option
+    (see `List Options`_ for details).
+
+    .. admonition:: Warning
+
+        The syntax is not stable yet and may change any time.
+
+    The general syntax of a user shader looks like this::
+
+        //!METADATA ARGS...
+        //!METADATA ARGS...
+
+        vec4 hook() {
+           ...
+           return something;
+        }
+
+        //!METADATA ARGS...
+        //!METADATA ARGS...
+
+        ...
+
+    Each section of metadata, along with the non-metadata lines after it,
+    defines a single block. There are currently two types of blocks, HOOKs and
+    TEXTUREs.
+
+    A ``TEXTURE`` block can set the following options:
+
+    TEXTURE <name> (required)
+        The name of this texture. Hooks can then bind the texture under this
+        name using BIND. This must be the first option of the texture block.
+
+    SIZE <width> [<height>] [<depth>] (required)
+        The dimensions of the texture. The height and depth are optional. The
+        type of texture (1D, 2D or 3D) depends on the number of components
+        specified.
+
+    FORMAT <name> (required)
+        The texture format for the samples. Supported texture formats are listed
+        in debug logging when the ``gpu`` VO is initialized (look for
+        ``Texture formats:``). Usually, this follows OpenGL naming conventions.
+        For example, ``rgb16`` provides 3 channels with normalized 16 bit
+        components. One oddity are float formats: for example, ``rgba16f`` has
+        16 bit internal precision, but the texture data is provided as 32 bit
+        floats, and the driver converts the data on texture upload.
+
+        Although format names follow a common naming convention, not all of them
+        are available on all hardware, drivers, GL versions, and so on.
+
+    FILTER <LINEAR|NEAREST>
+        The min/magnification filter used when sampling from this texture.
+
+    BORDER <CLAMP|REPEAT|MIRROR>
+        The border wrapping mode used when sampling from this texture.
+
+    Following the metadata is a string of bytes in hexadecimal notation that
+    define the raw texture data, corresponding to the format specified by
+    `FORMAT`, on a single line with no extra whitespace.
+
+    A ``HOOK`` block can set the following options:
+
+    HOOK <name> (required)
+        The texture which to hook into. May occur multiple times within a
+        metadata block, up to a predetermined limit. See below for a list of
+        hookable textures.
+
+    DESC <title>
+        User-friendly description of the pass. This is the name used when
+        representing this shader in the list of passes for property
+        `vo-passes`.
+
+    BIND <name>
+        Loads a texture (either coming from mpv or from a ``TEXTURE`` block)
+        and makes it available to the pass. When binding textures from mpv,
+        this will also set up macros to facilitate accessing it properly. See
+        below for a list. By default, no textures are bound. The special name
+        HOOKED can be used to refer to the texture that triggered this pass.
+
+    SAVE <name>
+        Gives the name of the texture to save the result of this pass into. By
+        default, this is set to the special name HOOKED which has the effect of
+        overwriting the hooked texture.
+
+    WIDTH <szexpr>, HEIGHT <szexpr>
+        Specifies the size of the resulting texture for this pass. ``szexpr``
+        refers to an expression in RPN (reverse polish notation), using the
+        operators + - * / > < !, floating point literals, and references to
+        sizes of existing texture (such as MAIN.width or CHROMA.height),
+        OUTPUT, or NATIVE_CROPPED (size of an input texture cropped after
+        pan-and-scan, video-align-x/y, video-pan-x/y, etc. and possibly
+        prescaled). By default, these are set to HOOKED.w and HOOKED.h,
+        espectively.
+
+    WHEN <szexpr>
+        Specifies a condition that needs to be true (non-zero) for the shader
+        stage to be evaluated. If it fails, it will silently be omitted. (Note
+        that a shader stage like this which has a dependency on an optional
+        hook point can still cause that hook point to be saved, which has some
+        minor overhead)
+
+    OFFSET <ox oy | ALIGN>
+        Indicates a pixel shift (offset) introduced by this pass. These pixel
+        offsets will be accumulated and corrected during the next scaling pass
+        (``cscale`` or ``scale``). The default values are 0 0 which correspond
+        to no shift. Note that offsets are ignored when not overwriting the
+        hooked texture.
+
+        A special value of ``ALIGN`` will attempt to fix existing offset of
+        HOOKED by align it with reference. It requires HOOKED to be resizable
+        (see below). It works transparently with fragment shader. For compute
+        shader, the predefined ``texmap`` macro is required to handle coordinate
+        mapping.
+
+    COMPONENTS <n>
+        Specifies how many components of this pass's output are relevant and
+        should be stored in the texture, up to 4 (rgba). By default, this value
+        is equal to the number of components in HOOKED.
+
+    COMPUTE <bw> <bh> [<tw> <th>]
+        Specifies that this shader should be treated as a compute shader, with
+        the block size bw and bh. The compute shader will be dispatched with
+        however many blocks are necessary to completely tile over the output.
+        Within each block, there will be tw*th threads, forming a single work
+        group. In other words: tw and th specify the work group size, which can
+        be different from the block size. So for example, a compute shader with
+        bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch
+        16x16 blocks (rounded up), each with 8x8 threads.
+
+        Compute shaders in mpv are treated a bit different from fragment
+        shaders. Instead of defining a ``vec4 hook`` that produces an output
+        sample, you directly define ``void hook`` which writes to a fixed
+        writeonly image unit named ``out_image`` (this is bound by mpv) using
+        `imageStore`. To help translate texture coordinates in the absence of
+        vertices, mpv provides a special function ``NAME_map(id)`` to map from
+        the texel space of the output image to the texture coordinates for all
+        bound textures. In particular, ``NAME_pos`` is equivalent to
+        ``NAME_map(gl_GlobalInvocationID)``, although using this only really
+        makes sense if (tw,th) == (bw,bh).
+
+    Each bound mpv texture (via ``BIND``) will make available the following
+    definitions to that shader pass, where NAME is the name of the bound
+    texture:
+
+    vec4 NAME_tex(vec2 pos)
+        The sampling function to use to access the texture at a certain spot
+        (in texture coordinate space, range [0,1]). This takes care of any
+        necessary normalization conversions.
+    vec4 NAME_texOff(vec2 offset)
+        Sample the texture at a certain offset in pixels. This works like
+        NAME_tex but additionally takes care of necessary rotations, so that
+        sampling at e.g. vec2(-1,0) is always one pixel to the left.
+    vec2 NAME_pos
+        The local texture coordinate of that texture, range [0,1].
+    vec2 NAME_size
+        The (rotated) size in pixels of the texture.
+    mat2 NAME_rot
+        The rotation matrix associated with this texture. (Rotates pixel space
+        to texture coordinates)
+    vec2 NAME_pt
+        The (unrotated) size of a single pixel, range [0,1].
+    float NAME_mul
+        The coefficient that needs to be multiplied into the texture contents
+        in order to normalize it to the range [0,1].
+    sampler NAME_raw
+        The raw bound texture itself. The use of this should be avoided unless
+        absolutely necessary.
+
+    Normally, users should use either NAME_tex or NAME_texOff to read from the
+    texture. For some shaders however , it can be better for performance to do
+    custom sampling from NAME_raw, in which case care needs to be taken to
+    respect NAME_mul and NAME_rot.
+
+    In addition to these parameters, the following uniforms are also globally
+    available:
+
+    float random
+        A random number in the range [0-1], different per frame.
+    int frame
+        A simple count of frames rendered, increases by one per frame and never
+        resets (regardless of seeks).
+    vec2 input_size
+        The size in pixels of the input image (possibly cropped and prescaled).
+    vec2 target_size
+        The size in pixels of the visible part of the scaled (and possibly
+        cropped) image.
+    vec2 tex_offset
+        Texture offset introduced by user shaders or options like panscan, video-align-x/y, video-pan-x/y.
+
+    Internally, vo_gpu may generate any number of the following textures.
+    Whenever a texture is rendered and saved by vo_gpu, all of the passes
+    that have hooked into it will run, in the order they were added by the
+    user. This is a list of the legal hook points:
+
+    RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
+        Source planes (raw). Which of these fire depends on the image format of
+        the source.
+
+    CHROMA_SCALED, ALPHA_SCALED (fixed)
+        Source planes (upscaled). These only fire on subsampled content.
+
+    NATIVE (resizable)
+        The combined image, in the source colorspace, before conversion to RGB.
+
+    MAINPRESUB (resizable)
+        The image, after conversion to RGB, but before
+        ``--blend-subtitles=video`` is applied.
+
+    MAIN (resizable)
+        The main image, after conversion to RGB but before upscaling.
+
+    LINEAR (fixed)
+        Linear light image, before scaling. This only fires when
+        ``--linear-upscaling``, ``--linear-downscaling`` or
+        ``--sigmoid-upscaling`` is in effect.
+
+    SIGMOID (fixed)
+        Sigmoidized light, before scaling. This only fires when
+        ``--sigmoid-upscaling`` is in effect.
+
+    PREKERNEL (fixed)
+        The image immediately before the scaler kernel runs.
+
+    POSTKERNEL (fixed)
+        The image immediately after the scaler kernel runs.
+
+    SCALED (fixed)
+        The final upscaled image, before color management.
+
+    OUTPUT (fixed)
+        The final output image, after color management but before dithering and
+        drawing to screen.
+
+    Only the textures labelled with ``resizable`` may be transformed by the
+    pass. When overwriting a texture marked ``fixed``, the WIDTH, HEIGHT and
+    OFFSET must be left at their default values.
+
+``--glsl-shader=<file>``
+    CLI/config file only alias for ``--glsl-shaders-append``.
+
+``--glsl-shader-opts=param1=value1,param2=value2,...``
+    Specifies the options to use for tunable shader parameters. You can target
+    specific named shaders by prefixing the shader name with a ``/``, e.g.
+    ``shader/param=value``. Without a prefix, parameters affect all shaders.
+    The shader name is the base part of the shader filename, without the
+    extension. (``--vo=gpu-next`` only)
+
+``--deband``
+    Enable the debanding algorithm. This greatly reduces the amount of visible
+    banding, blocking and other quantization artifacts, at the expense of
+    very slightly blurring some of the finest details. In practice, it's
+    virtually always an improvement - the only reason to disable it would be
+    for performance.
+
+``--deband-iterations=<0..16>``
+    The number of debanding steps to perform per sample. Each step reduces a
+    bit more banding, but takes time to compute. Note that the strength of each
+    step falls off very quickly, so high numbers (>4) are practically useless.
+    (Default 1)
+
+``--deband-threshold=<0..4096>``
+    The debanding filter's cut-off threshold. Higher numbers increase the
+    debanding strength dramatically but progressively diminish image details.
+    (Default 48)
+
+``--deband-range=<1..64>``
+    The debanding filter's initial radius. The radius increases linearly for
+    each iteration. A higher radius will find more gradients, but a lower
+    radius will smooth more aggressively. (Default 16)
+
+    If you increase the ``--deband-iterations``, you should probably decrease
+    this to compensate.
+
+``--deband-grain=<0..4096>``
+    Add some extra noise to the image. This significantly helps cover up
+    remaining quantization artifacts. Higher numbers add more noise. (Default
+    32)
+
+``--corner-rounding=<0..1>``
+    If set to a value above 0.0, the output will be rendered with rounded
+    corners, as if an alpha transparency mask had been applied. The value
+    indicates the relative fraction of the side length to round - a value of
+    1.0 rounds the corners as much as possible. (``--vo=gpu-next`` only)
+
+``--sharpen=<value>``
+    If set to a value other than 0, enable an unsharp masking filter. Positive
+    values will sharpen the image (but add more ringing and aliasing). Negative
+    values will blur the image. If your GPU is powerful enough, consider
+    alternatives like the ``ewa_lanczossharp`` scale filter, or the
+    ``--scale-blur`` option. (Only for ``--vo=gpu``)
+
+``--opengl-glfinish``
+    Call ``glFinish()`` before swapping buffers (default: disabled). Slower,
+    but might improve results when doing framedropping. Can completely ruin
+    performance. The details depend entirely on the OpenGL driver.
+
+``--opengl-waitvsync``
+    Call ``glXWaitVideoSyncSGI`` after each buffer swap (default: disabled).
+    This may or may not help with video timing accuracy and frame drop. It's
+    possible that this makes video output slower, or has no effect at all.
+
+    X11/GLX only.
+
+``--opengl-dwmflush=<no|windowed|yes|auto>``
+    (Windows only)
+    Calls ``DwmFlush`` after swapping buffers on Windows (default: auto). It
+    also sets ``SwapInterval(0)`` to ignore the OpenGL timing. Values are: no
+    (disabled), windowed (only in windowed mode), yes (also in full screen).
+
+    The value ``auto`` will try to determine whether the compositor is active,
+    and calls ``DwmFlush`` only if it seems to be.
+
+    This may help to get more consistent frame intervals, especially with
+    high-fps clips - which might also reduce dropped frames. Typically, a value
+    of ``windowed`` should be enough, since full screen may bypass the DWM.
+
+``--angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>``
+    Selects a specific feature level when using the ANGLE backend with D3D11.
+    By default, the highest available feature level is used. This option can be
+    used to select a lower feature level, which is mainly useful for debugging.
+    Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher.
+    Most extended OpenGL features will not work at lower feature levels
+    (similar to ``--gpu-dumb-mode``).
+
+    Windows with ANGLE only.
+
+``--angle-d3d11-warp=<yes|no|auto>``
+    Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE
+    backend with D3D11 (default: auto). This is a high performance software
+    renderer. By default, it is used when the Direct3D hardware does not
+    support Direct3D 11 feature level 9_3. While the extended OpenGL features
+    will work with WARP, they can be very slow.
+
+    Windows with ANGLE only.
+
+``--angle-egl-windowing=<yes|no|auto>``
+    Use ANGLE's built in EGL windowing functions to create a swap chain
+    (default: auto). If this is set to ``no`` and the D3D11 renderer is in use,
+    ANGLE's built in swap chain will not be used and a custom swap chain that
+    is optimized for video rendering will be created instead. If set to
+    ``auto``, a custom swap chain will be used for D3D11 and the built in swap
+    chain will be used for D3D9. This option is mainly for debugging purposes,
+    in case the custom swap chain has poor performance or does not work.
+
+    If set to ``yes``, the ``--angle-flip`` option will have no effect.
+
+    Windows with ANGLE only.
+
+``--angle-flip=<yes|no>``
+    Enable flip-model presentation, which avoids unnecessarily copying the
+    backbuffer by sharing surfaces with the DWM (default: yes). This may cause
+    performance issues with older drivers. If flip-model presentation is not
+    supported (for example, on Windows 7 without the platform update), mpv will
+    automatically fall back to the older bitblt presentation model.
+
+    If set to ``no``, the ``--angle-swapchain-length`` option will have no
+    effect.
+
+    Windows with ANGLE only.
+
+``--angle-renderer=<d3d9|d3d11|auto>``
+    Forces a specific renderer when using the ANGLE backend (default: auto). In
+    auto mode this will pick D3D11 for systems that support Direct3D 11 feature
+    level 9_3 or higher, and D3D9 otherwise. This option is mainly for
+    debugging purposes. Normally there is no reason to force a specific
+    renderer, though ``--angle-renderer=d3d9`` may give slightly better
+    performance on old hardware. Note that the D3D9 renderer only supports
+    OpenGL ES 2.0, so most extended OpenGL features will not work if this
+    renderer is selected (similar to ``--gpu-dumb-mode``).
+
+    Windows with ANGLE only.
+
+``--macos-force-dedicated-gpu=<yes|no>``
+    Deactivates the automatic graphics switching and forces the dedicated GPU.
+    (default: no)
+
+    macOS only.
+
+``--cocoa-cb-sw-renderer=<yes|no|auto>``
+    Use the Apple Software Renderer when using cocoa-cb (default: auto). If set
+    to ``no`` the software renderer is never used and instead fails when a the
+    usual pixel format could not be created, ``yes`` will always only use the
+    software renderer, and ``auto`` only falls back to the software renderer
+    when the usual pixel format couldn't be created.
+
+    macOS only.
+
+``--cocoa-cb-10bit-context=<yes|no>``
+    Creates a 10bit capable pixel format for the context creation (default: yes).
+    Instead of 8bit integer framebuffer a 16bit half-float framebuffer is
+    requested.
+
+    macOS only.
+
+``--macos-title-bar-appearance=<appearance>``
+    Sets the appearance of the title bar (default: auto). Not all combinations
+    of appearances and ``--macos-title-bar-material`` materials make sense or
+    are unique. Appearances that are not supported by you current macOS version
+    fall back to the default value.
+    macOS and cocoa-cb only
+
+    ``<appearance>`` can be one of the following:
+
+    :auto:                     Detects the system settings and sets the title
+                               bar appearance appropriately. On macOS 10.14 it
+                               also detects run time changes.
+    :aqua:                     The standard macOS Light appearance.
+    :darkAqua:                 The standard macOS Dark appearance. (macOS 10.14+)
+    :vibrantLight:             Light vibrancy appearance with.
+    :vibrantDark:              Dark vibrancy appearance with.
+    :aquaHighContrast:         Light Accessibility appearance. (macOS 10.14+)
+    :darkAquaHighContrast:     Dark Accessibility appearance. (macOS 10.14+)
+    :vibrantLightHighContrast: Light vibrancy Accessibility appearance.
+                               (macOS 10.14+)
+    :vibrantDarkHighContrast:  Dark vibrancy Accessibility appearance.
+                               (macOS 10.14+)
+
+``--macos-title-bar-material=<material>``
+    Sets the material of the title bar (default: titlebar). All deprecated
+    materials should not be used on macOS 10.14+ because their functionality
+    is not guaranteed. Not all combinations of materials and
+    ``--macos-title-bar-appearance`` appearances make sense or are unique.
+    Materials that are not supported by you current macOS version fall back to
+    the default value.
+    macOS and cocoa-cb only
+
+    ``<material>`` can be one of the following:
+
+    :titlebar:              The standard macOS title bar material.
+    :selection:             The standard macOS selection material.
+    :menu:                  The standard macOS menu material. (macOS 10.11+)
+    :popover:               The standard macOS popover material. (macOS 10.11+)
+    :sidebar:               The standard macOS sidebar material. (macOS 10.11+)
+    :headerView:            The standard macOS header view material.
+                            (macOS 10.14+)
+    :sheet:                 The standard macOS sheet material. (macOS 10.14+)
+    :windowBackground:      The standard macOS window background material.
+                            (macOS 10.14+)
+    :hudWindow:             The standard macOS hudWindow material. (macOS 10.14+)
+    :fullScreen:            The standard macOS full screen material.
+                            (macOS 10.14+)
+    :toolTip:               The standard macOS tool tip material. (macOS 10.14+)
+    :contentBackground:     The standard macOS content background material.
+                            (macOS 10.14+)
+    :underWindowBackground: The standard macOS under window background material.
+                            (macOS 10.14+)
+    :underPageBackground:   The standard macOS under page background material.
+                            (deprecated in macOS 10.14+)
+    :dark:                  The standard macOS dark material.
+                            (deprecated in macOS 10.14+)
+    :light:                 The standard macOS light material.
+                            (macOS 10.14+)
+    :mediumLight:           The standard macOS mediumLight material.
+                            (macOS 10.11+, deprecated in macOS 10.14+)
+    :ultraDark:             The standard macOS ultraDark material.
+                            (macOS 10.11+ deprecated in macOS 10.14+)
+
+``--macos-title-bar-color=<color>``
+    Sets the color of the title bar (default: completely transparent). Is
+    influenced by ``--macos-title-bar-appearance`` and
+    ``--macos-title-bar-material``.
+    See ``--sub-color`` for color syntax.
+
+``--macos-fs-animation-duration=<default|0-1000>``
+    Sets the fullscreen resize animation duration in ms (default: default).
+    The default value is slightly less than the system's animation duration
+    (500ms) to prevent some problems when the end of an async animation happens
+    at the same time as the end of the system wide fullscreen animation. Setting
+    anything higher than 500ms will only prematurely cancel the resize animation
+    after the system wide animation ended. The upper limit is still set at
+    1000ms since it's possible that Apple or the user changes the system
+    defaults. Anything higher than 1000ms though seems too long and shouldn't be
+    set anyway.
+    (macOS and cocoa-cb only)
+
+
+``--macos-app-activation-policy=<regular|accessory|prohibited>``
+    Changes the App activation policy. With accessory the mpv icon in the Dock
+    can be hidden. (default: regular)
+
+    macOS only.
+
+``--macos-geometry-calculation=<visible|whole>``
+    This changes the rectangle which is used to calculate the screen position
+    and size of the window (default: visible). ``visible`` takes the the menu
+    bar and Dock into account and the window is only positioned/sized within the
+    visible screen frame rectangle, ``whole`` takes the whole screen frame
+    rectangle and ignores the menu bar and Dock. Other previous restrictions
+    still apply, like the window can't be placed on top of the menu bar etc.
+
+    macOS only.
+
+``--macos-render-timer=<timer>``
+    Sets the mode (default: callback) for syncing the rendering of frames to the display's
+    vertical refresh rate.
+    macOS and Vulkan (macvk) only.
+
+    ``<timer>`` can be one of the following:
+
+    :callback: Syncs to the CVDisplayLink callback
+    :precise:  Syncs to the time of the next vertical display refresh reported by the
+               CVDisplayLink callback provided information
+    :system:   No manual syncing, depend on the layer mechanic and the next drawable
+
+``--android-surface-size=<WxH>``
+    Set dimensions of the rendering surface used by the Android gpu context.
+    Needs to be set by the embedding application if the dimensions change during
+    runtime (i.e. if the device is rotated), via the surfaceChanged callback.
+
+    Android with ``--gpu-context=android`` only.
+
+``--gpu-sw``
+    Continue even if a software renderer is detected.
+
+``--gpu-context=<sys>``
+    The value ``auto`` (the default) selects the GPU context. You can also pass
+    ``help`` to get a complete list of compiled in backends (sorted by
+    autoprobe order).
+
+    auto
+        auto-select (default)
+    cocoa
+        Cocoa/macOS (deprecated, use --vo=libmpv instead)
+    win
+        Win32/WGL
+    winvk
+        VK_KHR_win32_surface
+    angle
+        Direct3D11 through the OpenGL ES translation layer ANGLE. This supports
+        almost everything the ``win`` backend does (if the ANGLE build is new
+        enough).
+    dxinterop (experimental)
+        Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works
+        on Nvidia and AMD. Newer Intel chips with the latest drivers may also
+        work.
+    d3d11
+        Win32, with native Direct3D 11 rendering.
+    x11
+        X11/GLX (deprecated/legacy, EGL is preferred these days)
+    x11vk
+        VK_KHR_xlib_surface
+    wayland
+        Wayland/EGL
+    waylandvk
+        VK_KHR_wayland_surface
+    drm
+        DRM/EGL
+    displayvk
+        VK_KHR_display. This backend is roughly the Vukan equivalent of
+        DRM/EGL, allowing for direct rendering via Vulkan without a display
+        manager.
+    x11egl
+        X11/EGL
+    android
+        Android/EGL. Requires ``--wid`` be set to an ``android.view.Surface``.
+    macvk
+        Vulkan on macOS with a metal surface through a translation layer (experimental)
+
+``--gpu-api=<type>``
+    Controls which type of graphics APIs will be accepted:
+
+    auto
+        Use any available API (default)
+    opengl
+        Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
+    vulkan
+        Allow only Vulkan (requires a valid/working ``--spirv-compiler``)
+    d3d11
+        Allow only ``--gpu-context=d3d11``
+
+``--opengl-es=<mode>``
+    Controls which type of OpenGL context will be accepted:
+
+    auto
+        Allow all types of OpenGL (default)
+    yes
+        Only allow GLES
+    no
+        Only allow desktop/core GL
+
+``--fbo-format=<fmt>``
+    Selects the internal format of textures used for FBOs. The format can
+    influence performance and quality of the video output. ``fmt`` can be one
+    of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f,
+    rgba16hf, rgba32f.
+
+    Default: ``auto``, which first attempts to utilize 16bit float
+    (rgba16f, rgba16hf), and falls back to rgba16 if those are not available.
+    Finally, attempts to utilize rgb10_a2 or rgba8 if all of the previous formats
+    are not available.
+
+``--gamma-factor=<0.1..2.0>``
+    Set an additional raw gamma factor (default: 1.0). If gamma is adjusted in
+    other ways (like with the ``--gamma`` option or key bindings and the
+    ``gamma`` property), the value is multiplied with the other gamma value.
+
+    This option is deprecated and may be removed in the future.
+
+``--gamma-auto``
+    Automatically corrects the gamma value depending on ambient lighting
+    conditions (adding a gamma boost for bright rooms).
+
+    This option is deprecated and may be removed in the future.
+
+    NOTE: Only implemented on macOS.
+
+``--image-lut=<file>``
+    Specifies a custom LUT file (in Adobe .cube format) to apply to the colors
+    during image decoding. The exact interpretation of the LUT depends on
+    the value of ``--image-lut-type``. (Only for ``--vo=gpu-next``)
+
+``--image-lut-type=<value>``
+    Controls the interpretation of color values fed to and from the LUT
+    specified as ``--image-lut``. Valid values are:
+
+    auto
+        Chooses the interpretation of the LUT automatically from tagged
+        metadata, and otherwise falls back to ``native``. (Default)
+    native
+        Applied to the raw image contents in its native colorspace, before
+        decoding to RGB. For example, for a HDR10 image, this would be fed
+        PQ-encoded YCbCr values in the range 0.0 - 1.0.
+    normalized
+        Applied to the normalized RGB image contents, after decoding from
+        its native color encoding, but before linearization.
+    conversion
+        Fully replaces the color decoding. A LUT of this type should ingest the
+        image's native colorspace and output normalized non-linear RGB.
+
+``--target-colorspace-hint``
+    Automatically configure the output colorspace of the display to pass
+    through the input values of the stream (e.g. for HDR passthrough), if
+    possible. Requires a supporting driver and ``--vo=gpu-next``.
+
+``--target-prim=<value>``
+    Specifies the primaries of the display. Video colors will be adapted to
+    this colorspace when ICC color management is not being used. Valid values
+    are:
+
+    auto
+        Disable any adaptation, except for atypical color spaces. Specifically,
+        wide/unusual gamuts get automatically adapted to BT.709, while standard
+        gamut (i.e. BT.601 and BT.709) content is not touched. (default)
+    bt.470m
+        ITU-R BT.470 M
+    bt.601-525
+        ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE 170M/240M
+    bt.601-625
+        ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R BT.470 B/G
+    bt.709
+        ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 Annex B
+    bt.2020
+        ITU-R BT.2020 (UHD)
+    apple
+        Apple RGB
+    adobe
+        Adobe RGB (1998)
+    prophoto
+        ProPhoto RGB (ROMM)
+    cie1931
+        CIE 1931 RGB (not to be confused with CIE XYZ)
+    dci-p3
+        DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2
+    v-gamut
+        Panasonic V-Gamut (VARICAM) primaries
+    s-gamut
+        Sony S-Gamut (S-Log) primaries
+
+``--target-trc=<value>``
+    Specifies the transfer characteristics (gamma) of the display. Video colors
+    will be adjusted to this curve when ICC color management is not being used.
+    Valid values are:
+
+    auto
+        Disable any adaptation, except for atypical transfers. Specifically,
+        HDR or linear light source material gets automatically converted to
+        gamma 2.2, while SDR content is not touched. (default)
+    bt.1886
+        ITU-R BT.1886 curve (assuming infinite contrast)
+    srgb
+        IEC 61966-2-4 (sRGB)
+    linear
+        Linear light output
+    gamma1.8
+        Pure power curve (gamma 1.8), also used for Apple RGB
+    gamma2.0
+        Pure power curve (gamma 2.0)
+    gamma2.2
+        Pure power curve (gamma 2.2)
+    gamma2.4
+        Pure power curve (gamma 2.4)
+    gamma2.6
+        Pure power curve (gamma 2.6)
+    gamma2.8
+        Pure power curve (gamma 2.8), also used for BT.470-BG
+    prophoto
+        ProPhoto RGB (ROMM)
+    pq
+        ITU-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE ST2084
+    hlg
+        ITU-R BT.2100 HLG (Hybrid Log-gamma) curve, aka ARIB STD-B67
+    v-log
+        Panasonic V-Log (VARICAM) curve
+    s-log1
+        Sony S-Log1 curve
+    s-log2
+        Sony S-Log2 curve
+
+    .. note::
+
+        When using HDR output formats, mpv will encode to the specified
+        curve but it will not set any HDMI flags or other signalling that might
+        be required for the target device to correctly display the HDR signal.
+        The user should independently guarantee this before using these signal
+        formats for display.
+
+``--target-peak=<auto|nits>``
+    Specifies the measured peak brightness of the output display, in cd/m^2
+    (AKA nits). The interpretation of this brightness depends on the configured
+    ``--target-trc``. In all cases, it imposes a limit on the signal values
+    that will be sent to the display. If the source exceeds this brightness
+    level, a tone mapping filter will be inserted. For HLG, it has the
+    additional effect of parametrizing the inverse OOTF, in order to get
+    colorimetrically consistent results with the mastering display. For SDR, or
+    when using an ICC (profile (``--icc-profile``), setting this to a value
+    above 203 essentially causes the display to be treated as if it were an HDR
+    display in disguise. (See the note below)
+
+    In ``auto`` mode (the default), the chosen peak is an appropriate value
+    based on the TRC in use. For SDR curves, it uses 203. For HDR curves, it
+    uses 203 * the transfer function's nominal peak.
+
+    .. note::
+
+        When using an SDR transfer function, this is normally not needed, and
+        setting it may lead to very unexpected results. The one time it *is*
+        useful is if you want to calibrate a HDR display using traditional
+        transfer functions and calibration equipment. In such cases, you can
+        set your HDR display to a high brightness such as 800 cd/m^2, and then
+        calibrate it to a standard curve like gamma2.8. Setting this value to
+        800 would then instruct mpv to essentially treat it as an HDR display
+        with the given peak. This may be a good alternative in environments
+        where PQ or HLG input to the display is not possible, and makes it
+        possible to use HDR displays with mpv regardless of operating system
+        support for HDMI HDR metadata.
+
+        In such a configuration, we highly recommend setting ``--tone-mapping``
+        to ``mobius`` or even ``clip``.
+
+``--target-contrast=<auto|10-1000000|inf>``
+    Specifies the measured contrast of the output display. ``--target-contrast``
+    in conjunction with ``--target-peak`` value is used to calculate display
+    black point. Used in black point compensation during HDR tone-mapping.
+    ``auto`` is the default and assumes 1000:1 contrast as a typical SDR display
+    would have or an infinite contrast when HDR ``--target-trc`` is used.
+    ``inf`` contrast specifies display with perfect black level, in practice OLED.
+    (Only for ``--vo=gpu-next``)
+
+``--target-gamut=<value>``
+    Constrains the gamut of the display. You can use this option to output e.g.
+    DCIP3-in-BT.2020. Set ``--target-prim`` to the primaries of the containing
+    colorspace (into which values will be encoded), and ``--target-gamut`` to
+    the gamut you want to limit colors to. Takes the same values as
+    ``--target-prim``. (Only for ``--vo=gpu-next``)
+
+``--target-lut=<file>``
+    Specifies a custom LUT file (in Adobe .cube format) to apply to the colors
+    before display on-screen. This LUT is fed values in normalized RGB, after
+    encoding into the target colorspace, so after the application of
+    ``--target-trc``. (Only for ``--vo=gpu-next``)
+
+``--tone-mapping=<value>``
+    Specifies the algorithm used for tone-mapping images onto the target
+    display. This is relevant for both HDR->SDR conversion as well as gamut
+    reduction (e.g. playing back BT.2020 content on a standard gamut display).
+    Valid values are:
+
+    auto
+        Choose the best curve according to internal heuristics. (Default)
+    clip
+        Hard-clip any out-of-range values. Use this when you care about
+        perfect color accuracy for in-range values at the cost of completely
+        distorting out-of-range values. Not generally recommended.
+    mobius
+        Generalization of Reinhard to a Möbius transform with linear section.
+        Smoothly maps out-of-range values while retaining contrast and colors
+        for in-range material as much as possible. Use this when you care about
+        color accuracy more than detail preservation. This is somewhere in
+        between ``clip`` and ``reinhard``, depending on the value of
+        ``--tone-mapping-param``.
+    reinhard
+        Reinhard tone mapping algorithm. Very simple continuous curve.
+        Preserves overall image brightness but uses nonlinear contrast, which
+        results in flattening of details and degradation in color accuracy.
+    hable
+        Similar to ``reinhard`` but preserves both dark and bright details
+        better (slightly sigmoidal), at the cost of slightly darkening /
+        desaturating everything. Developed by John Hable for use in video
+        games. Use this when you care about detail preservation more than
+        color/brightness accuracy. This is roughly equivalent to
+        ``--tone-mapping=reinhard --tone-mapping-param=0.24``. If possible,
+        you should also enable ``--hdr-compute-peak`` for the best results.
+    bt.2390
+        Perceptual tone mapping curve (EETF) specified in ITU-R Report BT.2390.
+    gamma
+        Fits a logarithmic transfer between the tone curves.
+    linear
+        Linearly stretches the entire reference gamut to (a linear multiple of)
+        the display.
+    spline
+        Perceptually linear single-pivot polynomial. (``--vo=gpu-next`` only)
+    bt.2446a
+        HDR<->SDR mapping specified in ITU-R Report BT.2446, method A. This is
+        the recommended curve for well-mastered content. (``--vo=gpu-next``
+        only)
+    st2094-40
+        Dynamic HDR10+ tone-mapping method specified in SMPTE ST2094-40 Annex
+        B. In the absence of metadata, falls back to a fixed spline matched to
+        the input/output average brightness characteristics. (``--vo=gpu-next``
+        only)
+    st2094-10
+        Dynamic tone-mapping method specified in SMPTE ST2094-10 Annex B.2.
+        Conceptually simpler than ST2094-40, and generally produces worse
+        results.
+
+``--tone-mapping-param=<value>``
+    Set tone mapping parameters. By default, this is set to the special string
+    ``default``, which maps to an algorithm-specific default value. Ignored if
+    the tone mapping algorithm is not tunable. This affects the following tone
+    mapping algorithms:
+
+    clip
+        Specifies an extra linear coefficient to multiply into the signal
+        before clipping. Defaults to 1.0.
+    mobius
+        Specifies the transition point from linear to mobius transform. Every
+        value below this point is guaranteed to be mapped 1:1. The higher the
+        value, the more accurate the result will be, at the cost of losing
+        bright details. Defaults to 0.3, which due to the steep initial slope
+        still preserves in-range colors fairly accurately.
+    reinhard
+        Specifies the local contrast coefficient at the display peak. Defaults
+        to 0.5, which means that in-gamut values will be about half as bright
+        as when clipping.
+    bt.2390
+        Specifies the offset for the knee point. Defaults to 1.0, which is
+        higher than the value from the original ITU-R specification (0.5).
+        (``--vo=gpu-next`` only)
+    gamma
+        Specifies the exponent of the function. Defaults to 1.8.
+    linear
+        Specifies the scale factor to use while stretching. Defaults to 1.0.
+    spline
+        Specifies the knee point (in PQ space). Defaults to 0.30.
+    st2094-10
+        Specifies the contrast (slope) at the knee point. Defaults to 1.0.
+
+``--inverse-tone-mapping``
+    If set, allows inverse tone mapping (expanding SDR to HDR). Not supported
+    by all tone mapping curves. Use with caution. (``--vo=gpu-next`` only)
+
+``--tone-mapping-max-boost=<1.0..10.0>``
+    Upper limit for how much the tone mapping algorithm is allowed to boost
+    the average brightness by over-exposing the image. The default value of 1.0
+    allows no additional brightness boost. A value of 2.0 would allow
+    over-exposing by a factor of 2, and so on. Raising this setting can help
+    reveal details that would otherwise be hidden in dark scenes, but raising
+    it too high will make dark scenes appear unnaturally bright. (``--vo=gpu``
+    only)
+
+``--tone-mapping-visualize``
+    Display a (PQ-PQ) graph of the active tone-mapping LUT. Intended only for
+    debugging purposes. The X axis shows PQ input values, the Y axis shows PQ
+    output values. The tone-mapping curve is shown in green/yellow. Yellow
+    means the brightness has been boosted from the source, dark blue regions
+    show where the brightness has been reduced. The extra colored regions and
+    lines indicate various monitor limits, as well a reference diagonal
+    (neutral tone-mapping) and source scene average brightness information (if
+    available). (``--vo=gpu-next`` only)
+
+``--gamut-mapping-mode``
+    Specifies the algorithm used for reducing the gamut of images for the
+    target display, after any tone mapping is done.
+
+    auto
+        Choose the best mode automatically. (Default)
+    clip
+        Hard-clip to the gamut (per-channel). Very low quality, but free.
+    perceptual
+        Performs a perceptually balanced gamut mapping using a soft knee
+        function to roll-off clipped regions, and a hue shifting function to
+        preserve saturation. (``--vo=gpu-next`` only)
+    relative
+        Performs relative colorimetric clipping, while maintaining an
+        exponential relationship between brightness and chromaticity.
+        (``--vo=gpu-next`` only)
+    saturation
+        Performs simple RGB->RGB saturation mapping. The input R/G/B channels
+        are mapped directly onto the output R/G/B channels. Will never clip,
+        but will distort all hues and/or result in a faded look.
+        (``--vo=gpu-next`` only)
+    absolute
+        Performs absolute colorimetric clipping. Like ``relative``, but does
+        not adapt the white point. (``--vo=gpu-next`` only)
+    desaturate
+        Performs constant-luminance colorimetric clipping, desaturing colors
+        towards white until they're in-range.
+    darken
+        Uniformly darkens the input slightly to prevent clipping on blown-out
+        highlights, then clamps colorimetrically to the input gamut boundary,
+        biased slightly to preserve chromaticity over luminance.
+        (``--vo=gpu-next`` only)
+    warn
+        Performs no gamut mapping, but simply highlights out-of-gamut pixels.
+    linear
+        Linearly/uniformly desaturates the image in order to bring the entire
+        image into the target gamut. (``--vo=gpu-next`` only)
+
+``--hdr-compute-peak=<auto|yes|no>``
+    Compute the HDR peak and frame average brightness per-frame instead of
+    relying on tagged metadata. These values are averaged over local regions as
+    well as over several frames to prevent the value from jittering around too
+    much. This option basically gives you dynamic, per-scene tone mapping.
+    Requires compute shaders, which is a fairly recent OpenGL feature, and will
+    probably also perform horribly on some drivers, so enable at your own risk.
+    The special value ``auto`` (default) will enable HDR peak computation
+    automatically if compute shaders and SSBOs are supported.
+
+``--allow-delayed-peak-detect``
+    When using ``--hdr-compute-peak``, allow delaying the detected peak by a
+    frame when beneficial for performance. In particular, this is required to
+    avoid an unnecessary FBO indirection when no advanced rendering is required
+    otherwise. Has no effect if there already is an indirect pass, such as when
+    advanced scaling is enabled. Defaults to no. (Only affects
+    ``--vo=gpu-next``, note that ``--vo=gpu`` always delays the peak.)
+
+``--hdr-peak-percentile=<0.0..100.0>``
+    Which percentile of the input image brightness histogram to consider as the
+    true peak of the scene. If this is set to 100 (default), the
+    brightest pixel is measured. Otherwise, the top of the frequency
+    distribution is progressively cut off. Setting this too low will cause
+    clipping of very bright details, but can improve the dynamic brightness
+    range of scenes with very bright isolated highlights. Values other than 100
+    come with a small performance penalty. (Only for ``--vo=gpu-next``)
+
+``--hdr-peak-decay-rate=<0.0..1000.0>``
+    The decay rate used for the HDR peak detection algorithm (default: 20.0).
+    This is only relevant when ``--hdr-compute-peak`` is enabled. Higher values
+    make the peak decay more slowly, leading to more stable values at the cost
+    of more "eye adaptation"-like effects (although this is mitigated somewhat
+    by ``--hdr-scene-threshold``). A value of 0.0 (the lowest possible) disables
+    all averaging, meaning each frame's value is used directly as measured,
+    but doing this is not recommended for "noisy" sources since it may lead
+    to excessive flicker. (In signal theory terms, this controls the time
+    constant "tau" of an IIR low pass filter)
+
+``--hdr-scene-threshold-low=<0.0..100.0>``, ``--hdr-scene-threshold-high=<0.0..100.0>``
+    The lower and upper thresholds (in dB) for a brightness difference
+    to be considered a scene change (default: 1.0 low, 3.0 high). This is only
+    relevant when ``--hdr-compute-peak`` is enabled. Normally, small
+    fluctuations in the frame brightness are compensated for by the peak
+    averaging mechanism, but for large jumps in the brightness this can result
+    in the frame remaining too bright or too dark for up to several seconds,
+    depending on the value of ``--hdr-peak-decay-rate``. To counteract this,
+    when the brightness between the running average and the current frame
+    exceeds the low threshold, mpv will make the averaging filter more
+    aggressive, up to the limit of the high threshold (at which point the
+    filter becomes instant).
+
+``--hdr-contrast-recovery=<0.0..2.0>``, ``--hdr-contrast-smoothness=<1.0..100.0>``
+    Enables the HDR contrast recovery algorithm, which is to designed to
+    enhance contrast of HDR video after tone mapping. The strength (default:
+    0.0) indicates the degree of contrast recovery, with 0.0 being completely
+    disabled and 1.0 being 100% strength. Values higher than 1.0 are allowed,
+    but may result in excessive sharpening. The smoothness (default: 3.5)
+    indicates the degree to which the HDR source is low-passed in order to
+    obtain contrast information - a value of 2.0 corresponds to 2x downscaling.
+    Users on low DPI displays (<= 100) may want to lower this value, while
+    users on very high DPI displays ("retina") may want to increase it. (Only
+    for ``vo=gpu-next``)
+
+``--use-embedded-icc-profile``
+    Load the embedded ICC profile contained in media files such as PNG images.
+    (Default: yes). Note that this option only works when also using a display
+    ICC profile (``--icc-profile`` or ``--icc-profile-auto``), and also
+    requires LittleCMS 2 support.
+
+``--icc-profile=<file>``
+    Load an ICC profile and use it to transform video RGB to screen output.
+    Needs LittleCMS 2 support compiled in. This option overrides the
+    ``--target-prim``, ``--target-trc`` and ``--icc-profile-auto`` options.
+
+``--icc-profile-auto``
+    Automatically select the ICC display profile currently specified by the
+    display settings of the operating system.
+
+    NOTE: On Windows, the default profile must be an ICC profile. WCS profiles
+    are not supported.
+
+    Applications using libmpv with the render API need to provide the ICC
+    profile via ``MPV_RENDER_PARAM_ICC_PROFILE``.
+
+``--icc-cache``
+    Store and load 3DLUTs created from the ICC profile on disk in the
+    cache directory (Default: ``yes``). This can be used to speed up loading,
+    since LittleCMS 2 can take a while to create a 3D LUT. Note that these
+    files contain uncompressed LUTs. Their size depends on the
+    ``--icc-3dlut-size``, and can be very big.
+
+    NOTE: On ``--vo=gpu``, this is not cleaned automatically, so old, unused
+    cache files may stick around indefinitely.
+
+``--icc-cache-dir``
+    The directory where icc cache is stored. Cache is stored in the system's
+    cache directory (usually ``~/.cache/mpv``) if this is unset.
+
+``--icc-intent=<value>``
+    Specifies the ICC intent used for the color transformation (when using
+    ``--icc-profile``).
+
+    0
+        perceptual
+    1
+        relative colorimetric (default)
+    2
+        saturation
+    3
+        absolute colorimetric
+
+``--icc-3dlut-size=<auto|RxGxB>``
+    Size of the 3D LUT generated from the ICC profile in each dimension. The
+    default of ``auto`` means to pick the size automatically based on the
+    profile characteristics. Sizes may range from 2 to 512.
+
+    NOTE: Setting this option to anything other than ``auto`` is **strongly**
+    discouraged, except for testing.
+
+``--icc-force-contrast=<no|0-1000000|inf>``
+    Override the target device's detected contrast ratio by a specific value.
+    This is detected automatically from the profile if possible, but for some
+    profiles it might be missing, causing the contrast to be assumed as
+    infinite. As a result, video may appear darker than intended. If this is
+    the case, setting this option might help. This only affects BT.1886
+    content. The default of ``no`` means to use the profile values. The special
+    value ``inf`` causes the BT.1886 curve to be treated as a pure power gamma
+    2.4 function.
+
+``--icc-use-luma``
+    Use ICC profile luminance value. (Only for ``--vo=gpu-next``)
+
+``--lut=<file>``
+    Specifies a custom LUT (in Adobe .cube format) to apply to the colors
+    as part of color conversion. The exact interpretation depends on the value
+    of ``--lut-type``. (Only for ``--vo=gpu-next``)
+
+``--lut-type=<value>``
+    Controls the interpretation of color values fed to and from the LUT
+    specified as ``--lut``. Valid values are:
+
+    auto
+        Chooses the interpretation of the LUT automatically from tagged
+        metadata, and otherwise falls back to ``native``. (Default)
+    native
+        Applied to raw image contents in its native RGB colorspace (non-linear
+        light), before conversion to the output color space.
+    normalized
+        Applied to the normalized RGB image contents, in linear light, before
+        conversion to the output color space.
+    conversion
+        Fully replaces the conversion from the image color space to the output
+        color space. If such a LUT is present, it has the highest priority, and
+        overrides any ICC profiles, as well as options related to tone mapping
+        and output colorimetry (``--target-prim``, ``--target-trc`` etc.).
+
+``--blend-subtitles=<yes|video|no>``
+    Blend subtitles directly onto upscaled video frames, before interpolation
+    and/or color management (default: no). Enabling this causes subtitles to be
+    affected by ``--icc-profile``, ``--target-prim``, ``--target-trc``,
+    ``--interpolation``, ``--gamma-factor`` and ``--glsl-shaders``. It also
+    increases subtitle performance when using ``--interpolation``.
+
+    The downside of enabling this is that it restricts subtitles to the visible
+    portion of the video, so you can't have subtitles exist in the black
+    margins below a video (for example).
+
+    If ``video`` is selected, the behavior is similar to ``yes``, but subs are
+    drawn at the video's native resolution, and scaled along with the video.
+
+    .. warning:: This changes the way subtitle colors are handled. Normally,
+                 subtitle colors are assumed to be in sRGB and color managed as
+                 such. Enabling this makes them treated as being in the video's
+                 color space instead. This is good if you want things like
+                 softsubbed ASS signs to match the video colors, but may cause
+                 SRT subtitles or similar to look slightly off.
+
+``--alpha=<blend-tiles|blend|yes|no>``
+    Decides what to do if the input has an alpha component.
+
+    blend-tiles
+        Blend the frame against a 16x16 gray/white tiles background (default).
+    blend
+        Blend the frame against the background color (``--background``, normally
+        black).
+    yes
+        Try to create a framebuffer with alpha component. This only makes sense
+        if the video contains alpha information (which is extremely rare) or if
+        you make the background color transparent. May not be supported on all
+        platforms. If alpha framebuffers are unavailable, it silently falls
+        back on a normal framebuffer. Note that if you set the ``--fbo-format``
+        option to a non-default value, a format with alpha must be specified,
+        or this won't work. Whether this really works depends on the windowing
+        system and desktop environment.
+    no
+        Ignore alpha component.
+
+``--opengl-rectangle-textures``
+    Force use of rectangle textures (default: no). Normally this shouldn't have
+    any advantages over normal textures. Note that hardware decoding overrides
+    this flag. Could be removed any time.
+
+``--background=<color>``
+    Color used to draw parts of the mpv window not covered by video. See the
+    ``--sub-color`` option for how colors are defined.
+
+``--gpu-tex-pad-x``, ``--gpu-tex-pad-y``
+    Enlarge the video source textures by this many pixels. For debugging only
+    (normally textures are sized exactly, but due to hardware decoding interop
+    we may have to deal with additional padding, which can be tested with these
+    options). Could be removed any time.
+
+``--opengl-early-flush=<yes|no|auto>``
+    Call ``glFlush()`` after rendering a frame and before attempting to display
+    it (default: auto). Can fix stuttering in some cases, in other cases
+    probably causes it. The ``auto`` mode will call ``glFlush()`` only if
+    the renderer is going to wait for a while after rendering, instead of
+    flipping GL front and backbuffers immediately (i.e. it doesn't call it
+    in display-sync mode).
+
+    On macOS this is always deactivated because it only causes performance
+    problems and other regressions.
+
+``--gpu-dumb-mode=<yes|no|auto>``
+    This mode is extremely restricted, and will disable most extended
+    features. That includes high quality scalers and custom shaders!
+
+    It is intended for hardware that does not support FBOs (including GLES,
+    which supports it insufficiently), or to get some more performance out of
+    bad or old hardware.
+
+    This mode is forced automatically if needed, and this option is mostly
+    useful for debugging. The default of ``auto`` will enable it automatically
+    if nothing uses features which require FBOs.
+
+    This option might be silently removed in the future.
+
+``--gpu-shader-cache``
+    Store and load compiled GLSL shaders in the cache directory (Default:
+    ``yes``). Normally, shader compilation is very fast, so this is not usually
+    needed. It mostly matters for anything based on D3D11 (including ANGLE), as
+    well as on some other proprietary drivers. Enabling this can improve startup
+    performance on these platforms.
+
+    NOTE: On ``--vo=gpu``, is not cleaned automatically, so old, unused cache
+    files may stick around indefinitely.
+
+``--gpu-shader-cache-dir``
+    The directory where gpu shader cache is stored. Cache is stored in the system's
+    cache directory (usually ``~/.cache/mpv``) if this is unset.
+
+``--libplacebo-opts=<key>=<value>[,<key>=<value>[,...]]``
+    Passes extra raw option to the libplacebo rendering backend (used by
+    ``--vo=gpu-next``). May override the effects of any other options set using
+    the normal options system. Requires libplacebo v6.309 or higher. Included
+    for debugging purposes only. For more information, see:
+
+    https://libplacebo.org/options/
+
+Miscellaneous
+-------------
+
+``--display-tags=tag1,tags2,...``
+    Set the list of tags that should be displayed on the terminal. Tags that
+    are in the list, but are not present in the played file, will not be shown.
+    If a value ends with ``*``, all tags are matched by prefix (though there
+    is no general globbing). Just passing ``*`` essentially filtering.
+
+    The default includes a common list of tags, call mpv with ``--list-options``
+    to see it.
+
+    This is a string list option. See `List Options`_ for details.
+
+``--mc=<seconds/frame>``
+    Maximum A-V sync correction per frame (in seconds)
+
+``--autosync=<factor>``
+    Gradually adjusts the A/V sync based on audio delay measurements.
+    Specifying ``--autosync=0``, the default, will cause frame timing to be
+    based entirely on audio delay measurements. Specifying ``--autosync=1``
+    will do the same, but will subtly change the A/V correction algorithm. An
+    uneven video framerate in a video which plays fine with ``--no-audio`` can
+    often be helped by setting this to an integer value greater than 1. The
+    higher the value, the closer the timing will be to ``--no-audio``. Try
+    ``--autosync=30`` to smooth out problems with sound drivers which do not
+    implement a perfect audio delay measurement. With this value, if large A/V
+    sync offsets occur, they will only take about 1 or 2 seconds to settle
+    out. This delay in reaction time to sudden A/V offsets should be the only
+    side effect of turning this option on, for all sound drivers.
+
+``--video-timing-offset=<seconds>``
+    Control how long before video display target time the frame should be
+    rendered (default: 0.050). If a video frame should be displayed at a
+    certain time, the VO will start rendering the frame earlier, and then will
+    perform a blocking wait until the display time, and only then "swap" the
+    frame to display. The rendering cannot start before the previous frame is
+    displayed, so this value is implicitly limited by the video framerate. With
+    normal video frame rates, the default value will ensure that rendering is
+    always immediately started after the previous frame was displayed. On the
+    other hand, setting a too high value can reduce responsiveness with low
+    FPS value.
+
+    This option is interesting for client API users using the render API
+    because you can stop it from limiting your FPS
+    (see ``mpv_render_context_render()`` documentation).
+
+    This applies only to audio timing modes (e.g. ``--video-sync=audio``). In
+    other modes (``--video-sync=display-...``), video timing relies on vsync
+    blocking, and this option is not used.
+
+``--video-sync=<audio|...>``
+    How the player synchronizes audio and video.
+
+    If you use this option, you usually want to set it to ``display-resample``
+    to enable a timing mode that tries to not skip or repeat frames when for
+    example playing 24fps video on a 24Hz screen.
+
+    The modes starting with ``display-`` try to output video frames completely
+    synchronously to the display, using the detected display vertical refresh
+    rate as a hint how fast frames will be displayed on average. These modes
+    change video speed slightly to match the display. See ``--video-sync-...``
+    options for fine tuning. The robustness of this mode is further reduced by
+    making a some idealized assumptions, which may not always apply in reality.
+    Behavior can depend on the VO and the system's video and audio drivers.
+    Media files must use constant framerate. Section-wise VFR might work as well
+    with some container formats (but not e.g. mkv).
+
+    Under some circumstances, the player automatically reverts to ``audio`` mode
+    for some time or permanently. This can happen on very low framerate video,
+    or if the framerate cannot be detected.
+
+    Also in display-sync modes it can happen that interruptions to video
+    playback (such as toggling fullscreen mode, or simply resizing the window)
+    will skip the video frames that should have been displayed, while ``audio``
+    mode will display them after the renderer has resumed (typically resulting
+    in a short A/V desync and the video "catching up").
+
+    Before mpv 0.30.0, there was a fallback to ``audio`` mode on severe A/V
+    desync. This was changed for the sake of not sporadically stopping. Now,
+    ``display-desync`` does what it promises and may desync with audio by an
+    arbitrary amount, until it is manually fixed with a seek.
+
+    These modes also require a vsync blocked presentation mode. For OpenGL, this
+    translates to ``--opengl-swapinterval=1``. For Vulkan, it translates to
+    ``--vulkan-swap-mode=fifo`` (or ``fifo-relaxed``).
+
+    The modes with ``desync`` in their names do not attempt to keep audio/video
+    in sync. They will slowly (or quickly) desync, until e.g. the next seek
+    happens. These modes are meant for testing, not serious use.
+
+    :audio:             Time video frames to audio. This is the most robust
+                        mode, because the player doesn't have to assume anything
+                        about how the display behaves. The disadvantage is that
+                        it can lead to occasional frame drops or repeats. If
+                        audio is disabled, this uses the system clock. This is
+                        the default mode.
+    :display-resample:  Resample audio to match the video. This mode will also
+                        try to adjust audio speed to compensate for other drift.
+                        (This means it will play the audio at a different speed
+                        every once in a while to reduce the A/V difference.)
+    :display-resample-vdrop:  Resample audio to match the video. Drop video
+                        frames to compensate for drift.
+    :display-resample-desync: Like the previous mode, but no A/V compensation.
+    :display-tempo:     Same as ``display-resample``, but apply audio speed
+                        changes to audio filters instead of resampling to avoid
+                        the change in pitch. Beware that some audio filters
+                        don't do well with a speed close to 1. It is recommend
+                        to use a conditional profile to automatically switch to
+                        ``display-resample`` when speed gets too close to 1 for
+                        your filter setup. Use (speed * video_speed_correction)
+                        to get the actual playback speed in the condition.
+                        See `Conditional auto profiles`_ for details.
+    :display-vdrop:     Drop or repeat video frames to compensate desyncing
+                        video. (Although it should have the same effects as
+                        ``audio``, the implementation is very different.)
+    :display-adrop:     Drop or repeat audio data to compensate desyncing
+                        video. This mode will cause severe audio artifacts if
+                        the real monitor refresh rate is too different from
+                        the reported or forced rate. Since mpv 0.33.0, this
+                        acts on entire audio frames, instead of single samples.
+    :display-desync:    Sync video to display, and let audio play on its own.
+    :desync:            Sync video according to system clock, and let audio play
+                        on its own.
+
+``--video-sync-max-factor=<value>``
+    Maximum multiple for which to try to fit the video's FPS to the display's
+    FPS (default: 5).
+
+    For example, if this is set to 1, the video FPS is forced to an integer
+    multiple of the display FPS, as long as the speed change does not exceed
+    the value set by ``--video-sync-max-video-change``.
+
+    See ``--interpolation-threshold`` for how this option affects
+    interpolation.
+
+``--video-sync-max-video-change=<value>``
+    Maximum speed difference in percent that is applied to video with
+    ``--video-sync=display-...`` (default: 1). Display sync mode will be
+    disabled if the monitor and video refresh way do not match within the
+    given range. It tries multiples as well: playing 30 fps video on a 60 Hz
+    screen will duplicate every second frame. Playing 24 fps video on a 60 Hz
+    screen will play video in a 2-3-2-3-... pattern.
+
+    The default settings are not loose enough to speed up 23.976 fps video to
+    25 fps. We consider the pitch change too extreme to allow this behavior
+    by default. Set this option to a value of ``5`` to enable it.
+
+    Note that ``--video-sync=display-tempo`` avoids this pitch change.
+
+    Also note that in the ``--video-sync=display-resample`` or
+    ``--video-sync=display-tempo`` mode, audio speed will additionally be
+    changed by a small amount if necessary for A/V sync. See
+    ``--video-sync-max-audio-change``.
+
+``--video-sync-max-audio-change=<value>``
+    Maximum *additional* speed difference in percent that is applied to audio
+    with ``--video-sync=display-...`` (default: 0.125). Normally, the player
+    plays the audio at the speed of the video. But if the difference between
+    audio and video position is too high, e.g. due to drift or other timing
+    errors, it will attempt to speed up or slow down audio by this additional
+    factor. Too low values could lead to video frame dropping or repeating if
+    the A/V desync cannot be compensated, too high values could lead to chaotic
+    frame dropping due to the audio "overshooting" and skipping multiple video
+    frames before the sync logic can react.
+
+``--mf-fps=<value>``
+    Framerate used when decoding from multiple PNG or JPEG files with ``mf://``
+    (default: 1).
+
+``--mf-type=<value>``
+    Input file type for ``mf://`` (available: jpeg, png, tga, sgi). By default,
+    this is guessed from the file extension.
+
+``--stream-dump=<destination-filename>``
+    Instead of playing a file, read its byte stream and write it to the given
+    destination file. The destination is overwritten. Can be useful to test
+    network-related behavior.
+
+``--stream-lavf-o=opt1=value1,opt2=value2,...``
+    Set AVOptions on streams opened with libavformat. Unknown or misspelled
+    options are silently ignored. (They are mentioned in the terminal output
+    in verbose mode, i.e. ``--v``. In general we can't print errors, because
+    other options such as e.g. user agent are not available with all protocols,
+    and printing errors for unknown options would end up being too noisy.)
+
+    This is a key/value list option. See `List Options`_ for details.
+
+``--backdrop-type=<auto|none|mica|acrylic|mica-alt>``
+    (Windows only)
+    Controls the backdrop/border style.
+
+    :auto: Default Windows behavior
+    :none: The backdrop will be black or white depending on the system's theme settings.
+    :mica: Enables the Mica style, which is the default on Windows 11.
+    :acrylic: Enables the Acrylic style (frosted glass look).
+    :mica-alt: Same as Mica, except reversed.
+
+``--window-affinity=<default|excludefromcmcapture|monitor>``
+    (Windows only)
+    Controls the window affinity behavior of mpv.
+
+    :default: Default Windows behavior
+    :excludefromcapture: mpv's window will be completely excluded from capture by external applications or screen recording software.
+    :monitor: Blacks out the mpv window
+
+``--vo-mmcss-profile=<name>``
+    (Windows only)
+    Set the MMCSS profile for the video renderer thread (default: ``Playback``).
+
+``--priority=<prio>``
+    (Windows only)
+    Set process priority for mpv according to the predefined priorities
+    available under Windows.
+
+    Possible values of ``<prio>``:
+    idle|belownormal|normal|abovenormal|high|realtime
+
+    .. warning:: Using realtime priority can cause system lockup.
+
+``--force-media-title=<string>``
+    Force the contents of the ``media-title`` property to this value. Useful
+    for scripts which want to set a title, without overriding the user's
+    setting in ``--title``.
+
+``--external-files=<file-list>``
+    Load a file and add all of its tracks. This is useful to play different
+    files together (for example audio from one file, video from another), or
+    for advanced ``--lavfi-complex`` used (like playing two video files at
+    the same time).
+
+    Unlike ``--sub-files`` and ``--audio-files``, this includes all tracks, and
+    does not cause default stream selection over the "proper" file. This makes
+    it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite
+    strictly enforced.)
+
+    This is a path list option. See `List Options`_ for details.
+
+``--external-file=<file>``
+    CLI/config file only alias for ``--external-files-append``. Each use of this
+    option will add a new external file.
+
+``--cover-art-files=<file-list>``
+    Use an external file as cover art while playing audio. This makes it appear
+    on the track list and subject to automatic track selection. Options like
+    ``--audio-display`` control whether such tracks are supposed to be selected.
+
+    (The difference to loading a file with ``--external-files`` is that video
+    tracks will be marked as being pictures, which affects the auto-selection
+    method. If the passed file is a video, only the first frame will be decoded
+    and displayed. Enabling the cover art track during playback may show a
+    random frame if the source file is a video. Normally you're not supposed to
+    pass videos to this option, so this paragraph describes the behavior
+    coincidentally resulting from implementation details.)
+
+    This is a path list option. See `List Options`_ for details.
+
+``--cover-art-file=<file>``
+    CLI/config file only alias for ``--cover-art-files-append``. Each use of this
+    option will add a new external file.
+
+``--cover-art-auto=<no|exact|fuzzy|all>``
+    Whether to load _external_ cover art automatically. Similar to
+    ``--sub-auto`` and ``--audio-file-auto``. If a video already has tracks
+    (which are not marked as cover art), external cover art will not be loaded.
+
+    :no:    Don't automatically load cover art.
+    :exact: Load the media filename with an image file extension (default).
+    :fuzzy: Load all cover art containing the media filename.
+    :all:   Load all images in the current directory.
+
+    See ``--cover-art-files`` for details about what constitutes cover art.
+
+    See ``--audio-display`` how to control display of cover art (this can be
+    used to disable cover art that is part of the file).
+
+``--cover-art-auto-exts=ext1,ext2,...``
+    Cover art extentions to try and match when using ``cover-art-auto``.
+
+    This is a string list option. See `List Options`_ for details.
+
+``--cover-art-whitelist=<no|yes>``
+    Whether to load files with a filename among "AlbumArt", "Album", "cover",
+    "front", "AlbumArtSmall", "Folder", ".folder", "thumb", and an extension in
+    ``--cover-art-auto-exts``, as cover art. This has no effect if
+    ``cover-art-auto`` is ``no``.
+
+    Default: ``yes``.
+
+``--autoload-files=<yes|no>``
+    Automatically load/select external files (default: yes).
+
+    If set to ``no``, then do not automatically load external files as specified
+    by ``--sub-auto``, ``--audio-file-auto`` and ``--cover-art-auto``. If
+    external files are forcibly added (like with ``--sub-files``), they will
+    not be auto-selected.
+
+    This does not affect playlist expansion, redirection, or other loading of
+    referenced files like with ordered chapters.
+
+``--stream-record=<file>``
+    Write received/read data from the demuxer to the given output file. The
+    output file will always be overwritten without asking. The output format
+    is determined by the extension of the output file.
+
+    Switching streams or seeking during recording might result in recording
+    being stopped and/or broken files. Use with care.
+
+    Seeking outside of the demuxer cache will result in "skips" in the output
+    file, but seeking within  the demuxer cache should not affect recording. One
+    exception is when you seek back far enough to exceed the forward buffering
+    size, in which case the cache stops actively reading. This will return in
+    dropped data if it's a live stream.
+
+    If this is set at runtime, the old file is closed, and the new file is
+    opened. Note that this will write only data that is appended at the end of
+    the cache, and the already cached data cannot be written. You can try the
+    ``dump-cache`` command as an alternative.
+
+    External files (``--audio-file`` etc.) are ignored by this, it works on the
+    "main" file only. Using this with files using ordered chapters or EDL files
+    will also not work correctly in general.
+
+    There are some glitches with this because it uses FFmpeg's libavformat for
+    writing the output file. For example, it's typical that it will only work if
+    the output format is the same as the input format. This is the case even if
+    it works with the ``ffmpeg`` tool. One reason for this is that ``ffmpeg``
+    and its libraries contain certain hacks and workarounds for these issues,
+    that are unavailable to outside users.
+
+``--lavfi-complex=<string>``
+    Set a "complex" libavfilter filter, which means a single filter graph can
+    take input from multiple source audio and video tracks. The graph can result
+    in a single audio or video output (or both).
+
+    Currently, the filter graph labels are used to select the participating
+    input tracks and audio/video output. The following rules apply:
+
+    - A label of the form ``aidN`` selects audio track N as input (e.g.
+      ``aid1``).
+    - A label of the form ``vidN`` selects video track N as input.
+    - A label named ``ao`` will be connected to the audio output.
+    - A label named ``vo`` will be connected to the video output.
+
+    Each label can be used only once. If you want to use e.g. an audio stream
+    for multiple filters, you need to use the ``asplit`` filter. Multiple
+    video or audio outputs are not possible, but you can use filters to merge
+    them into one.
+
+    It's not possible to change the tracks connected to the filter at runtime,
+    unless you explicitly change the ``lavfi-complex`` property and set new
+    track assignments. When the graph is changed, the track selection is changed
+    according to the used labels as well.
+
+    Other tracks, as long as they're not connected to the filter, and the
+    corresponding output is not connected to the filter, can still be freely
+    changed with the normal methods.
+
+    Note that the normal filter chains (``--af``, ``--vf``) are applied between
+    the complex graphs (e.g. ``ao`` label) and the actual output.
+
+    .. admonition:: Examples
+
+        - ``--lavfi-complex='[aid1] [aid2] amix [ao]'``
+          Play audio track 1 and 2 at the same time.
+        - ``--lavfi-complex='[vid1] [vid2] vstack [vo]'``
+          Stack video track 1 and 2 and play them at the same time. Note that
+          both tracks need to have the same width, or filter initialization
+          will fail (you can add ``scale`` filters before the ``vstack`` filter
+          to fix the size).
+          To load a video track from another file, you can use
+          ``--external-file=other.mkv``.
+        - ``--lavfi-complex='[vid1] [vid2] [vid3] hstack=inputs=3 [vo]'``
+          Use the inputs option to stack more than 2 tracks.
+        - ``--lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]'``
+          Play audio track 1, and overlay the measured volume for each speaker
+          over video track 1.
+
+    See the FFmpeg libavfilter documentation for details on the available
+    filters.
+
+``--metadata-codepage=<codepage>``
+    Codepage for various input metadata (default: ``auto``). This affects how
+    file tags, chapter titles, etc. are interpreted. In most cases, this merely
+    evaluates to UTF-8 as non-UTF-8 codepages are obscure.
+
+    See ``--sub-codepage`` option on how codepages are specified and further
+    details regarding autodetection and codepage conversion. (The underlying
+    code is the same.)
+
+    Conversion is not applied to metadata that is updated at runtime.
diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst
new file mode 100644
index 0000000..c791d75
--- /dev/null
+++ b/DOCS/man/osc.rst
@@ -0,0 +1,456 @@
+ON SCREEN CONTROLLER
+====================
+
+The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to
+offer basic mouse-controllability. It is intended to make interaction easier
+for new users and to enable precise and direct seeking.
+
+The OSC is enabled by default if mpv was compiled with Lua support. It can be
+disabled entirely using the ``--osc=no`` option.
+
+Using the OSC
+-------------
+
+By default, the OSC will show up whenever the mouse is moved inside the
+player window and will hide if the mouse is not moved outside the OSC for
+0.5 seconds or if the mouse leaves the window.
+
+The Interface
+~~~~~~~~~~~~~
+
+::
+
+    +---------+----------+------------------------------------------+----------+
+    | pl prev | pl next  |  title                                   |    cache |
+    +------+--+---+------+---------+-----------+------+-------+-----+-----+----+
+    | play | skip | skip | time    |  seekbar  | time | audio | sub | vol | fs |
+    |      | back | frwd | elapsed |           | left |       |     |     |    |
+    +------+------+------+---------+-----------+------+-------+-----+-----+----+
+
+
+pl prev
+    =============   ================================================
+    left-click      play previous file in playlist
+    right-click     show playlist
+    shift+L-click   show playlist
+    =============   ================================================
+
+pl next
+    =============   ================================================
+    left-click      play next file in playlist
+    right-click     show playlist
+    shift+L-click   show playlist
+    =============   ================================================
+
+title
+    | Displays current media-title, filename, custom title, or target chapter
+      name while hovering the seekbar.
+
+    =============   ================================================
+    left-click      show playlist position and length and full title
+    right-click     show filename
+    =============   ================================================
+
+cache
+    | Shows current cache fill status
+
+play
+    =============   ================================================
+    left-click      toggle play/pause
+    =============   ================================================
+
+skip back
+    =============   ================================================
+    left-click      go to beginning of chapter / previous chapter
+    right-click     show chapters
+    shift+L-click   show chapters
+    =============   ================================================
+
+skip frwd
+    =============   ================================================
+    left-click      go to next chapter
+    right-click     show chapters
+    shift+L-click   show chapters
+    =============   ================================================
+
+time elapsed
+    | Shows current playback position timestamp
+
+    =============   ================================================
+    left-click      toggle displaying timecodes with milliseconds
+    =============   ================================================
+
+seekbar
+    | Indicates current playback position and position of chapters
+
+    =============   ================================================
+    left-click      seek to position
+    mouse wheel     seek forward/backward
+    =============   ================================================
+
+time left
+    | Shows remaining playback time timestamp
+
+    =============   ================================================
+    left-click      toggle between total and remaining time
+    =============   ================================================
+
+audio and sub
+    | Displays selected track and amount of available tracks
+
+    =============   ================================================
+    left-click      cycle audio/sub tracks forward
+    right-click     cycle audio/sub tracks backwards
+    shift+L-click   show available audio/sub tracks
+    mouse wheel     cycle audio/sub tracks forward/backwards
+    =============   ================================================
+
+vol
+    =============   ================================================
+    left-click      toggle mute
+    mouse wheel     volume up/down
+    =============   ================================================
+
+fs
+    =============   ================================================
+    left-click      toggle fullscreen
+    =============   ================================================
+
+Key Bindings
+~~~~~~~~~~~~
+
+These key bindings are active by default if nothing else is already bound to
+these keys. In case of collision, the function needs to be bound to a
+different key. See the `Script Commands`_ section.
+
+=============   ================================================
+del             Cycles visibility between never / auto (mouse-move) / always
+=============   ================================================
+
+Configuration
+-------------
+
+The OSC offers limited configuration through a config file
+``script-opts/osc.conf`` placed in mpv's user dir and through the
+``--script-opts`` command-line option. Options provided through the command-line
+will override those from the config file.
+
+Config Syntax
+~~~~~~~~~~~~~
+
+The config file must exactly follow the following syntax::
+
+    # this is a comment
+    optionA=value1
+    optionB=value2
+
+``#`` can only be used at the beginning of a line and there may be no
+spaces around the ``=`` or anywhere else.
+
+Command-line Syntax
+~~~~~~~~~~~~~~~~~~~
+
+To avoid collisions with other scripts, all options need to be prefixed with
+``osc-``.
+
+Example::
+
+    --script-opts=osc-optionA=value1,osc-optionB=value2
+
+
+Configurable Options
+~~~~~~~~~~~~~~~~~~~~
+
+``layout``
+    Default: bottombar
+
+    The layout for the OSC. Currently available are: box, slimbox,
+    bottombar and topbar. Default pre-0.21.0 was 'box'.
+
+``seekbarstyle``
+    Default: bar
+
+    Sets the style of the playback position marker and overall shape
+    of the seekbar: ``bar``, ``diamond`` or ``knob``.
+
+``seekbarhandlesize``
+    Default: 0.6
+
+    Size ratio of the seek handle if ``seekbarstyle`` is set to ``diamond``
+    or ``knob``. This is relative to the full height of the seekbar.
+
+``seekbarkeyframes``
+    Default: yes
+
+    Controls the mode used to seek when dragging the seekbar. If set to ``yes``,
+    default seeking mode is used (usually keyframes, but player defaults and
+    heuristics can change it to exact). If set to ``no``, exact seeking on
+    mouse drags will be used instead. Keyframes are preferred, but exact seeks
+    may be useful in cases where keyframes cannot be found. Note that using
+    exact seeks can potentially make mouse dragging much slower.
+
+``seekrangestyle``
+    Default: inverted
+
+    Display seekable ranges on the seekbar. ``bar`` shows them on the full
+    height of the bar, ``line`` as a thick line and ``inverted`` as a thin
+    line that is inverted over playback position markers. ``none`` will hide
+    them. Additionally, ``slider`` will show a permanent handle inside the seekbar
+    with cached ranges marked inside. Note that these will look differently
+    based on the seekbarstyle option. Also, ``slider`` does not work with
+    ``seekbarstyle`` set to ``bar``.
+
+``seekrangeseparate``
+    Default: yes
+
+    Controls whether to show line-style seekable ranges on top of the
+    seekbar or separately if ``seekbarstyle`` is set to ``bar``.
+
+``seekrangealpha``
+    Default: 200
+
+    Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent).
+
+``deadzonesize``
+    Default: 0.5
+
+    Size of the deadzone. The deadzone is an area that makes the mouse act
+    like leaving the window. Movement there won't make the OSC show up and
+    it will hide immediately if the mouse enters it. The deadzone starts
+    at the window border opposite to the OSC and the size controls how much
+    of the window it will span. Values between 0.0 and 1.0, where 0 means the
+    OSC will always popup with mouse movement in the window, and 1 means the
+    OSC will only show up when the mouse hovers it. Default pre-0.21.0 was 0.
+
+``minmousemove``
+    Default: 0
+
+    Minimum amount of pixels the mouse has to move between ticks to make
+    the OSC show up. Default pre-0.21.0 was 3.
+
+``showwindowed``
+    Default: yes
+
+    Enable the OSC when windowed
+
+``showfullscreen``
+    Default: yes
+
+    Enable the OSC when fullscreen
+
+``idlescreen``
+    Default: yes
+
+    Show the mpv logo and message when idle
+
+``scalewindowed``
+    Default: 1.0
+
+    Scale factor of the OSC when windowed.
+
+``scalefullscreen``
+    Default: 1.0
+
+    Scale factor of the OSC when fullscreen
+
+``scaleforcedwindow``
+    Default: 2.0
+
+    Scale factor of the OSC when rendered on a forced (dummy) window
+
+``vidscale``
+    Default: yes
+
+    Scale the OSC with the video
+    ``no`` tries to keep the OSC size constant as much as the window size allows
+
+``valign``
+    Default: 0.8
+
+    Vertical alignment, -1 (top) to 1 (bottom)
+
+``halign``
+    Default: 0.0
+
+    Horizontal alignment, -1 (left) to 1 (right)
+
+``barmargin``
+    Default: 0
+
+    Margin from bottom (bottombar) or top (topbar), in pixels
+
+``boxalpha``
+    Default: 80
+
+    Alpha of the background box, 0 (opaque) to 255 (fully transparent)
+
+``hidetimeout``
+    Default: 500
+
+    Duration in ms until the OSC hides if no mouse movement, must not be
+    negative
+
+``fadeduration``
+    Default: 200
+
+    Duration of fade out in ms, 0 = no fade
+
+``title``
+    Default: ${media-title}
+
+    String that supports property expansion that will be displayed as
+    OSC title.
+    ASS tags are escaped, and newlines and trailing slashes are stripped.
+
+``tooltipborder``
+    Default: 1
+
+    Size of the tooltip outline when using bottombar or topbar layouts
+
+``timetotal``
+    Default: no
+
+    Show total time instead of time remaining
+
+``remaining_playtime``
+    Default: yes
+
+    Whether the time-remaining display takes speed into account.
+    ``yes`` - how much playback time remains at the current speed.
+    ``no`` - how much video-time remains.
+
+``timems``
+    Default: no
+
+    Display timecodes with milliseconds
+
+``tcspace``
+    Default: 100 (allowed: 50-200)
+
+    Adjust space reserved for timecodes (current time and time remaining) in
+    the ``bottombar`` and ``topbar`` layouts. The timecode width depends on the
+    font, and with some fonts the spacing near the timecodes becomes too small.
+    Use values above 100 to increase that spacing, or below 100 to decrease it.
+
+``visibility``
+    Default: auto (auto hide/show on mouse move)
+
+    Also supports ``never`` and ``always``
+
+``boxmaxchars``
+    Default: 80
+
+    Max chars for the osc title at the box layout. mpv does not measure the
+    text width on screen and so it needs to limit it by number of chars. The
+    default is conservative to allow wide fonts to be used without overflow.
+    However, with many common fonts a bigger number can be used. YMMV.
+
+``boxvideo``
+    Default: no
+
+    Whether to overlay the osc over the video (``no``), or to box the video
+    within the areas not covered by the osc (``yes``). If this option is set,
+    the osc may overwrite the ``--video-margin-ratio-*`` options, even if the
+    user has set them. (It will not overwrite them if all of them are set to
+    default values.) Additionally, ``visibility`` must be set to ``always``.
+    Otherwise, this option does nothing.
+
+    Currently, this is supported for the ``bottombar`` and ``topbar`` layout
+    only. The other layouts do not change if this option is set. Separately,
+    if window controls are present (see below), they will be affected
+    regardless of which osc layout is in use.
+
+    The border is static and appears even if the OSC is configured to appear
+    only on mouse interaction. If the OSC is invisible, the border is simply
+    filled with the background color (black by default).
+
+    This currently still makes the OSC overlap with subtitles (if the
+    ``--sub-use-margins`` option is set to ``yes``, the default). This may be
+    fixed later.
+
+    This does not work correctly with video outputs like ``--vo=xv``, which
+    render OSD into the unscaled video.
+
+``windowcontrols``
+    Default: auto (Show window controls if there is no window border)
+
+    Whether to show window management controls over the video, and if so,
+    which side of the window to place them. This may be desirable when the
+    window has no decorations, either because they have been explicitly
+    disabled (``border=no``) or because the current platform doesn't support
+    them (eg: gnome-shell with wayland).
+
+    The set of window controls is fixed, offering ``minimize``, ``maximize``,
+    and ``quit``. Not all platforms implement ``minimize`` and ``maximize``,
+    but ``quit`` will always work.
+
+``windowcontrols_alignment``
+    Default: right
+
+    If window controls are shown, indicates which side should they be aligned
+    to.
+
+    Supports ``left`` and ``right`` which will place the controls on those
+    respective sides.
+
+``greenandgrumpy``
+    Default: no
+
+    Set to ``yes`` to reduce festivity (i.e. disable santa hat in December.)
+
+``livemarkers``
+    Default: yes
+
+    Update chapter markers positions on duration changes, e.g. live streams.
+    The updates are unoptimized - consider disabling it on very low-end systems.
+
+``chapters_osd``, ``playlist_osd``
+    Default: yes
+
+    Whether to display the chapters/playlist at the OSD when left-clicking the
+    next/previous OSC buttons, respectively.
+
+``chapter_fmt``
+    Default: ``Chapter: %s``
+
+    Template for the chapter-name display when hovering the seekbar.
+    Use ``no`` to disable chapter display on hover. Otherwise it's a lua
+    ``string.format`` template and ``%s`` is replaced with the actual name.
+
+``unicodeminus``
+    Default: no
+
+    Use a Unicode minus sign instead of an ASCII hyphen when displaying
+    the remaining playback time.
+
+
+Script Commands
+~~~~~~~~~~~~~~~
+
+The OSC script listens to certain script commands. These commands can bound
+in ``input.conf``, or sent by other scripts.
+
+``osc-message``
+    Show a message on screen using the OSC. First argument is the message,
+    second the duration in seconds.
+
+``osc-visibility``
+    Controls visibility mode ``never`` / ``auto`` (on mouse move) / ``always``
+    and also ``cycle`` to cycle between the modes
+
+Example
+
+You could put this into ``input.conf`` to hide the OSC with the ``a`` key and
+to set auto mode (the default) with ``b``::
+
+    a script-message osc-visibility never
+    b script-message osc-visibility auto
+
+``osc-idlescreen``
+    Controls the visibility of the mpv logo on idle. Valid arguments are ``yes``,
+    ``no``, and ``cycle`` to toggle between yes and no.
+
+``osc-playlist``, ``osc-chapterlist``, ``osc-tracklist``
+    Shows a limited view of the respective type of list using the OSC. First
+    argument is duration in seconds.
+
diff --git a/DOCS/man/stats.rst b/DOCS/man/stats.rst
new file mode 100644
index 0000000..88238bc
--- /dev/null
+++ b/DOCS/man/stats.rst
@@ -0,0 +1,233 @@
+STATS
+=====
+
+This builtin script displays information and statistics for the currently
+played file. It is enabled by default if mpv was compiled with Lua support.
+It can be disabled entirely using the ``--load-stats-overlay=no`` option.
+
+Usage
+-----
+
+The following key bindings are active by default unless something else is
+already bound to them:
+
+====   ==============================================
+i      Show stats for a fixed duration
+I      Toggle stats (shown until toggled again)
+====   ==============================================
+
+While the stats are visible on screen the following key bindings are active,
+regardless of existing bindings. They allow you to switch between *pages* of
+stats:
+
+====   ==================
+1      Show usual stats
+2      Show frame timings (scroll)
+3      Input cache stats
+4      Active key bindings (scroll)
+0      Internal stuff (scroll)
+====   ==================
+
+On pages which support scroll, these key bindings are also active:
+
+====   ==================
+UP      Scroll one line up
+DOWN    Scroll one line down
+====   ==================
+
+Configuration
+-------------
+
+This script can be customized through a config file ``script-opts/stats.conf``
+placed in mpv's user directory and through the ``--script-opts`` command-line
+option. The configuration syntax is described in `ON SCREEN CONTROLLER`_.
+
+Configurable Options
+~~~~~~~~~~~~~~~~~~~~
+
+``key_page_1``
+    Default: 1
+``key_page_2``
+    Default: 2
+``key_page_3``
+    Default: 3
+``key_page_4``
+    Default: 4
+``key_page_0``
+    Default: 0
+
+    Key bindings for page switching while stats are displayed.
+
+``key_scroll_up``
+    Default: UP
+``key_scroll_down``
+    Default: DOWN
+``scroll_lines``
+    Default: 1
+
+    Scroll key bindings and number of lines to scroll on pages which support it.
+
+``duration``
+    Default: 4
+
+    How long the stats are shown in seconds (oneshot).
+
+``redraw_delay``
+    Default: 1
+
+    How long it takes to refresh the displayed stats in seconds (toggling).
+
+``persistent_overlay``
+    Default: no
+
+    When `no`, other scripts printing text to the screen can overwrite the
+    displayed stats. When `yes`, displayed stats are persistently shown for the
+    respective duration. This can result in overlapping text when multiple
+    scripts decide to print text at the same time.
+
+``plot_perfdata``
+    Default: yes
+
+    Show graphs for performance data (page 2).
+
+``plot_vsync_ratio``
+    Default: yes
+``plot_vsync_jitter``
+    Default: yes
+
+    Show graphs for vsync and jitter values (page 1). Only when toggled.
+
+``plot_tonemapping_lut``
+    Default: no
+
+    Enable tone-mapping LUT visualization automatically. Only when toggled.
+
+``flush_graph_data``
+    Default: yes
+
+    Clear data buffers used for drawing graphs when toggling.
+
+``font``
+    Default: sans-serif
+
+    Font name. Should support as many font weights as possible for optimal
+    visual experience.
+
+``font_mono``
+    Default: monospace
+
+    Font name for parts where monospaced characters are necessary to align
+    text. Currently, monospaced digits are sufficient.
+
+``font_size``
+    Default: 8
+
+    Font size used to render text.
+
+``font_color``
+    Default: FFFFFF
+
+    Font color.
+
+``border_size``
+    Default: 0.8
+
+    Size of border drawn around the font.
+
+``border_color``
+    Default: 262626
+
+    Color of drawn border.
+
+``alpha``
+    Default: 11
+
+    Transparency for drawn text.
+
+``plot_bg_border_color``
+    Default: 0000FF
+
+    Border color used for drawing graphs.
+
+``plot_bg_color``
+    Default: 262626
+
+    Background color used for drawing graphs.
+
+``plot_color``
+    Default: FFFFFF
+
+    Color used for drawing graphs.
+
+Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR
+(blue green red).
+
+Different key bindings
+~~~~~~~~~~~~~~~~~~~~~~
+
+Additional keys can be configured in ``input.conf`` to display the stats::
+
+    e script-binding stats/display-stats
+    E script-binding stats/display-stats-toggle
+
+And to display a certain page directly::
+
+    i script-binding stats/display-page-1
+    e script-binding stats/display-page-2
+
+Active key bindings page
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lists the active key bindings and the commands they're bound to, excluding the
+interactive keys of the stats script itself. See also ``--input-test`` for more
+detailed view of each binding.
+
+The keys are grouped automatically using a simple analysis of the command
+string, and one should not expect documentation-level grouping accuracy,
+however, it should still be reasonably useful.
+
+Using ``--idle --script-opts=stats-bindlist=yes`` will print the list to the
+terminal and quit immediately. By default long lines are shortened to 79 chars,
+and terminal escape sequences are enabled. A different length limit can be
+set by changing ``yes`` to a number (at least 40), and escape sequences can be
+disabled by adding ``-`` before the value, e.g. ``...=-yes`` or ``...=-120``.
+
+Like with ``--input-test``, the list includes bindings from ``input.conf`` and
+from user scripts. Use ``--no-config`` to list only built-in bindings.
+
+Internal stuff page
+~~~~~~~~~~~~~~~~~~~
+
+Most entries shown on this page have rather vague meaning. Likely none of this
+is useful for you. Don't attempt to use it. Forget its existence.
+
+Selecting this for the first time will start collecting some internal
+performance data. That means performance will be slightly lower than normal for
+the rest of the time the player is running (even if the stats page is closed).
+Note that the stats page itself uses a lot of CPU and even GPU resources, and
+may have a heavy impact on performance.
+
+The displayed information is accumulated over the redraw delay (shown as
+``poll-time`` field).
+
+This adds entries for each Lua script. If there are too many scripts running,
+parts of the list will simply be out of the screen, but it can be scrolled.
+
+If the underlying platform does not support pthread per thread times, the
+displayed times will be 0 or something random (I suspect that at time of this
+writing, only Linux provides the correct via pthread APIs for per thread times).
+
+Most entries are added lazily and only during data collection, which is why
+entries may pop up randomly after some time. It's also why the memory usage
+entries for scripts that have been inactive since the start of data collection
+are missing.
+
+Memory usage is approximate and does not reflect internal fragmentation.
+
+JS scripts memory reporting is disabled by default because collecting the data
+at the JS side has an overhead and will increase memory usage. It can be
+enabled by setting the ``--js-memory-report`` option before starting mpv.
+
+If entries have ``/time`` and ``/cpu`` variants, the former gives the real time
+(monotonic clock), while the latter the thread CPU time (only if the
+corresponding pthread API works and is supported).
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
new file mode 100644
index 0000000..1423e4c
--- /dev/null
+++ b/DOCS/man/vf.rst
@@ -0,0 +1,794 @@
+VIDEO FILTERS
+=============
+
+Video filters allow you to modify the video stream and its properties. All of
+the information described in this section applies to audio filters as well
+(generally using the prefix ``--af`` instead of ``--vf``).
+
+The exact syntax is:
+
+``--vf=<filter1[=parameter1:parameter2:...],filter2,...>``
+    Setup a chain of video filters. This consists on the filter name, and an
+    option list of parameters after ``=``. The parameters are separated by
+    ``:`` (not ``,``, as that starts a new filter entry).
+
+    Before the filter name, a label can be specified with ``@name:``, where
+    name is an arbitrary user-given name, which identifies the filter. This
+    is only needed if you want to toggle the filter at runtime.
+
+    A ``!`` before the filter name means the filter is disabled by default. It
+    will be skipped on filter creation. This is also useful for runtime filter
+    toggling.
+
+    See the ``vf`` command (and ``toggle`` sub-command) for further explanations
+    and examples.
+
+    The general filter entry syntax is:
+
+        ``["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-parameter-list> ]``
+
+    or for the special "toggle" syntax (see ``vf`` command):
+
+        ``"@"<label-name>``
+
+    and the ``filter-parameter-list``:
+
+        ``<filter-parameter> | <filter-parameter> "," <filter-parameter-list>``
+
+    and ``filter-parameter``:
+
+        ``( <param-name> "=" <param-value> ) | <param-value>``
+
+    ``param-value`` can further be quoted in ``[`` / ``]`` in case the value
+    contains characters like ``,`` or ``=``. This is used in particular with
+    the ``lavfi`` filter, which uses a very similar syntax as mpv (MPlayer
+    historically) to specify filters and their parameters.
+
+.. note::
+
+    ``--vf`` can only take a single track as input, even if the filter supports
+    dynamic input. Filters that require multiple inputs can't be used.
+    Use ``--lavfi-complex`` for such a use case. This also applies for ``--af``.
+
+Filters can be manipulated at run time. You can use ``@`` labels as described
+above in combination with the ``vf`` command (see `COMMAND INTERFACE`_) to get
+more control over this. Initially disabled filters with ``!`` are useful for
+this as well.
+
+.. note::
+
+    To get a full list of available video filters, see ``--vf=help`` and
+    https://ffmpeg.org/ffmpeg-filters.html .
+
+    Also, keep in mind that most actual filters are available via the ``lavfi``
+    wrapper, which gives you access to most of libavfilter's filters. This
+    includes all filters that have been ported from MPlayer to libavfilter.
+
+    Most builtin filters are deprecated in some ways, unless they're only available
+    in mpv (such as filters which deal with mpv specifics, or which are
+    implemented in mpv only).
+
+    If a filter is not builtin, the ``lavfi-bridge`` will be automatically
+    tried. This bridge does not support help output, and does not verify
+    parameters before the filter is actually used. Although the mpv syntax
+    is rather similar to libavfilter's, it's not the same. (Which means not
+    everything accepted by vf_lavfi's ``graph`` option will be accepted by
+    ``--vf``.)
+
+    You can also prefix the filter name with ``lavfi-`` to force the wrapper.
+    This is helpful if the filter name collides with a deprecated mpv builtin
+    filter. For example ``--vf=lavfi-scale=args`` would use libavfilter's
+    ``scale`` filter over mpv's deprecated builtin one.
+
+Video filters are managed in lists. There are a few commands to manage the
+filter list.
+
+``--vf-append=filter``
+    Appends the filter given as arguments to the filter list.
+
+``--vf-add=filter``
+    Appends the filter given as arguments to the filter list. (Passing multiple
+    filters is currently still possible, but deprecated.)
+
+``--vf-pre=filter``
+    Prepends the filters given as arguments to the filter list. (Passing
+    multiple filters is currently still possible, but deprecated.)
+
+``--vf-remove=filter``
+    Deletes the filter from the list. The filter can be either given the way it
+    was added (filter name and its full argument list), or by label (prefixed
+    with ``@``). Matching of filters works as follows: if either of the compared
+    filters has a label set, only the labels are compared. If none of the
+    filters have a label, the filter name, arguments, and argument order are
+    compared. (Passing multiple filters is currently still possible, but
+    deprecated.)
+
+``-vf-toggle=filter``
+    Add the given filter to the list if it was not present yet, or remove it
+    from the list if it was present. Matching of filters works as described in
+    ``--vf-remove``.
+
+``--vf-clr``
+    Completely empties the filter list.
+
+With filters that support it, you can access parameters by their name.
+
+``--vf=<filter>=help``
+    Prints the parameter names and parameter value ranges for a particular
+    filter.
+
+Available mpv-only filters are:
+
+``format=fmt=<value>:colormatrix=<value>:...``
+    Applies video parameter overrides, with optional conversion. By default,
+    this overrides the video's parameters without conversion (except for the
+    ``fmt`` parameter), but can be made to perform an appropriate conversion
+    with ``convert=yes`` for parameters for which conversion is supported.
+
+    ``<fmt>``
+        Image format name, e.g. rgb15, bgr24, 420p, etc. (default: don't change).
+
+        This filter always performs conversion to the given format.
+
+        .. note::
+
+            For a list of available formats, use ``--vf=format=fmt=help``.
+
+        .. note::
+
+            Conversion between hardware formats is supported in some cases.
+            eg: ``cuda`` to ``vulkan``, or ``vaapi`` to ``vulkan``.
+
+    ``<convert=yes|no>``
+        Force conversion of color parameters (default: no).
+
+        If this is disabled (the default), the only conversion that is possibly
+        performed is format conversion if ``<fmt>`` is set. All other parameters
+        (like ``<colormatrix>``) are forced without conversion. This mode is
+        typically useful when files have been incorrectly tagged.
+
+        If this is enabled, libswscale or zimg is used if any of the parameters
+        mismatch. zimg is used of the input/output image formats are supported
+        by mpv's zimg wrapper, and if ``--sws-allow-zimg=yes`` is used. Both
+        libraries may not support all kinds of conversions. This typically
+        results in silent incorrect conversion. zimg has in many cases a better
+        chance of performing the conversion correctly.
+
+        In both cases, the color parameters are set on the output stage of the
+        image format conversion (if ``fmt`` was set). The difference is that
+        with ``convert=no``, the color parameters are not passed on to the
+        converter.
+
+        If input and output video parameters are the same, conversion is always
+        skipped.
+
+        When converting between hardware formats, this parameter has no effect,
+        and the only conversion that is done is the format conversion.
+
+        .. admonition:: Examples
+
+            ``mpv test.mkv --vf=format:colormatrix=ycgco``
+                Results in incorrect colors (if test.mkv was tagged correctly).
+
+            ``mpv test.mkv --vf=format:colormatrix=ycgco:convert=yes --sws-allow-zimg``
+                Results in true conversion to ``ycgco``, assuming the renderer
+                supports it (``--vo=gpu`` normally does). You can add ``--vo=xv``
+                to force a VO which definitely does not support it, which should
+                show incorrect colors as confirmation.
+
+                Using ``--sws-allow-zimg=no`` (or disabling zimg at build time)
+                will use libswscale, which cannot perform this conversion as
+                of this writing.
+
+    ``<colormatrix>``
+        Controls the YUV to RGB color space conversion when playing video. There
+        are various standards. Normally, BT.601 should be used for SD video, and
+        BT.709 for HD video. (This is done by default.) Using incorrect color space
+        results in slightly under or over saturated and shifted colors.
+
+        These options are not always supported. Different video outputs provide
+        varying degrees of support. The ``gpu`` and ``vdpau`` video output
+        drivers usually offer full support. The ``xv`` output can set the color
+        space if the system video driver supports it, but not input and output
+        levels. The ``scale`` video filter can configure color space and input
+        levels, but only if the output format is RGB (if the video output driver
+        supports RGB output, you can force this with ``-vf scale,format=rgba``).
+
+        If this option is set to ``auto`` (which is the default), the video's
+        color space flag will be used. If that flag is unset, the color space
+        will be selected automatically. This is done using a simple heuristic that
+        attempts to distinguish SD and HD video. If the video is larger than
+        1279x576 pixels, BT.709 (HD) will be used; otherwise BT.601 (SD) is
+        selected.
+
+        Available color spaces are:
+
+        :auto:          automatic selection (default)
+        :bt.601:        ITU-R BT.601 (SD)
+        :bt.709:        ITU-R BT.709 (HD)
+        :bt.2020-ncl:   ITU-R BT.2020 non-constant luminance system
+        :bt.2020-cl:    ITU-R BT.2020 constant luminance system
+        :smpte-240m:    SMPTE-240M
+
+    ``<colorlevels>``
+        YUV color levels used with YUV to RGB conversion. This option is only
+        necessary when playing broken files which do not follow standard color
+        levels or which are flagged wrong. If the video does not specify its
+        color range, it is assumed to be limited range.
+
+        The same limitations as with ``<colormatrix>`` apply.
+
+        Available color ranges are:
+
+        :auto:      automatic selection (normally limited range) (default)
+        :limited:   limited range (16-235 for luma, 16-240 for chroma)
+        :full:      full range (0-255 for both luma and chroma)
+
+    ``<primaries>``
+        RGB primaries the source file was encoded with. Normally this should be set
+        in the file header, but when playing broken or mistagged files this can be
+        used to override the setting.
+
+        This option only affects video output drivers that perform color
+        management, for example ``gpu`` with the ``target-prim`` or
+        ``icc-profile`` suboptions set.
+
+        If this option is set to ``auto`` (which is the default), the video's
+        primaries flag will be used. If that flag is unset, the color space will
+        be selected automatically, using the following heuristics: If the
+        ``<colormatrix>`` is set or determined as BT.2020 or BT.709, the
+        corresponding primaries are used. Otherwise, if the video height is
+        exactly 576 (PAL), BT.601-625 is used. If it's exactly 480 or 486 (NTSC),
+        BT.601-525 is used. If the video resolution is anything else, BT.709 is
+        used.
+
+        Available primaries are:
+
+        :auto:         automatic selection (default)
+        :bt.601-525:   ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)
+        :bt.601-625:   ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)
+        :bt.709:       ITU-R BT.709 (HD) (same primaries as sRGB)
+        :bt.2020:      ITU-R BT.2020 (UHD)
+        :apple:        Apple RGB
+        :adobe:        Adobe RGB (1998)
+        :prophoto:     ProPhoto RGB (ROMM)
+        :cie1931:      CIE 1931 RGB
+        :dci-p3:       DCI-P3 (Digital Cinema)
+        :v-gamut:      Panasonic V-Gamut primaries
+
+    ``<gamma>``
+       Gamma function the source file was encoded with. Normally this should be set
+       in the file header, but when playing broken or mistagged files this can be
+       used to override the setting.
+
+       This option only affects video output drivers that perform color management.
+
+       If this option is set to ``auto`` (which is the default), the gamma will
+       be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for
+       XYZ content.
+
+       Available gamma functions are:
+
+       :auto:         automatic selection (default)
+       :bt.1886:      ITU-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020)
+       :srgb:         IEC 61966-2-4 (sRGB)
+       :linear:       Linear light
+       :gamma1.8:     Pure power curve (gamma 1.8)
+       :gamma2.0:     Pure power curve (gamma 2.0)
+       :gamma2.2:     Pure power curve (gamma 2.2)
+       :gamma2.4:     Pure power curve (gamma 2.4)
+       :gamma2.6:     Pure power curve (gamma 2.6)
+       :gamma2.8:     Pure power curve (gamma 2.8)
+       :prophoto:     ProPhoto RGB (ROMM) curve
+       :pq:           ITU-R BT.2100 PQ (Perceptual quantizer) curve
+       :hlg:          ITU-R BT.2100 HLG (Hybrid Log-gamma) curve
+       :v-log:        Panasonic V-Log transfer curve
+       :s-log1:       Sony S-Log1 transfer curve
+       :s-log2:       Sony S-Log2 transfer curve
+
+    ``<sig-peak>``
+        Reference peak illumination for the video file, relative to the
+        signal's reference white level. This is mostly interesting for HDR, but
+        it can also be used tone map SDR content to simulate a different
+        exposure. Normally inferred from tags such as MaxCLL or mastering
+        metadata.
+
+        The default of 0.0 will default to the source's nominal peak luminance.
+
+    ``<light>``
+        Light type of the scene. This is mostly correctly inferred based on the
+        gamma function, but it can be useful to override this when viewing raw
+        camera footage (e.g. V-Log), which is normally scene-referred instead
+        of display-referred.
+
+        Available light types are:
+
+       :auto:         Automatic selection (default)
+       :display:      Display-referred light (most content)
+       :hlg:          Scene-referred using the HLG OOTF (e.g. HLG content)
+       :709-1886:     Scene-referred using the BT709+BT1886 interaction
+       :gamma1.2:     Scene-referred using a pure power OOTF (gamma=1.2)
+
+    ``<dolbyvision=yes|no>``
+        Whether or not to include Dolby Vision metadata (default: yes). If
+        disabled, any Dolby Vision metadata will be stripped from frames.
+
+    ``<film-grain=yes|no>``
+        Whether or not to include film grain metadata (default: yes). If
+        disabled, any film grain metadata will be stripped from frames.
+
+    ``<stereo-in>``
+        Set the stereo mode the video is assumed to be encoded in. Use
+        ``--vf=format:stereo-in=help`` to list all available modes. Check with
+        the ``stereo3d`` filter documentation to see what the names mean.
+
+    ``<stereo-out>``
+        Set the stereo mode the video should be displayed as. Takes the
+        same values as the ``stereo-in`` option.
+
+    ``<rotate>``
+        Set the rotation the video is assumed to be encoded with in degrees.
+        The special value ``-1`` uses the input format.
+
+    ``<w>``, ``<h>``
+        If not 0, perform conversion to the given size. Ignored if
+        ``convert=yes`` is not set.
+
+    ``<dw>``, ``<dh>``
+        Set the display size. Note that setting the display size such that
+        the video is scaled in both directions instead of just changing the
+        aspect ratio is an implementation detail, and might change later.
+
+    ``<dar>``
+        Set the display aspect ratio of the video frame. This is a float,
+        but values such as ``[16:9]`` can be passed too (``[...]`` for quoting
+        to prevent the option parser from interpreting the ``:`` character).
+
+    ``<force-scaler=auto|zimg|sws>``
+        Force a specific scaler backend, if applicable. This is a debug option
+        and could go away any time.
+
+    ``<alpha=auto|straight|premul>``
+        Set the kind of alpha the video uses. Undefined effect if the image
+        format has no alpha channel (could be ignored or cause an error,
+        depending on how mpv internals evolve). Setting this may or may not
+        cause downstream image processing to treat alpha differently, depending
+        on support. With ``convert`` and zimg used, this will convert the alpha.
+        libswscale and other FFmpeg components completely ignore this.
+
+``lavfi=graph[:sws-flags[:o=opts]]``
+    Filter video using FFmpeg's libavfilter.
+
+    ``<graph>``
+        The libavfilter graph string. The filter must have a single video input
+        pad and a single video output pad.
+
+        See `<https://ffmpeg.org/ffmpeg-filters.html>`_ for syntax and available
+        filters.
+
+        .. warning::
+
+            If you want to use the full filter syntax with this option, you have
+            to quote the filter graph in order to prevent mpv's syntax and the
+            filter graph syntax from clashing. To prevent a quoting and escaping
+            mess, consider using ``--lavfi-complex`` if you know which video
+            track you want to use from the input file. (There is only one video
+            track for nearly all video files anyway.)
+
+        .. admonition:: Examples
+
+            ``--vf=lavfi=[gradfun=20:30,vflip]``
+                ``gradfun`` filter with nonsense parameters, followed by a
+                ``vflip`` filter. (This demonstrates how libavfilter takes a
+                graph and not just a single filter.) The filter graph string is
+                quoted with ``[`` and ``]``. This requires no additional quoting
+                or escaping with some shells (like bash), while others (like
+                zsh) require additional ``"`` quotes around the option string.
+
+            ``'--vf=lavfi="gradfun=20:30,vflip"'``
+                Same as before, but uses quoting that should be safe with all
+                shells. The outer ``'`` quotes make sure that the shell does not
+                remove the ``"`` quotes needed by mpv.
+
+            ``'--vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"'``
+                Same as before, but uses named parameters for everything.
+
+    ``<sws-flags>``
+        If libavfilter inserts filters for pixel format conversion, this
+        option gives the flags which should be passed to libswscale. This
+        option is numeric and takes a bit-wise combination of ``SWS_`` flags.
+
+        See ``https://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h``.
+
+    ``<o>``
+        Set AVFilterGraph options. These should be documented by FFmpeg.
+
+        .. admonition:: Example
+
+            ``'--vf=lavfi=yadif:o="threads=2,thread_type=slice"'``
+                forces a specific threading configuration.
+
+``sub=[=bottom-margin:top-margin]``
+    Moves subtitle rendering to an arbitrary point in the filter chain, or force
+    subtitle rendering in the video filter as opposed to using video output OSD
+    support.
+
+    ``<bottom-margin>``
+        Adds a black band at the bottom of the frame. The SSA/ASS renderer can
+        place subtitles there (with ``--sub-use-margins``).
+    ``<top-margin>``
+        Black band on the top for toptitles  (with ``--sub-use-margins``).
+
+    .. admonition:: Examples
+
+        ``--vf=sub,eq``
+            Moves sub rendering before the eq filter. This will put both
+            subtitle colors and video under the influence of the video equalizer
+            settings.
+
+``vapoursynth=file:buffered-frames:concurrent-frames``
+    Loads a VapourSynth filter script. This is intended for streamed
+    processing: mpv actually provides a source filter, instead of using a
+    native VapourSynth video source. The mpv source will answer frame
+    requests only within a small window of frames (the size of this window
+    is controlled with the ``buffered-frames`` parameter), and requests outside
+    of that will return errors. As such, you can't use the full power of
+    VapourSynth, but you can use certain filters.
+
+    .. warning::
+
+        Do not use this filter, unless you have expert knowledge in VapourSynth,
+        and know how to fix bugs in the mpv VapourSynth wrapper code.
+
+    If you just want to play video generated by VapourSynth (i.e. using
+    a native VapourSynth video source), it's better to use ``vspipe`` and a
+    pipe or FIFO to feed the video to mpv. The same applies if the filter script
+    requires random frame access (see ``buffered-frames`` parameter).
+
+    ``file``
+        Filename of the script source. Currently, this is always a python
+        script (``.vpy`` in VapourSynth convention).
+
+        The variable ``video_in`` is set to the mpv video source, and it is
+        expected that the script reads video from it. (Otherwise, mpv will
+        decode no video, and the video packet queue will overflow, eventually
+        leading to only audio playing, or worse.)
+
+        The filter graph created by the script is also expected to pass through
+        timestamps using the ``_DurationNum`` and ``_DurationDen`` frame
+        properties.
+
+        See the end of the option list for a full list of script variables
+        defined by mpv.
+
+        .. admonition:: Example:
+
+            ::
+
+                import vapoursynth as vs
+                from vapoursynth import core
+                core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
+
+        .. warning::
+
+            The script will be reloaded on every seek. This is done to reset
+            the filter properly on discontinuities.
+
+    ``buffered-frames``
+        Maximum number of decoded video frames that should be buffered before
+        the filter (default: 4). This specifies the maximum number of frames
+        the script can request in backward direction.
+
+        E.g. if ``buffered-frames=5``, and the script just requested frame 15,
+        it can still request frame 10, but frame 9 is not available anymore.
+        If it requests frame 30, mpv will decode 15 more frames, and keep only
+        frames 25-30.
+
+        The only reason why this buffer exists is to serve the random access
+        requests the VapourSynth filter can make.
+
+        The VapourSynth API has a ``getFrameAsync`` function, which takes an
+        absolute frame number. Source filters must respond to all requests. For
+        example, a source filter can request frame 2432, and then frame 3.
+        Source filters  typically implement this by pre-indexing the entire
+        file.
+
+        mpv on the other hand is stream oriented, and does not allow filters to
+        seek. (And it would not make sense to allow it, because it would ruin
+        performance.) Filters get frames sequentially in playback direction, and
+        cannot request them out of order.
+
+        To compensate for this mismatch, mpv allows the filter to access frames
+        within a certain window. ``buffered-frames`` controls the size of this
+        window. Most VapourSynth filters happen to work with this, because mpv
+        requests frames sequentially increasing from it, and most filters only
+        require frames "close" to the requested frame.
+
+        If the filter requests a frame that has a higher frame number than the
+        highest buffered frame, new frames will be decoded until the requested
+        frame number is reached. Excessive frames will be flushed out in a FIFO
+        manner (there are only at most ``buffered-frames`` in this buffer).
+
+        If the filter requests a frame that has a lower frame number than the
+        lowest buffered frame, the request cannot be satisfied, and an error
+        is returned to the filter. This kind of error is not supposed to happen
+        in a "proper" VapourSynth environment. What exactly happens depends on
+        the filters involved.
+
+        Increasing this buffer will not improve performance. Rather, it will
+        waste memory, and slow down seeks (when enough frames to fill the buffer
+        need to be decoded at once). It is only needed to prevent the error
+        described in the previous paragraph.
+
+        How many frames a filter requires depends on filter implementation
+        details, and mpv has no way of knowing. A scale filter might need only
+        1 frame, an interpolation filter may require a small number of frames,
+        and the ``Reverse`` filter will require an infinite number of frames.
+
+        If you want reliable operation to the full extend VapourSynth is
+        capable, use ``vspipe``.
+
+        The actual number of buffered frames also depends on the value of the
+        ``concurrent-frames`` option. Currently, both option values are
+        multiplied to get the final buffer size.
+
+    ``concurrent-frames``
+        Number of frames that should be requested in parallel. The
+        level of concurrency depends on the filter and how quickly mpv can
+        decode video to feed the filter. This value should probably be
+        proportional to the number of cores on your machine. Most time,
+        making it higher than the number of cores can actually make it
+        slower.
+
+        Technically, mpv will call the VapourSynth ``getFrameAsync`` function
+        in a loop, until there are ``concurrent-frames`` frames that have not
+        been returned by the filter yet. This also assumes that the rest of the
+        mpv filter chain reads the output of the ``vapoursynth`` filter quickly
+        enough. (For example, if you pause the player, filtering will stop very
+        soon, because the filtered frames are waiting in a queue.)
+
+        Actual concurrency depends on many other factors.
+
+        By default, this uses the special value ``auto``, which sets the option
+        to the number of detected logical CPU cores.
+
+    The following ``.vpy`` script variables are defined by mpv:
+
+    ``video_in``
+        The mpv video source as vapoursynth clip. Note that this has an
+        incorrect (very high) length set, which confuses many filters. This is
+        necessary, because the true number of frames is unknown. You can use the
+        ``Trim`` filter on the clip to reduce the length.
+
+    ``video_in_dw``, ``video_in_dh``
+        Display size of the video. Can be different from video size if the
+        video does not use square pixels (e.g. DVD).
+
+    ``container_fps``
+        FPS value as reported by file headers. This value can be wrong or
+        completely broken (e.g. 0 or NaN). Even if the value is correct,
+        if another filter changes the real FPS (by dropping or inserting
+        frames), the value of this variable will not be useful. Note that
+        the ``--container-fps-override`` command line option overrides this value.
+
+        Useful for some filters which insist on having a FPS.
+
+    ``display_fps``
+        Refresh rate of the current display. Note that this value can be 0.
+
+    ``display_res``
+        Resolution of the current display. This is an integer array with the
+        first entry corresponding to the width and the second entry coresponding
+        to the height. These values can be 0. Note that this will not respond to
+        monitor changes and may not work on all platforms.
+
+``vavpp``
+    VA-API video post processing. Requires the system to support VA-API,
+    i.e. Linux/BSD only. Works with ``--vo=vaapi`` and ``--vo=gpu`` only.
+    Currently deinterlaces. This filter is automatically inserted if
+    deinterlacing is requested (either using the ``d`` key, by default mapped to
+    the command ``cycle deinterlace``, or the ``--deinterlace`` option).
+
+    ``deint=<method>``
+        Select the deinterlacing algorithm.
+
+        no
+            Don't perform deinterlacing.
+        auto
+             Select the best quality deinterlacing algorithm (default). This
+             goes by the order of the options as documented, with
+             ``motion-compensated`` being considered best quality.
+        first-field
+            Show only first field.
+        bob
+            bob deinterlacing.
+        weave, motion-adaptive, motion-compensated
+            Advanced deinterlacing algorithms. Whether these actually work
+            depends on the GPU hardware, the GPU drivers, driver bugs, and
+            mpv bugs.
+
+    ``<interlaced-only>``
+        :no:  Deinterlace all frames (default).
+        :yes: Only deinterlace frames marked as interlaced.
+
+    ``reversal-bug=<yes|no>``
+        :no:  Use the API as it was interpreted by older Mesa drivers. While
+              this interpretation was more obvious and intuitive, it was
+              apparently wrong, and not shared by Intel driver developers.
+        :yes: Use Intel interpretation of surface forward and backwards
+              references (default). This is what Intel drivers and newer Mesa
+              drivers expect. Matters only for the advanced deinterlacing
+              algorithms.
+
+``vdpaupp``
+    VDPAU video post processing. Works with ``--vo=vdpau`` and ``--vo=gpu``
+    only. This filter is automatically inserted if deinterlacing is requested
+    (either using the ``d`` key, by default mapped to the command
+    ``cycle deinterlace``, or the ``--deinterlace`` option). When enabling
+    deinterlacing, it is always preferred over software deinterlacer filters
+    if the ``vdpau`` VO is used, and also if ``gpu`` is used and hardware
+    decoding was activated at least once (i.e. vdpau was loaded).
+
+    ``sharpen=<-1-1>``
+        For positive values, apply a sharpening algorithm to the video, for
+        negative values a blurring algorithm (default: 0).
+    ``denoise=<0-1>``
+        Apply a noise reduction algorithm to the video (default: 0; no noise
+        reduction).
+    ``deint=<yes|no>``
+        Whether deinterlacing is enabled (default: no). If enabled, it will use
+        the mode selected with ``deint-mode``.
+    ``deint-mode=<first-field|bob|temporal|temporal-spatial>``
+        Select deinterlacing mode (default: temporal).
+
+        Note that there's currently a mechanism that allows the ``vdpau`` VO to
+        change the ``deint-mode`` of auto-inserted ``vdpaupp`` filters. To avoid
+        confusion, it's recommended not to use the ``--vo=vdpau`` suboptions
+        related to filtering.
+
+        first-field
+            Show only first field.
+        bob
+            Bob deinterlacing.
+        temporal
+            Motion-adaptive temporal deinterlacing. May lead to A/V desync
+            with slow video hardware and/or high resolution.
+        temporal-spatial
+            Motion-adaptive temporal deinterlacing with edge-guided spatial
+            interpolation. Needs fast video hardware.
+    ``chroma-deint``
+        Makes temporal deinterlacers operate both on luma and chroma (default).
+        Use no-chroma-deint to solely use luma and speed up advanced
+        deinterlacing. Useful with slow video memory.
+    ``pullup``
+        Try to apply inverse telecine, needs motion adaptive temporal
+        deinterlacing.
+    ``interlaced-only=<yes|no>``
+        If ``yes``, only deinterlace frames marked as interlaced (default: no).
+    ``hqscaling=<0-9>``
+        0
+            Use default VDPAU scaling (default).
+        1-9
+            Apply high quality VDPAU scaling (needs capable hardware).
+
+``d3d11vpp``
+    Direct3D 11 video post processing. Currently requires D3D11 hardware
+    decoding for use.
+
+    ``deint=<yes|no>``
+        Whether deinterlacing is enabled (default: no).
+    ``interlaced-only=<yes|no>``
+        If ``yes``, only deinterlace frames marked as interlaced (default: no).
+    ``mode=<blend|bob|adaptive|mocomp|ivctc|none>``
+        Tries to select a video processor with the given processing capability.
+        If a video processor supports multiple capabilities, it is not clear
+        which algorithm is actually selected. ``none`` always falls back. On
+        most if not all hardware, this option will probably do nothing, because
+        a video processor usually supports all modes or none.
+
+``fingerprint=...``
+    Compute video frame fingerprints and provide them as metadata. Actually, it
+    currently barely deserved to be called ``fingerprint``, because it does not
+    compute "proper" fingerprints, only tiny downscaled images (but which can be
+    used to compute image hashes or for similarity matching).
+
+    The main purpose of this filter is to support the ``skip-logo.lua`` script.
+    If this script is dropped, or mpv ever gains a way to load user-defined
+    filters (other than VapourSynth), this filter will be removed. Due to the
+    "special" nature of this filter, it will be removed without warning.
+
+    The intended way to read from the filter is using ``vf-metadata`` (also
+    see ``clear-on-query`` filter parameter). The property will return a list
+    of key/value pairs as follows:
+
+    ::
+
+        fp0.pts = 1.2345
+        fp0.hex = 1234abcdef...bcde
+        fp1.pts = 1.4567
+        fp1.hex = abcdef1234...6789
+        ...
+        fpN.pts = ...
+        fpN.hex = ...
+        type = gray-hex-16x16
+
+    Each ``fp<N>`` entry is for a frame. The ``pts`` entry specifies the
+    timestamp of the frame (within the filter chain; in simple cases this is
+    the same as the display timestamp). The ``hex`` field is the hex encoded
+    fingerprint, whose size and meaning depend on the ``type`` filter option.
+    The ``type`` field has the same value as the option the filter was created
+    with.
+
+    This returns the frames that were filtered since the last query of the
+    property. If ``clear-on-query=no`` was set, a query doesn't reset the list
+    of frames. In both cases, a maximum of 10 frames is returned. If there are
+    more frames, the oldest frames are discarded. Frames are returned in filter
+    order.
+
+    (This doesn't return a structured list for the per-frame details because the
+    internals of the ``vf-metadata`` mechanism suck. The returned format may
+    change in the future.)
+
+    This filter uses zimg for speed and profit. However, it will fallback to
+    libswscale in a number of situations: lesser pixel formats, unaligned data
+    pointers or strides, or if zimg fails to initialize for unknown reasons. In
+    these cases, the filter will use more CPU. Also, it will output different
+    fingerprints, because libswscale cannot perform the full range expansion we
+    normally request from zimg. As a consequence, the filter may be slower and
+    not work correctly in random situations.
+
+    ``type=...``
+        What fingerprint to compute. Available types are:
+
+        :gray-hex-8x8:      grayscale, 8 bit, 8x8 size
+        :gray-hex-16x16:    grayscale, 8 bit, 16x16 size (default)
+
+        Both types simply remove all colors, downscale the image, concatenate
+        all pixel values to a byte array, and convert the array to a hex string.
+
+    ``clear-on-query=yes|no``
+        Clear the list of frame fingerprints if the ``vf-metadata`` property for
+        this filter is queried (default: yes). This requires some care by the
+        user. Some types of accesses might query the filter multiple times,
+        which leads to lost frames.
+
+    ``print=yes|no``
+        Print computed fingerprints to the terminal (default: no). This is
+        mostly for testing and such. Scripts should use ``vf-metadata`` to
+        read information from this filter instead.
+
+``gpu=...``
+    Convert video to RGB using the OpenGL renderer normally used with
+    ``--vo=gpu``. This requires that the EGL implementation supports off-screen
+    rendering on the default display. (This is the case with Mesa.)
+
+    Sub-options:
+
+    ``w=<pixels>``, ``h=<pixels>``
+        Size of the output in pixels (default: 0). If not positive, this will
+        use the size of the first filtered input frame.
+
+    .. warning::
+
+        This is highly experimental. Performance is bad, and it will not work
+        everywhere in the first place. Some features are not supported.
+
+    .. warning::
+
+        This does not do OSD rendering. If you see OSD, then it has been
+        rendered by the VO backend. (Subtitles are rendered by the ``gpu``
+        filter, if possible.)
+
+    .. warning::
+
+        If you use this with encoding mode, keep in mind that encoding mode will
+        convert the RGB filter's output back to yuv420p in software, using the
+        configured software scaler. Using ``zimg`` might improve this, but in
+        any case it might go against your goals when using this filter.
+
+    .. warning::
+
+        Do not use this with ``--vo=gpu``. It will apply filtering twice, since
+        most ``--vo=gpu`` options are unconditionally applied to the ``gpu``
+        filter. There is no mechanism in mpv to prevent this.
+
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
new file mode 100644
index 0000000..5ee4eaa
--- /dev/null
+++ b/DOCS/man/vo.rst
@@ -0,0 +1,710 @@
+VIDEO OUTPUT DRIVERS
+====================
+
+Video output drivers are interfaces to different video output facilities. The
+syntax is:
+
+``--vo=<driver1,driver2,...[,]>``
+    Specify a priority list of video output drivers to be used.
+
+If the list has a trailing ``,``, mpv will fall back on drivers not contained
+in the list.
+
+.. note::
+
+    See ``--vo=help`` for a list of compiled-in video output drivers.
+
+    The recommended output driver is ``--vo=gpu``, which is the default. All
+    other drivers are for compatibility or special purposes. If the default
+    does not work, it will fallback to other drivers (in the same order as
+    listed by ``--vo=help``).
+
+Available video output drivers are:
+
+``gpu``
+    General purpose, customizable, GPU-accelerated video output driver. It
+    supports extended scaling methods, dithering, color management, custom
+    shaders, HDR, and more.
+
+    See `GPU renderer options`_ for options specific to this VO.
+
+    By default, mpv utilizes settings that balance quality and performance.
+    Additionally, two predefined profiles are available: ``fast`` for maximum
+    performance and ``high-quality`` for superior rendering quality. You can
+    apply a specific profile using the ``--profile=<name>`` option and inspect
+    its contents using ``--show-profile=<name>``.
+
+    This VO abstracts over several possible graphics APIs and windowing
+    contexts, which can be influenced using the ``--gpu-api`` and
+    ``--gpu-context`` options.
+
+    Hardware decoding over OpenGL-interop is supported to some degree. Note
+    that in this mode, some corner case might not be gracefully handled, and
+    color space conversion and chroma upsampling is generally in the hand of
+    the hardware decoder APIs.
+
+    ``gpu`` makes use of FBOs by default. Sometimes you can achieve better
+    quality or performance by changing the ``--fbo-format`` option to
+    ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not
+    accepting ``rgb16``, Mesa sometimes not being compiled with float texture
+    support, and some macOS setups being very slow with ``rgb16`` but fast
+    with ``rgb32f``. If you have problems, you can also try enabling the
+    ``--gpu-dumb-mode=yes`` option.
+
+``gpu-next``
+    Experimental video renderer based on ``libplacebo``. This supports almost
+    the same set of features as ``--vo=gpu``. See `GPU renderer options`_ for a
+    list.
+
+    Should generally be faster and higher quality, but some features may still
+    be missing or misbehave. Expect (and report!) bugs. See here for a list of
+    known differences and bugs:
+
+    https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
+
+``xv`` (X11 only)
+    Uses the XVideo extension to enable hardware-accelerated display. This is
+    the most compatible VO on X, but may be low-quality, and has issues with
+    OSD and subtitle display.
+
+    .. note:: This driver is for compatibility with old systems.
+
+    The following global options are supported by this video output:
+
+    ``--xv-adaptor=<number>``
+        Select a specific XVideo adapter (check xvinfo results).
+    ``--xv-port=<number>``
+        Select a specific XVideo port.
+    ``--xv-ck=<cur|use|set>``
+        Select the source from which the color key is taken (default: cur).
+
+        cur
+          The default takes the color key currently set in Xv.
+        use
+          Use but do not set the color key from mpv (use the ``--colorkey``
+          option to change it).
+        set
+          Same as use but also sets the supplied color key.
+
+    ``--xv-ck-method=<none|man|bg|auto>``
+        Sets the color key drawing method (default: man).
+
+        none
+          Disables color-keying.
+        man
+          Draw the color key manually (reduces flicker in some cases).
+        bg
+          Set the color key as window background.
+        auto
+          Let Xv draw the color key.
+
+    ``--xv-colorkey=<number>``
+        Changes the color key to an RGB value of your choice. ``0x000000`` is
+        black and ``0xffffff`` is white.
+
+    ``--xv-buffers=<number>``
+        Number of image buffers to use for the internal ringbuffer (default: 2).
+        Increasing this will use more memory, but might help with the X server
+        not responding quickly enough if video FPS is close to or higher than
+        the display refresh rate.
+
+``x11`` (X11 only)
+    Shared memory video output driver without hardware acceleration that works
+    whenever X11 is present.
+
+    Since mpv 0.30.0, you may need to use ``--profile=sw-fast`` to get decent
+    performance.
+
+    .. note:: This is a fallback only, and should not be normally used.
+
+``vdpau`` (X11 only)
+    Uses the VDPAU interface to display and optionally also decode video.
+    Hardware decoding is used with ``--hwdec=vdpau``. Note that there is
+    absolutely no reason to use this, other than compatibility. We strongly
+    recommend that you use ``--vo=gpu`` with ``--hwdec=nvdec`` instead.
+
+    .. note::
+
+        Earlier versions of mpv (and MPlayer, mplayer2) provided sub-options
+        to tune vdpau post-processing, like ``deint``, ``sharpen``, ``denoise``,
+        ``chroma-deint``, ``pullup``, ``hqscaling``. These sub-options are
+        deprecated, and you should use the ``vdpaupp`` video filter instead.
+
+    The following global options are supported by this video output:
+
+    ``--vo-vdpau-sharpen=<-1-1>``
+        (Deprecated. See note about ``vdpaupp``.)
+
+        For positive values, apply a sharpening algorithm to the video, for
+        negative values a blurring algorithm (default: 0).
+    ``--vo-vdpau-denoise=<0-1>``
+        (Deprecated. See note about ``vdpaupp``.)
+
+        Apply a noise reduction algorithm to the video (default: 0; no noise
+        reduction).
+    ``--vo-vdpau-chroma-deint``
+        (Deprecated. See note about ``vdpaupp``.)
+
+        Makes temporal deinterlacers operate both on luma and chroma (default).
+        Use no-chroma-deint to solely use luma and speed up advanced
+        deinterlacing. Useful with slow video memory.
+    ``--vo-vdpau-pullup``
+        (Deprecated. See note about ``vdpaupp``.)
+
+        Try to apply inverse telecine, needs motion adaptive temporal
+        deinterlacing.
+    ``--vo-vdpau-hqscaling=<0-9>``
+        (Deprecated. See note about ``vdpaupp``.)
+
+        0
+            Use default VDPAU scaling (default).
+        1-9
+            Apply high quality VDPAU scaling (needs capable hardware).
+    ``--vo-vdpau-fps=<number>``
+        Override autodetected display refresh rate value (the value is needed
+        for framedrop to allow video playback rates higher than display
+        refresh rate, and for vsync-aware frame timing adjustments). Default 0
+        means use autodetected value. A positive value is interpreted as a
+        refresh rate in Hz and overrides the autodetected value. A negative
+        value disables all timing adjustment and framedrop logic.
+    ``--vo-vdpau-composite-detect``
+        NVIDIA's current VDPAU implementation behaves somewhat differently
+        under a compositing window manager and does not give accurate frame
+        timing information. With this option enabled, the player tries to
+        detect whether a compositing window manager is active. If one is
+        detected, the player disables timing adjustments as if the user had
+        specified ``fps=-1`` (as they would be based on incorrect input). This
+        means timing is somewhat less accurate than without compositing, but
+        with the composited mode behavior of the NVIDIA driver, there is no
+        hard playback speed limit even without the disabled logic. Enabled by
+        default, use ``--vo-vdpau-composite-detect=no`` to disable.
+    ``--vo-vdpau-queuetime-windowed=<number>`` and ``queuetime-fs=<number>``
+        Use VDPAU's presentation queue functionality to queue future video
+        frame changes at most this many milliseconds in advance (default: 50).
+        See below for additional information.
+    ``--vo-vdpau-output-surfaces=<2-15>``
+        Allocate this many output surfaces to display video frames (default:
+        3). See below for additional information.
+    ``--vo-vdpau-colorkey=<#RRGGBB|#AARRGGBB>``
+        Set the VDPAU presentation queue background color, which in practice
+        is the colorkey used if VDPAU operates in overlay mode (default:
+        ``#020507``, some shade of black). If the alpha component of this value
+        is 0, the default VDPAU colorkey will be used instead (which is usually
+        green).
+    ``--vo-vdpau-force-yuv``
+        Never accept RGBA input. This means mpv will insert a filter to convert
+        to a YUV format before the VO. Sometimes useful to force availability
+        of certain YUV-only features, like video equalizer or deinterlacing.
+
+    Using the VDPAU frame queuing functionality controlled by the queuetime
+    options makes mpv's frame flip timing less sensitive to system CPU load and
+    allows mpv to start decoding the next frame(s) slightly earlier, which can
+    reduce jitter caused by individual slow-to-decode frames. However, the
+    NVIDIA graphics drivers can make other window behavior such as window moves
+    choppy if VDPAU is using the blit queue (mainly happens if you have the
+    composite extension enabled) and this feature is active. If this happens on
+    your system and it bothers you then you can set the queuetime value to 0 to
+    disable this feature. The settings to use in windowed and fullscreen mode
+    are separate because there should be no reason to disable this for
+    fullscreen mode (as the driver issue should not affect the video itself).
+
+    You can queue more frames ahead by increasing the queuetime values and the
+    ``output_surfaces`` count (to ensure enough surfaces to buffer video for a
+    certain time ahead you need at least as many surfaces as the video has
+    frames during that time, plus two). This could help make video smoother in
+    some cases. The main downsides are increased video RAM requirements for
+    the surfaces and laggier display response to user commands (display
+    changes only become visible some time after they're queued). The graphics
+    driver implementation may also have limits on the length of maximum
+    queuing time or number of queued surfaces that work well or at all.
+
+``direct3d`` (Windows only)
+    Video output driver that uses the Direct3D interface.
+
+    .. note:: This driver is for compatibility with systems that don't provide
+              proper OpenGL drivers, and where ANGLE does not perform well.
+
+    The following global options are supported by this video output:
+
+    ``--vo-direct3d-disable-texture-align``
+        Normally texture sizes are always aligned to 16. With this option
+        enabled, the video texture will always have exactly the same size as
+        the video itself.
+
+
+    Debug options. These might be incorrect, might be removed in the future,
+    might crash, might cause slow downs, etc. Contact the developers if you
+    actually need any of these for performance or proper operation.
+
+    ``--vo-direct3d-force-power-of-2``
+        Always force textures to power of 2, even if the device reports
+        non-power-of-2 texture sizes as supported.
+
+    ``--vo-direct3d-texture-memory=<mode>``
+        Only affects operation with shaders/texturing enabled, and (E)OSD.
+        Possible values:
+
+        ``default`` (default)
+            Use ``D3DPOOL_DEFAULT``, with a ``D3DPOOL_SYSTEMMEM`` texture for
+            locking. If the driver supports ``D3DDEVCAPS_TEXTURESYSTEMMEMORY``,
+            ``D3DPOOL_SYSTEMMEM`` is used directly.
+
+        ``default-pool``
+            Use ``D3DPOOL_DEFAULT``. (Like ``default``, but never use a
+            shadow-texture.)
+
+        ``default-pool-shadow``
+            Use ``D3DPOOL_DEFAULT``, with a ``D3DPOOL_SYSTEMMEM`` texture for
+            locking. (Like ``default``, but always force the shadow-texture.)
+
+        ``managed``
+            Use ``D3DPOOL_MANAGED``.
+
+        ``scratch``
+            Use ``D3DPOOL_SCRATCH``, with a ``D3DPOOL_SYSTEMMEM`` texture for
+            locking.
+
+    ``--vo-direct3d-swap-discard``
+        Use ``D3DSWAPEFFECT_DISCARD``, which might be faster.
+        Might be slower too, as it must(?) clear every frame.
+
+    ``--vo-direct3d-exact-backbuffer``
+        Always resize the backbuffer to window size.
+
+``sdl``
+    SDL 2.0+ Render video output driver, depending on system with or without
+    hardware acceleration. Should work on all platforms supported by SDL 2.0.
+    For tuning, refer to your copy of the file ``SDL_hints.h``.
+
+    .. note:: This driver is for compatibility with systems that don't provide
+              proper graphics drivers.
+
+    The following global options are supported by this video output:
+
+    ``--sdl-sw``
+        Continue even if a software renderer is detected.
+
+    ``--sdl-switch-mode``
+        Instruct SDL to switch the monitor video mode when going fullscreen.
+
+``dmabuf-wayland``
+    Experimental Wayland output driver designed for use with either drm stateless
+    or VA API hardware decoding. The driver is designed to avoid any GPU to CPU copies,
+    and to perform scaling and color space conversion using fixed-function hardware,
+    if available, rather than GPU shaders. This frees up GPU resources for other tasks.
+    It is highly recommended to use this VO with the appropriate ``--hwdec`` option such
+    as ``auto-safe``. It can still work in some circumstances without ``--hwdec`` due to
+    mpv's internal conversion filters, but this is not recommended as it's a needless
+    extra step. Correct output depends on support from your GPU, drivers, and compositor.
+    Weston and wlroots-based compositors like Sway and Intel GPUs are known to generally
+    work.
+
+``vaapi``
+    Intel VA API video output driver with support for hardware decoding. Note
+    that there is absolutely no reason to use this, other than compatibility.
+    This is low quality, and has issues with OSD. We strongly recommend that
+    you use ``--vo=gpu`` with ``--hwdec=vaapi`` instead.
+
+    The following global options are supported by this video output:
+
+    ``--vo-vaapi-scaling=<algorithm>``
+        default
+            Driver default (mpv default as well).
+        fast
+            Fast, but low quality.
+        hq
+            Unspecified driver dependent high-quality scaling, slow.
+        nla
+            ``non-linear anamorphic scaling``
+
+    ``--vo-vaapi-scaled-osd=<yes|no>``
+        If enabled, then the OSD is rendered at video resolution and scaled to
+        display resolution. By default, this is disabled, and the OSD is
+        rendered at display resolution if the driver supports it.
+
+``null``
+    Produces no video output. Useful for benchmarking.
+
+    Usually, it's better to disable video with ``--no-video`` instead.
+
+    The following global options are supported by this video output:
+
+    ``--vo-null-fps=<value>``
+        Simulate display FPS. This artificially limits how many frames the
+        VO accepts per second.
+
+``caca``
+    Color ASCII art video output driver that works on a text console.
+
+    .. note:: This driver is a joke.
+
+``tct``
+    Color Unicode art video output driver that works on a text console.
+    By default depends on support of true color by modern terminals to display
+    the images at full color range, but 256-colors output is also supported (see
+    below). On Windows it requires an ansi terminal such as mintty.
+
+    Since mpv 0.30.0, you may need to use ``--profile=sw-fast`` to get decent
+    performance.
+
+    Note: the TCT image output is not synchronized with other terminal output
+    from mpv, which can lead to broken images. The options ``--no-terminal`` or
+    ``--really-quiet`` can help with that.
+
+    ``--vo-tct-algo=<algo>``
+        Select how to write the pixels to the terminal.
+
+        half-blocks
+            Uses unicode LOWER HALF BLOCK character to achieve higher vertical
+            resolution. (Default.)
+        plain
+            Uses spaces. Causes vertical resolution to drop twofolds, but in
+            theory works in more places.
+
+    ``--vo-tct-width=<width>``  ``--vo-tct-height=<height>``
+        Assume the terminal has the specified character width and/or height.
+        These default to 80x25 if the terminal size cannot be determined.
+
+    ``--vo-tct-256=<yes|no>`` (default: no)
+        Use 256 colors - for terminals which don't support true color.
+
+``kitty``
+    Graphical output for the terminal, using the kitty graphics protocol.
+    Tested with kitty and Konsole.
+
+    You may need to use ``--profile=sw-fast`` to get decent performance.
+
+    Kitty size and alignment options:
+
+    ``--vo-kitty-cols=<columns>``, ``--vo-kitty-rows=<rows>`` (default: 0)
+        Specify the terminal size in character cells, otherwise (0) read it
+        from the terminal, or fall back to 80x25.
+
+    ``--vo-kitty-width=<width>``, ``--vo-kitty-height=<height>`` (default: 0)
+        Specify the available size in pixels, otherwise (0) read it from the
+        terminal, or fall back to 320x240.
+
+    ``--vo-kitty-left=<col>``, ``--vo-kitty-top=<row>`` (default: 0)
+        Specify the position in character cells where the image starts (1 is
+        the first column or row). If 0 (default) then try to automatically
+        determine it according to the other values and the image aspect ratio
+        and zoom.
+
+    ``--vo-kitty-config-clear=<yes|no>`` (default: yes)
+        Whether or not to clear the terminal whenever the output is
+        reconfigured (e.g. when video size changes).
+
+    ``--vo-kitty-alt-screen=<yes|no>`` (default: yes)
+        Whether or not to use the alternate screen buffer and return the
+        terminal to its previous state on exit. When set to no, the last
+        kitty image stays on screen after quit, with the cursor following it.
+
+    ``--vo-kitty-use-shm=<yes|no>`` (default: no)
+        Use shared memory objects to transfer image data to the terminal.
+        This is much faster than sending the data as escape codes, but is not
+        supported by as many terminals. It also only works on the local machine
+        and not via e.g. SSH connections.
+
+        This option is not implemented on Windows.
+
+``sixel``
+    Graphical output for the terminal, using sixels. Tested with ``mlterm`` and
+    ``xterm``.
+
+    Note: the Sixel image output is not synchronized with other terminal
+    output from mpv, which can lead to broken images.
+    The option ``--really-quiet`` can help with that, and is recommended.
+    On some platforms, using the ``--vo-sixel-buffered`` option may work as
+    well.
+
+    You may need to use ``--profile=sw-fast`` to get decent performance.
+
+    Note: at the time of writing, ``xterm`` does not enable sixel by default -
+    launching it as ``xterm -ti 340`` is one way to enable it. Also, ``xterm``
+    does not display images bigger than 1000x1000 pixels by default.
+
+    To render and align sixel images correctly, mpv needs to know the terminal
+    size both in cells and in pixels. By default it tries to use values which
+    the terminal reports, however, due to differences between terminals this is
+    an error-prone process which cannot be automated with certainty - some
+    terminals report the size in pixels including the padding - e.g. ``xterm``,
+    while others report the actual usable number of pixels - like ``mlterm``.
+    Additionally, they may behave differently when maximized or in fullscreen,
+    and mpv cannot detect this state using standard methods.
+
+    Sixel size and alignment options:
+
+    ``--vo-sixel-cols=<columns>``, ``--vo-sixel-rows=<rows>`` (default: 0)
+        Specify the terminal size in character cells, otherwise (0) read it
+        from the terminal, or fall back to 80x25. Note that mpv doesn't use the
+        the last row with sixel because this seems to result in scrolling.
+
+    ``--vo-sixel-width=<width>``, ``--vo-sixel-height=<height>`` (default: 0)
+        Specify the available size in pixels, otherwise (0) read it from the
+        terminal, or fall back to 320x240. Other than excluding the last line,
+        the height is also further rounded down to a multiple of 6 (sixel unit
+        height) to avoid overflowing below the designated size.
+
+    ``--vo-sixel-left=<col>``, ``--vo-sixel-top=<row>`` (default: 0)
+        Specify the position in character cells where the image starts (1 is
+        the first column or row). If 0 (default) then try to automatically
+        determine it according to the other values and the image aspect ratio
+        and zoom.
+
+    ``--vo-sixel-pad-x=<pad_x>``, ``--vo-sixel-pad-y=<pad_y>`` (default: -1)
+        Used only when mpv reads the size in pixels from the terminal.
+        Specify the number of padding pixels (on one side) which are included
+        at the size which the terminal reports. If -1 (default) then the number
+        of pixels is rounded down to a multiple of number of cells (per axis),
+        to take into account padding at the report - this only works correctly
+        when the overall padding per axis is smaller than the number of cells.
+
+    ``--vo-sixel-config-clear=<yes|no>`` (default: yes)
+        Whether or not to clear the terminal whenever the output is
+        reconfigured (e.g. when video size changes).
+
+    ``--vo-sixel-alt-screen=<yes|no>`` (default: yes)
+        Whether or not to use the alternate screen buffer and return the
+        terminal to its previous state on exit. When set to no, the last
+        sixel image stays on screen after quit, with the cursor following it.
+
+        ``--vo-sixel-exit-clear`` is a deprecated alias for this option and
+        may be removed in the future.
+
+    ``--vo-sixel-buffered=<yes|no>`` (default: no)
+        Buffers the full output sequence before writing it to the terminal.
+        On POSIX platforms, this can help prevent interruption (including from
+        other applications) and thus broken images, but may come at a
+        performance cost with some terminals and is subject to implementation
+        details.
+
+    Sixel image quality options:
+
+    ``--vo-sixel-dither=<algo>``
+        Selects the dither algorithm which libsixel should apply.
+        Can be one of the below list as per libsixel's documentation.
+
+        auto (Default)
+            Let libsixel choose the dithering method.
+        none
+            Don't diffuse
+        atkinson
+            Diffuse with Bill Atkinson's method.
+        fs
+            Diffuse with Floyd-Steinberg method
+        jajuni
+            Diffuse with Jarvis, Judice & Ninke method
+        stucki
+            Diffuse with Stucki's method
+        burkes
+            Diffuse with Burkes' method
+        arithmetic
+            Positionally stable arithmetic dither
+        xor
+            Positionally stable arithmetic xor based dither
+
+    ``--vo-sixel-fixedpalette=<yes|no>`` (default: yes)
+        Use libsixel's built-in static palette using the XTERM256 profile
+        for dither. Fixed palette uses 256 colors for dithering. Note that
+        using ``no`` (at the time of writing) will slow down ``xterm``.
+
+    ``--vo-sixel-reqcolors=<colors>`` (default: 256)
+        Has no effect with fixed palette. Set up libsixel to use required
+        number of colors for dynamic palette. This value depends on the
+        terminal emulator as well. Xterm supports 256 colors. Can set this to
+        a lower value for faster performance.
+
+    ``--vo-sixel-threshold=<threshold>`` (default: -1)
+        Has no effect with fixed palette. Defines the threshold to change the
+        palette - as percentage of the number of colors, e.g. 20 will change
+        the palette when the number of colors changed by 20%. It's a simple
+        measure to reduce the number of palette changes, because it can be slow
+        in some terminals (``xterm``). The default (-1) will choose a palette
+        on every frame and will have better quality.
+
+``image``
+    Output each frame into an image file in the current directory. Each file
+    takes the frame number padded with leading zeros as name.
+
+    The following global options are supported by this video output:
+
+    ``--vo-image-format=<format>``
+        Select the image file format.
+
+        jpg
+            JPEG files, extension .jpg. (Default.)
+        jpeg
+            JPEG files, extension .jpeg.
+        png
+            PNG files.
+        webp
+            WebP files.
+
+    ``--vo-image-png-compression=<0-9>``
+        PNG compression factor (speed vs. file size tradeoff) (default: 7)
+    ``--vo-image-png-filter=<0-5>``
+        Filter applied prior to PNG compression (0 = none; 1 = sub; 2 = up;
+        3 = average; 4 = Paeth; 5 = mixed) (default: 5)
+    ``--vo-image-jpeg-quality=<0-100>``
+        JPEG quality factor (default: 90)
+    ``--vo-image-jpeg-optimize=<0-100>``
+        JPEG optimization factor (default: 100)
+    ``--vo-image-webp-lossless=<yes|no>``
+        Enable writing lossless WebP files (default: no)
+    ``--vo-image-webp-quality=<0-100>``
+        WebP quality (default: 75)
+    ``--vo-image-webp-compression=<0-6>``
+        WebP compression factor (default: 4)
+    ``--vo-image-outdir=<dirname>``
+        Specify the directory to save the image files to (default: ``./``).
+
+``libmpv``
+    For use with libmpv direct embedding. As a special case, on macOS it
+    is used like a normal VO within mpv (cocoa-cb). Otherwise useless in any
+    other contexts.
+    (See ``<mpv/render.h>``.)
+
+    This also supports many of the options the ``gpu`` VO has, depending on the
+    backend.
+
+``rpi`` (Raspberry Pi)
+    Native video output on the Raspberry Pi using the MMAL API.
+
+    The following global options are supported by this video output:
+
+    ``--rpi-display=<number>``
+        Select the display number on which the video overlay should be shown
+        (default: 0).
+
+    ``--rpi-layer=<number>``
+        Select the dispmanx layer on which the video overlay should be shown
+        (default: -10). Note that mpv will also use the 2 layers above the
+        selected layer, to handle the window background and OSD. Actual video
+        rendering will happen on the layer above the selected layer.
+
+    ``--rpi-background=<yes|no>``
+        Whether to render a black background behind the video (default: no).
+        Normally it's better to kill the console framebuffer instead, which
+        gives better performance.
+
+    ``--rpi-osd=<yes|no>``
+        Enabled by default. If disabled with ``no``, no OSD layer is created.
+        This also means there will be no subtitles rendered.
+
+``drm`` (Direct Rendering Manager)
+    Video output driver using Kernel Mode Setting / Direct Rendering Manager.
+    Should be used when one doesn't want to install full-blown graphical
+    environment (e.g. no X). Does not support hardware acceleration (if you
+    need this, check the ``drm`` backend for ``gpu`` VO).
+
+    Since mpv 0.30.0, you may need to use ``--profile=sw-fast`` to get decent
+    performance.
+
+    The following global options are supported by this video output:
+
+    ``--drm-connector=<name>``
+        Select the connector to use (usually this is a monitor.) If ``<name>``
+        is empty or ``auto``, mpv renders the output on the first available
+        connector. Use ``--drm-connector=help`` to get a list of available
+        connectors. (default: empty)
+
+    ``--drm-device=<path>``
+        Select the DRM device file to use. If specified this overrides automatic
+        card selection. (default: empty)
+
+    ``--drm-mode=<preferred|highest|N|WxH[@R]>``
+        Mode to use (resolution and frame rate).
+        Possible values:
+
+        :preferred: Use the preferred mode for the screen on the selected
+                    connector. (default)
+        :highest:   Use the mode with the highest resolution available on the
+                    selected connector.
+        :N:         Select mode by index.
+        :WxH[@R]:   Specify mode by width, height, and optionally refresh rate.
+                    In case several modes match, selects the mode that comes
+                    first in the EDID list of modes.
+
+        Use ``--drm-mode=help`` to get a list of available modes for all active
+        connectors.
+
+    ``--drm-draw-plane=<primary|overlay|N>``
+        Select the DRM plane to which video and OSD is drawn to, under normal
+        circumstances. The plane can be specified as ``primary``, which will
+        pick the first applicable primary plane; ``overlay``, which will pick
+        the first applicable overlay plane; or by index. The index is zero
+        based, and related to the CRTC.
+        (default: primary)
+
+        When using this option with the drmprime-overlay hwdec interop, only the
+        OSD is rendered to this plane.
+
+    ``--drm-drmprime-video-plane=<primary|overlay|N>``
+        Select the DRM plane to use for video with the drmprime-overlay hwdec
+        interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s
+        on various other SoC:s). The plane is unused otherwise. This option
+        accepts the same values as ``--drm-draw-plane``. (default: overlay)
+
+        To be able to successfully play 4K video on various SoCs you might need
+        to set ``--drm-draw-plane=overlay --drm-drmprime-video-plane=primary``
+        and setting ``--drm-draw-surface-size=1920x1080``, to render the OSD at a
+        lower resolution (the video when handled by the hwdec will be on the
+        drmprime-video plane and at full 4K resolution)
+
+    ``--drm-format=<xrgb8888|xrgb2101010>``
+        Select the DRM format to use (default: xrgb8888). This allows you to
+        choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per
+        pixel/8 bits per channel packed RGB format with 8 bits of padding.
+        xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB
+        format with 2 bits of padding.
+
+        There are cases when xrgb2101010 will work with the ``drm`` VO, but not
+        with the ``drm`` backend for the ``gpu`` VO. This is because with the
+        ``gpu`` VO, in addition to requiring support in your DRM driver,
+        requires support for xrgb2101010 in your EGL driver
+
+    ``--drm-draw-surface-size=<[WxH]>``
+        Sets the size of the surface used on the draw plane. The surface will
+        then be upscaled to the current screen resolution. This option can be
+        useful when used together with the drmprime-overlay hwdec interop at
+        high resolutions, as it allows scaling the draw plane (which in this
+        case only handles the OSD) down to a size the GPU can handle.
+
+        When used without the drmprime-overlay hwdec interop this option will
+        just cause the video to get rendered at a different resolution and then
+        scaled to screen size.
+
+        (default: display resolution)
+
+    ``--drm-vrr-enabled=<no|yes|auto>``
+        Toggle use of Variable Refresh Rate (VRR), aka Freesync or Adaptive Sync
+        on compatible systems. VRR allows for the display to be refreshed at any
+        rate within a range (usually ~40Hz-60Hz for 60Hz displays). This can help
+        with playback of 24/25/50fps content. Support depends on the use of a
+        compatible monitor, GPU, and a sufficiently new kernel with drivers
+        that support the feature.
+
+        :no:    Do not attempt to enable VRR. (default)
+        :yes:   Attempt to enable VRR, whether the capability is reported or not.
+        :auto:  Attempt to enable VRR if support is reported.
+
+``mediacodec_embed`` (Android)
+    Renders ``IMGFMT_MEDIACODEC`` frames directly to an ``android.view.Surface``.
+    Requires ``--hwdec=mediacodec`` for hardware decoding, along with
+    ``--vo=mediacodec_embed`` and ``--wid=(intptr_t)(*android.view.Surface)``.
+
+    Since this video output driver uses native decoding and rendering routines,
+    many of mpv's features (subtitle rendering, OSD/OSC, video filters, etc)
+    are not available with this driver.
+
+    To use hardware decoding with ``--vo=gpu`` instead, use ``--hwdec=mediacodec``
+    or ``mediacodec-copy`` along with ``--gpu-context=android``.
+
+``wlshm`` (Wayland only)
+    Shared memory video output driver without hardware acceleration that works
+    whenever Wayland is present.
+
+    Since mpv 0.30.0, you may need to use ``--profile=sw-fast`` to get decent
+    performance.
+
+    .. note:: This is a fallback only, and should not be normally used.
diff --git a/DOCS/mplayer-changes.rst b/DOCS/mplayer-changes.rst
new file mode 100644
index 0000000..6ecb1d0
--- /dev/null
+++ b/DOCS/mplayer-changes.rst
@@ -0,0 +1,455 @@
+CHANGES FROM OTHER VERSIONS OF MPLAYER
+======================================
+
+**mpv** is based on mplayer2, which in turn is based on the original MPlayer
+(also called mplayer, mplayer-svn, mplayer1). Many changes have been made, a
+large part of which is incompatible or completely changes how the player
+behaves. Although there are still many similarities to its ancestors, **mpv**
+should generally be treated as a completely different program.
+
+.. admonition:: Warning
+
+    This document is **not updated** anymore, and is **incomplete** and
+    **outdated**. If you look for old option replacements, always check with
+    the current mpv manpage, as the options could have changed meanwhile.
+
+General Changes from MPlayer to mpv
+-----------------------------------
+
+This listing is about changes introduced by mplayer2 and mpv relatively to
+MPlayer.
+
+Player
+~~~~~~
+
+* New name for the binary (``mpv``). New location for config files (either
+  ``~/.config/mpv/mpv.conf``, or if you want, ``~/.mpv/config``).
+* Encoding functionality (replacement for MEncoder, see the `ENCODING`_ section).
+* Support for Lua scripting (see the `LUA SCRIPTING`_ section).
+* Better pause handling (e.g. do not unpause on a command).
+* Precise seeking support.
+* Improvements in audio/video sync handling.
+* Do not lose settings when playing a new file in the same player instance.
+* Slave mode compatibility broken (see below).
+* Re-enable screensaver while the player is paused.
+* Allow resuming playback at a later point with ``Shift+q``, also see the
+  ``quit-watch-later`` input command.
+* ``--keep-open`` option to stop the player from closing the window and
+  exiting after playback ends.
+* A client API, that allows embedding **mpv** into applications
+  (see ``libmpv/client.h`` in the sources).
+
+Input
+~~~~~
+
+* Improved default keybindings. MPlayer bindings are also available (see
+  ``etc/mplayer-input.conf`` in the source tree).
+* Improved responsiveness on user input.
+* Support for modifier keys (alt, shift, ctrl) in input.conf.
+* Allow customizing whether a key binding for seeking shows the video time, the
+  OSD bar, or nothing (see the `Input Command Prefixes`_ section).
+* Support mapping multiple commands to one key.
+* Classic LIRC support was removed. Install remotes as input devices instead.
+  This way they will send X11 key events to the mpv window, which can be bound
+  using the normal ``input.conf``.
+  Also see: https://github.com/mpv-player/mpv/wiki/IR-remotes
+* Joystick support was removed. It was considered useless and was the cause
+  of some problems (e.g. a laptop's accelerator being recognized as joystick).
+* Support for relative seeking by percentage.
+
+Audio
+~~~~~
+
+* Support for gapless audio (see the ``--gapless-audio`` option).
+* Support for OSS4 volume control.
+* Improved support for PulseAudio.
+* Make ``--softvol`` default (**mpv** is not a mixer control panel).
+* By default, do pitch correction if playback speed is increased.
+* Improved downmixing and output of surround audio:
+
+  - Instead of using hardcoded pan filters to do remixing, libavresample is used
+  - Channel maps are used to identify the channel layout, so e.g. ``3.0`` and
+    ``2.1`` audio can be distinguished.
+
+Video
+~~~~~
+
+* Wayland support.
+* Native support for VAAPI and VDA. Improved VDPAU video output.
+* Improved GPU-accelerated video output (see the ``gpu-hq`` preset).
+* Make hardware decoding work with the ``gpu`` video output.
+* Support for libavfilter (for video->video and audio->audio). This allows
+  using most of FFmpeg's filters, which improve greatly on the old MPlayer
+  filters in features, performance, and correctness.
+* More correct color reproduction (color matrix generation), including support
+  for BT.2020 (Ultra HD). linear XYZ (Digital Cinema) and SMPTE ST2084 (HDR)
+  inputs.
+* Support for color managed displays, via ICC profiles.
+* High-quality image resamplers (see the ``--scale`` suboption).
+* Support for scaling in (sigmoidized) linear light.
+* Better subtitle rendering using libass by default.
+* Improvements when playing multiple files (``-fixed-vo`` is default, do not
+  reset settings by default when playing a new file).
+* Replace image video outputs (``--vo=jpeg`` etc.) with ``--vo=image``.
+* Removal of ``--vo=gif89a``, ``--vo=md5sum``, ``--vo=yuv4mpeg``, as encoding
+  can handle these use cases. For yuv4mpeg, for example, use::
+
+    mpv input.mkv -o output.y4m --no-audio --oautofps --oneverdrop
+
+* Image subtitles (DVDs etc.) are rendered in color and use more correct
+  positioning (color for image subs can be disabled with ``--sub-gray``).
+* Support for the X11 video output is removed, since it was considered
+  deprecated. SDL video output can still be used as a fallback.
+
+OSD and terminal
+~~~~~~~~~~~~~~~~
+
+* Cleaned up terminal output: nicer status line, less useless noise.
+* Improved OSD rendering using libass, with full Unicode support.
+* New OSD bar with chapter marks. Not positioned in the middle of the video
+  (this can be customized with the ``--osd-bar-align-y`` option).
+* Display list of chapters and audio/subtitle tracks on OSD (see the
+  `Properties`_ section).
+
+Screenshots
+~~~~~~~~~~~
+
+* Instant screenshots without 1-frame delay.
+* Support for taking screenshots even with hardware decoding.
+* Support for saving screenshots as JPEG or PNG.
+* Support for configurable file names.
+* Support for taking screenshots with or without subtitles.
+
+Note that the ``screenshot`` video filter is not needed anymore, and should not
+be put into the mpv config file.
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+* Better MKV support (e.g. ordered chapters, 3D metadata).
+* Matroska edition switching at runtime.
+* Support for playing URLs of popular streaming sites directly.
+  (e.g. ``mpv https://www.youtube.com/watch?v=...``).
+  Requires a recent version of ``youtube-dl`` to be installed. Can be
+  disabled with ``ytdl=no`` in the mpv config file.
+* Support for precise scrolling which scales the parameter of commands. If the
+  input doesn't support precise scrolling the scale factor stays 1.
+* Allow changing/adjusting video filters at runtime. (This is also used to make
+  the ``D`` key insert vf_yadif if deinterlacing is not supported otherwise).
+* Improved support for .cue files.
+
+Mac OS X
+~~~~~~~~
+
+* Native OpenGL backend.
+* Cocoa event loop is independent from MPlayer's event loop, so user
+  actions like accessing menus and live resizing do not block the playback.
+* Media Keys support.
+* VDA support using libavcodec hwaccel API instead of FFmpeg's decoder with up
+  to 2-2.5x reduction in CPU usage.
+
+Windows
+~~~~~~~
+
+* Improved support for Unicode file names.
+* Improved window handling.
+* Do not block playback when moving the window.
+* Improved Direct3D video output.
+* Added WASAPI audio output.
+
+Internal changes
+~~~~~~~~~~~~~~~~
+
+* Switch to GPLv2+ (see ``Copyright`` file for details).
+* Removal of lots of cruft:
+
+  - Internal GUI (replaced by the OSC, see the `ON SCREEN CONTROLLER`_ section).
+  - MEncoder (replaced by native encoding, see the `ENCODING`_ section).
+  - OSD menu.
+  - Kernel video drivers for Linux 2.4 (including VIDIX).
+  - Teletext support.
+  - Support for dead platforms.
+  - Most built-in demuxers have been replaced by their libavformat counterparts.
+  - Built-in network support has been replaced by libavformat's (which also
+    supports https URLs).
+  - Embedded copies of libraries (such as FFmpeg).
+
+* General code cleanups (including refactoring or rewrites of many parts).
+* New build system.
+* Many bug fixes and removal of long-standing issues.
+* Generally preferring FFmpeg/Libav over internal demuxers, decoders, and
+  filters.
+
+Detailed Listing of User-visible Changes
+----------------------------------------
+
+This listing is about changed command line switches, slave commands, and similar
+things. Completely removed features are not listed.
+
+Command Line Switches
+~~~~~~~~~~~~~~~~~~~~~
+
+* There is a new command line syntax, which is generally preferred over the old
+  syntax. ``-optname optvalue`` becomes ``--optname=optvalue``.
+
+  The old syntax will not be removed. However, the new syntax is mentioned in
+  all documentation and so on, and unlike the old syntax is not ambiguous,
+  so it is a good thing to know about this change.
+* In general, negating switches like ``-noopt`` now have to be written as
+  ``-no-opt`` or ``--no-opt``.
+* Per-file options are not the default anymore. You can explicitly specify
+  file-local options. See ``Usage`` section.
+* Many options have been renamed, removed or changed semantics. Some options
+  that are required for a good playback experience with MPlayer are now
+  superfluous or even worse than the defaults, so make sure to read the manual
+  before trying to use your existing configuration with **mpv**.
+* Table of renamed/replaced switches:
+
+    =========================== ========================================
+    Old                         New
+    =========================== ========================================
+    ``-no<opt>``                ``--no-<opt>`` (add a dash)
+    ``-a52drc level``           ``--ad-lavc-ac3drc=level``
+    ``-ac spdifac3``            ``--ad=spdif:ac3`` (see ``--ad=help``)
+    ``-af volnorm``             (removed; use acompressor ffmpeg filter instead)
+    ``-afm hwac3``              ``--ad=spdif:ac3,spdif:dts``
+    ``-ao alsa:device=hw=0.3``  ``--ao=alsa:device=[hw:0,3]``
+    ``-aspect``                 ``--video-aspect-override``
+    ``-ass-bottom-margin``      ``--vf=sub=bottom:top``
+    ``-ass``                    ``--sub-ass``
+    ``-audiofile-cache``        (removed; the main cache settings are used)
+    ``-audiofile``              ``--audio-file``
+    ``-benchmark``              ``--untimed`` (no stats)
+    ``-capture``                ``--stream-capture=<filename>``
+    ``-channels``               ``--audio-channels`` (changed semantics)
+    ``-cursor-autohide-delay``  ``--cursor-autohide``
+    ``-delay``                  ``--audio-delay``
+    ``-dumpstream``             ``--stream-dump=<filename>``
+    ``-dvdangle``               ``--dvd-angle``
+    ``-endpos``                 ``--length``
+    ``-fixed-vo``               (removed; always the default)
+    ``-font``                   ``--osd-font``
+    ``-forcedsubsonly``         ``--sub-forced-events-only``
+    ``-forceidx``               ``--index``
+    ``-format``                 ``--audio-format``
+    ``-fsmode-dontuse``         (removed)
+    ``-fstype``                 ``--x11-netwm`` (changed semantics)
+    ``-hardframedrop``          ``--framedrop=hard``
+    ``-identify``               (removed; use TOOLS/mpv_identify.sh)
+    ``-idx``                    ``--index``
+    ``-lavdopts ...``           ``--vd-lavc-...``
+    ``-lavfdopts``              ``--demuxer-lavf-...``
+    ``-loop 0``                 ``--loop=inf``
+    ``-mixer-channel``          AO suboptions (``alsa``, ``oss``)
+    ``-mixer``                  AO suboptions (``alsa``, ``oss``)
+    ``-mouse-movements``        ``--input-cursor``
+    ``-msgcolor``               ``--msg-color``
+    ``-msglevel``               ``--msg-level`` (changed semantics)
+    ``-msgmodule``              ``--msg-module``
+    ``-name``                   ``--x11-name``
+    ``-noar``                   ``(removed; replaced by MediaPlayer framework)``
+    ``-noautosub``              ``--no-sub-auto``
+    ``-noconsolecontrols``      ``--no-input-terminal``
+    ``-nosound``                ``--no-audio``
+    ``-osdlevel``               ``--osd-level``
+    ``-panscanrange``           ``--video-zoom``, ``--video-pan-x/y``
+    ``-playing-msg``            ``--term-playing-msg``
+    ``-pp ...``                 ``'--vf=lavfi=[pp=...]'``
+    ``-pphelp``                 (See FFmpeg libavfilter documentation.)
+    ``-rawaudio ...``           ``--demuxer-rawaudio-...``
+    ``-rawvideo ...``           ``--demuxer-rawvideo-...``
+    ``-spugauss``               ``--sub-gauss``
+    ``-srate``                  ``--audio-samplerate``
+    ``-ss``                     ``--start``
+    ``-ssf <sub>``              ``--sws-...``
+    ``-stop-xscreensaver``      ``--stop-screensaver``
+    ``-sub-fuzziness``          ``--sub-auto``
+    ``-sub-text-*``             ``--sub-*``
+    ``-sub``                    ``--sub-file``
+    ``-subcp``                  ``--sub-codepage``
+    ``-subdelay``               ``--sub-delay``
+    ``-subfile``                ``--sub-file``
+    ``-subfont-*``              ``--sub-*``, ``--osd-*``
+    ``-subfont-text-scale``     ``--sub-scale``
+    ``-subfont``                ``--sub-font``
+    ``-subfps``                 ``--sub-fps``
+    ``-subpos``                 ``--sub-pos``
+    ``-sws``                    ``--sws-scaler``
+    ``-tvscan``                 ``--tv-scan``
+    ``-use-filename-title``     ``--title='${filename}'``
+    ``-vc ffh264vdpau`` (etc.)  ``--hwdec=vdpau``
+    ``-vobsub``                 ``--sub-file`` (pass the .idx file)
+    ``-x W``, ``-y H``          ``--geometry=WxH`` + ``--no-keepaspect``
+    ``-xineramascreen``         ``--screen`` (different values)
+    ``-xy W``                   ``--autofit=W``
+    ``-zoom``                   Inverse available as ``--video-unscaled``
+    ``dvdnav://``               Removed.
+    ``dvd://1``                 ``dvd://0`` (0-based offset)
+    =========================== ========================================
+
+.. note::
+
+    ``-opt val`` becomes ``--opt=val``.
+
+.. note::
+
+    Quite some video filters, video outputs, audio filters, audio outputs, had
+    changes in their option parsing. These aren't mentioned in the table above.
+
+    Also, some video and audio filters have been removed, and you have to use
+    libavfilter (using ``--vf=lavfi=[...]`` or ``--af=lavfi=[...]``) to get
+    them back.
+
+input.conf and Slave Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Table of renamed input commands:
+
+    This lists only commands that are not always gracefully handled by the
+    internal legacy translation layer. If an input.conf contains any legacy
+    commands, a warning will be printed when starting the player. The warnings
+    also show the replacement commands.
+
+    Properties containing ``_`` to separate words use ``-`` instead.
+
+    +--------------------------------+----------------------------------------+
+    | Old                            | New                                    |
+    +================================+========================================+
+    | ``pt_step 1 [0|1]``            | ``playlist-next [weak|force]``         |
+    |                                | (translation layer cannot deal with    |
+    |                                | whitespace)                            |
+    +--------------------------------+----------------------------------------+
+    | ``pt_step -1 [0|1]``           | ``playlist-prev [weak|force] (same)``  |
+    +--------------------------------+----------------------------------------+
+    | ``switch_ratio [<ratio>]``     | ``set video-aspect-override <ratio>``  |
+    |                                |                                        |
+    |                                | ``set video-aspect-override 0`` (reset)|
+    +--------------------------------+----------------------------------------+
+    | ``step_property_osd <prop>``   | ``cycle <prop> <step>`` (wraps),       |
+    | ``<step> <dir>``               | ``add <prop> <step>`` (clamps).        |
+    |                                | ``<dir>`` parameter unsupported. Use   |
+    |                                | a negative ``<step>`` instead.         |
+    +--------------------------------+----------------------------------------+
+    | ``step_property <prop>``       | Prefix ``cycle`` or ``add`` with       |
+    | ``<step> <dir>``               | ``no-osd``: ``no-osd cycle <prop>``    |
+    |                                | ``<step>``                             |
+    +--------------------------------+----------------------------------------+
+    | ``osd_show_property_text``     | ``show-text <text>``                   |
+    | ``<text>``                     | The property expansion format string   |
+    |                                | syntax slightly changed.               |
+    +--------------------------------+----------------------------------------+
+    | ``osd_show_text``              | Now does the same as                   |
+    |                                | ``osd_show_property_text``. Use the    |
+    |                                | ``raw`` prefix to disable property     |
+    |                                | expansion.                             |
+    +--------------------------------+----------------------------------------+
+    | ``show_tracks``                | ``show-text ${track-list}``            |
+    +--------------------------------+----------------------------------------+
+    | ``show_chapters``              | ``show-text ${chapter-list}``          |
+    +--------------------------------+----------------------------------------+
+    | ``af_switch``, ``af_add``, ... | ``af set|add|...``                     |
+    +--------------------------------+----------------------------------------+
+    | ``tv_start_scan``              | ``set tv-scan yes``                    |
+    +--------------------------------+----------------------------------------+
+    | ``tv_set_channel <val>``       | ``set tv-channel <val>``               |
+    +--------------------------------+----------------------------------------+
+    | ``tv_step_channel``            | ``cycle tv-channel``                   |
+    +--------------------------------+----------------------------------------+
+    | ``dvb_set_channel <v1> <v2>``  | ``set dvb-channel <v1>-<v2>``          |
+    +--------------------------------+----------------------------------------+
+    | ``dvb_step_channel``           | ``cycle dvb-channel``                  |
+    +--------------------------------+----------------------------------------+
+    | ``tv_set_freq <val>``          | ``set tv-freq <val>``                  |
+    +--------------------------------+----------------------------------------+
+    | ``tv_step_freq``               | ``cycle tv-freq``                      |
+    +--------------------------------+----------------------------------------+
+    | ``tv_set_norm <norm>``         | ``set tv-norm <norm>``                 |
+    +--------------------------------+----------------------------------------+
+    | ``tv_step_norm``               | ``cycle tv-norm``                      |
+    +--------------------------------+----------------------------------------+
+
+    .. note::
+
+        Due to lack of hardware and users using the TV/DVB/PVR features, and
+        due to the need to cleanup the related command code, it's possible
+        that the new commands are buggy or behave worse. This can be improved
+        if testers are available. Otherwise, some of the TV code will be
+        removed at some point.
+
+Slave mode
+~~~~~~~~~~
+
+* Slave mode was removed. A proper slave mode application needed tons of code
+  and hacks to get
+  it right. The main problem is that slave mode is a bad and incomplete
+  interface, and to get around that, applications parsed output messages
+  intended for users. It is hard to know which messages exactly are parsed by
+  slave mode applications. This makes it virtually impossible to improve
+  terminal output intended for users without possibly breaking something.
+
+  This is absolutely insane, and since initial improvements to **mpv** quickly
+  made slave mode incompatible to most applications, it was removed as useless
+  cruft. The client API (see below) is provided instead.
+
+  ``--identify`` was replaced by the ``TOOLS/mpv_identify.sh`` wrapper script.
+
+* For some time (until including release 0.4.x), mpv supported a
+  ``--slave-broken`` option. The following options are equivalent:
+
+  ::
+
+        --input-file=/dev/stdin --input-terminal=no
+
+
+  Assuming the system supports ``/dev/stdin``.
+
+  (The option was added back in 0.5.1 and sets exactly these options. It was
+  removed in 0.10.x again.)
+
+* A JSON RPC protocol giving access to the client API is also supported. See
+  `JSON IPC`_ for more information.
+
+* **mpv** also provides a client API, which can be used to embed the player
+  by loading it as shared library. (See ``libmpv/client.h`` in the sources.)
+  It might also be possible to implement a custom slave mode-like protocol
+  using Lua scripting.
+
+Policy for Removed Features
+---------------------------
+
+**mpv** is in active development. If something is in the way of more important
+development (such as fixing bugs or implementing new features), we sometimes
+remove features. Usually this happens only with old features that either seem
+to be useless, or are not used by anyone. Often these are obscure, or
+"inherited", or were marked experimental, but never received any particular
+praise by any users.
+
+Sometimes, features are replaced by something new. The new code will be either
+simpler or more powerful, but doesn't necessarily provide everything the old
+feature did.
+
+We can not exclude that we accidentally remove features that are actually
+popular. Generally, we do not know how much a specific functionality is used.
+If you miss a feature and think it should be re-added, please open an issue
+on the mpv bug tracker. Hopefully, a solution can be found. Often, it turns
+out that re-adding something is not much of a problem, or that there are
+better alternatives.
+
+Why this Fork?
+--------------
+
+mplayer2 is practically dead, and mpv started out as a branch containing
+new/experimental development. (Some of it was merged right *after* the fork
+was made public, seemingly as an acknowledgment that development, or at
+least merging, should have been more active.)
+
+MPlayer is focused on not breaking anything, but is stuck with a horrible
+codebase resistant to cleanup. (Unless you do what mpv did - merciless and
+consequent pruning of bad, old code.) Cleanup and keeping broken things
+conflict, so the kind of development mpv strives for can't be done within
+MPlayer due to clashing development policies.
+
+Additionally, mplayer2 already had lots of changes over MPlayer, which would
+have needed to be backported to the MPlayer codebase. This would not only
+have been hard (several years of diverging development), but also would have
+been impossible due to the aforementioned MPlayer development policy.
diff --git a/DOCS/release-policy.md b/DOCS/release-policy.md
new file mode 100644
index 0000000..2426ab4
--- /dev/null
+++ b/DOCS/release-policy.md
@@ -0,0 +1,138 @@
+Release Policy
+==============
+
+Once or twice a year, a new release is cut off of the master branch and is
+assigned a 0.X.Y version number, where X is incremented each time a release
+contains breaking changes, such as changed options or added/removed features,
+and Y is incremented if a release contains only bugfixes and other minor
+changes.
+
+Releases are tagged on the master branch and will not be maintained separately.
+Patch releases may be made if the amount or severity of bugs justify it, or in
+the event of security issues.
+
+The goal of releases is to provide Linux distributions with something to
+package. If you want the newest features, just use the master branch.
+We try our best to keep it deployable at all times.
+
+Releases other than the latest release are unsupported and unmaintained.
+
+Release procedure
+-----------------
+
+While on master:
+
+- Update the `RELEASE_NOTES` file, replacing the previous release notes.
+
+- Update the `VERSION` file.
+
+- Update `DOCS/client-api-changes.rst` and `DOCS/interface-changes.rst`
+  (in particular, update the last version numbers if necessary)
+
+- Create signed commit with changes.
+
+- Create signed tag v0.X.Y.
+
+- Push release branch (`release/0.X`) and tag to GitHub.
+
+- Create a new GitHub release using the content of `RELEASE_NOTES` related to
+  the new version.
+
+- Readd -UNKNOWN suffix to version in `VERSION` file.
+
+If necessary (to e.g. exclude commits already on master), the release can
+be done on a branch with different commit history. The release branch **must**
+then be merged to master so `git describe` will pick up the tag.
+
+This does not apply to patch releases, which are tagged directly on the
+`release/0.X` branch. The master branch always remains at v0.X.0.
+
+Release notes template
+----------------------
+
+Here is a template that can be used for writing the `RELEASE_NOTES` file:
+
+```markdown
+Release 0.X.Y
+=============
+
+This release requires FFmpeg <ver> or newer.
+
+Features
+--------
+
+New
+~~~
+
+- List of new features
+
+
+Changed
+~~~~~~~
+
+- List of changed features
+
+
+Removed
+~~~~~~~
+
+- List of removed features
+
+
+Options and Commands
+--------------------
+
+Added
+~~~~~
+
+- List of added options and commands
+
+
+Changed
+~~~~~~~
+
+- List of changed options and commands
+
+
+Deprecated
+~~~~~~~~~~
+
+- List of deprecated options and commands
+
+
+Removed
+~~~~~~~
+
+- List of removed options and commands
+
+
+Fixes and Minor Enhancements
+----------------------------
+
+- List of fixes and minor enhancements
+
+
+This listing is not complete. Check DOCS/client-api-changes.rst for a history
+of changes to the client API, and DOCS/interface-changes.rst for a history
+of changes to other user-visible interfaces.
+
+A complete changelog can be seen by running `git log <start>..<end>`
+in the git repository.
+```
+
+When creating a new point release its changes should be added on top of the
+`RELEASE_NOTES` file (with the appropriate title) so that all the changes in
+the current 0.X branch will be included. This way the `RELEASE_NOTES` file
+can be used by distributors as changelog for point releases too.
+
+The changelog of lists all changes since the last release, including those
+that have been backported to patch releases already.
+
+Some additional advice:
+- Especially for features, try to reword the messages so that the user-visible
+  change is clear to the reader. But don't simplify too much or be too verbose.
+- It often makes sense to merge multiple related changes into one line
+- Changes that have been made and reverted within the same release must not
+  appear in the changelog
+- Limit the "Options and Commands" section to relevant changes
+- When filling in the GitHub release, remove the "Release 0.X.Y" heading
diff --git a/DOCS/tech-overview.txt b/DOCS/tech-overview.txt
new file mode 100644
index 0000000..e723f78
--- /dev/null
+++ b/DOCS/tech-overview.txt
@@ -0,0 +1,656 @@
+This file intends to give a big picture overview of how mpv is structured.
+
+player/*.c:
+    Essentially makes up the player applications, including the main() function
+    and the playback loop.
+
+    Generally, it accesses all other subsystems, initializes them, and pushes
+    data between them during playback.
+
+    The structure is as follows (as of commit e13c05366557cb):
+    * main():
+        * basic initializations (e.g. init_libav() and more)
+        * pre-parse command line (verbosity level, config file locations)
+        * load config files (parse_cfgfiles())
+        * parse command line, add files from the command line to playlist
+          (m_config_parse_mp_command_line())
+        * check help options etc. (call handle_help_options()), possibly exit
+        * call mp_play_files() function that works down the playlist:
+            * run idle loop (idle_loop()), until there are files in the
+                playlist or an exit command was given (only if --idle it set)
+            * actually load and play a file in play_current_file():
+                * run all the dozens of functions to load the file and
+                  initialize playback
+                * run a small loop that does normal playback, until the file is
+                  done or a command terminates playback
+                  (on each iteration, run_playloop() is called, which is rather
+                   big and complicated - it decodes some audio and video on
+                   each frame, waits for input, etc.)
+                * uninitialize playback
+            * determine next entry on the playlist to play
+            * loop, or exit if no next file or quit is requested
+              (see enum stop_play_reason)
+        * call mp_destroy()
+    * run_playloop():
+        * calls fill_audio_out_buffers()
+            This checks whether new audio needs to be decoded, and pushes it
+            to the AO.
+        * calls write_video()
+            Decode new video, and push it to the VO.
+        * determines whether playback of the current file has ended
+        * determines when to start playback after seeks
+        * and calls a whole lot of other stuff
+            (Really, this function does everything.)
+
+    Things worth saying about the playback core:
+    - most state is in MPContext (core.h), which is not available to the
+      subsystems (and should not be made available)
+    - the currently played tracks are in mpctx->current_tracks, and decoder
+      state in track.dec/d_sub
+    - the other subsystems rarely call back into the frontend, and the frontend
+      polls them instead (probably a good thing)
+    - one exceptions are wakeup callbacks, which notify a "higher" component
+      of a changed situation in a subsystem
+
+    I like to call the player/*.c files the "frontend".
+
+ta.h & ta.c:
+    Hierarchical memory manager inspired by talloc from Samba. It's like a
+    malloc() with more features. Most importantly, each talloc allocation can
+    have a parent, and if the parent is free'd, all children will be free'd as
+    well. The parent is an arbitrary talloc allocation. It's either set by the
+    allocation call by passing a talloc parent, usually as first argument to the
+    allocation function. It can also be set or reset later by other calls (at
+    least talloc_steal()). A talloc allocation that is used as parent is often
+    called a talloc context.
+
+    One very useful feature of talloc is fast tracking of memory leaks. ("Fast"
+    as in it doesn't require valgrind.) You can enable it by setting the
+    MPV_LEAK_REPORT environment variable to "1":
+        export MPV_LEAK_REPORT=1
+    Or permanently by building with --enable-ta-leak-report.
+    This will list all unfree'd allocations on exit.
+
+    Documentation can be found here:
+        http://git.samba.org/?p=samba.git;a=blob;f=lib/talloc/talloc.h;hb=HEAD
+
+    For some reason, we're still using API-compatible wrappers instead of TA
+    directly. The talloc wrapper has only a subset of the functionality, and
+    in particular the wrappers abort() on memory allocation failure.
+
+    Note: unlike tcmalloc, jemalloc, etc., talloc() is not actually a malloc
+          replacement. It works on top of system malloc and provides additional
+          features that are supposed to make memory management easier.
+
+player/command.c:
+    This contains the implementation for client API commands and properties.
+    Properties are essentially dynamic variables changed by certain commands.
+    This is basically responsible for all user commands, like initiating
+    seeking, switching tracks, etc. It calls into other player/*.c files,
+    where most of the work is done, but also calls other parts of mpv.
+
+player/core.h:
+    Data structures and function prototypes for most of player/*.c. They are
+    usually not accessed by other parts of mpv for the sake of modularization.
+
+player/client.c:
+    This implements the client API (libmpv/client.h). For the most part, this
+    just calls into other parts of the player. This also manages a ringbuffer
+    of events from player to clients.
+
+options/options.h, options/options.c
+    options.h contains the global option struct MPOpts. The option declarations
+    (option names, types, and MPOpts offsets for the option parser) are in
+    options.c. Most default values for options and MPOpts are in
+    mp_default_opts at the end of options.c.
+
+    MPOpts is unfortunately quite monolithic, but is being incrementally broken
+    up into sub-structs. Many components have their own sub-option structs
+    separate from MPOpts. New options should be bound to the component that uses
+    them. Add a new option table/struct if needed.
+
+    The global MPOpts still contains the sub-structs as fields, which serves to
+    link them to the option parser. For example, an entry like this may be
+    typical:
+
+        {"", OPT_SUBSTRUCT(demux_opts, demux_conf)},
+
+    This directs the option access code to include all options in demux_conf
+    into the global option list, with no prefix (""), and as part of the
+    MPOpts.demux_opts field. The MPOpts.demux_opts field is actually not
+    accessed anywhere, and instead demux.c does this:
+
+        struct m_config_cache *opts_cache =
+            m_config_cache_alloc(demuxer, global, &demux_conf);
+        struct demux_opts *opts = opts_cache->opts;
+
+    ... to get a copy of its options.
+
+    See m_config.h (below) how to access options.
+
+    The actual option parser is spread over m_option.c, m_config.c, and
+    parse_commandline.c, and uses the option table in options.c.
+
+options/m_config.h & m_config.c:
+    Code for querying and managing options. This (unfortunately) contains both
+    declarations for the "legacy-ish" global m_config struct, and ways to access
+    options in a threads-safe way anywhere, like m_config_cache_alloc().
+
+    m_config_cache_alloc() lets anyone read, observe, and write options in any
+    thread. The only state it needs is struct mpv_global, which is an opaque
+    type that can be passed "down" the component hierarchy. For safety reasons,
+    you should not pass down any pointers to option structs (like MPOpts), but
+    instead pass down mpv_global, and use m_config_cache_alloc() (or similar)
+    to get a synchronized copy of the options.
+
+input/input.c:
+    This translates keyboard input coming from VOs and other sources (such
+    as remote control devices like Apple IR or client API commands) to the
+    key bindings listed in the user's (or the builtin) input.conf and turns
+    them into items of type struct mp_cmd. These commands are queued, and read
+    by playloop.c. They get pushed with run_command() to command.c.
+
+    Note that keyboard input and commands used by the client API are the same.
+    The client API only uses the command parser though, and has its own queue
+    of input commands somewhere else.
+
+common/msg.h:
+    All terminal output must go through mp_msg().
+
+stream/*:
+    File input is implemented here. stream.h/.c provides a simple stream based
+    interface (like reading a number of bytes at a given offset). mpv can
+    also play from http streams and such, which is implemented here.
+
+    E.g. if mpv sees "http://something" on the command line, it will pick
+    stream_lavf.c based on the prefix, and pass the rest of the filename to it.
+
+    Some stream inputs are quite special: stream_dvd.c turns DVDs into mpeg
+    streams (DVDs are actually a bunch of vob files etc. on a filesystem),
+    stream_tv.c provides TV input including channel switching.
+
+    Some stream inputs are just there to invoke special demuxers, like
+    stream_mf.c. (Basically to make the prefix "mf://" do something special.)
+
+demux/:
+    Demuxers split data streams into audio/video/sub streams, which in turn
+    are split in packets. Packets (see demux_packet.h) are mostly byte chunks
+    tagged with a playback time (PTS). These packets are passed to the decoders.
+
+    Most demuxers have been removed from this fork, and the only important and
+    "actual" demuxers left are demux_mkv.c and demux_lavf.c (uses libavformat).
+    There are some pseudo demuxers like demux_cue.c.
+
+    The main interface is in demux.h. The stream headers are in stheader.h.
+    There is a stream header for each audio/video/sub stream, and each of them
+    holds codec information about the stream and other information.
+
+    demux.c is a bit big, the main reason being that it contains the demuxer
+    cache, which is implemented as a list of packets. The cache is complex
+    because it support seeking, multiple ranges, prefetching, and so on.
+
+video/:
+    This contains several things related to audio/video decoding, as well as
+    video filters.
+
+    mp_image.h and img_format.h define how mpv stores decoded video frames
+    internally.
+
+video/decode/:
+    vd_*.c are video decoders. (There's only vd_lavc.c left.) dec_video.c
+    handles most of connecting the frontend with the actual decoder.
+
+video/filter/:
+    vf_*.c and vf.c form the video filter chain. They are fed by the video
+    decoder, and output the filtered images to the VOs though vf_vo.c. By
+    default, no video filters (except vf_vo) are used. vf_scale is automatically
+    inserted if the video output can't handle the video format used by the
+    decoder.
+
+video/out/:
+    Video output. They also create GUI windows and handle user input. In most
+    cases, the windowing code is shared among VOs, like x11_common.c for X11 and
+    w32_common.c for Windows. The VOs stand between frontend and windowing code.
+    vo_gpu can pick a windowing system at runtime, e.g. the same binary can
+    provide both X11 and Cocoa support on OSX.
+
+    VOs can be reconfigured at runtime. A vo_reconfig() call can change the video
+    resolution and format, without destroying the window.
+
+    vo_gpu should be taken as reference.
+
+audio/:
+    format.h/format.c define the uncompressed audio formats. (As well as some
+    compressed formats used for spdif.)
+
+audio/decode/:
+    ad_*.c and dec_audio.c handle audio decoding. ad_lavc.c is the
+    decoder using ffmpeg. ad_spdif.c is not really a decoder, but is used for
+    compressed audio passthrough.
+
+audio/filter/:
+    Audio filter chain. af_lavrresample is inserted if any form of conversion
+    between audio formats is needed.
+
+audio/out/:
+    Audio outputs.
+
+    Unlike VOs, AOs can't be reconfigured on a format change. On audio format
+    changes, the AO will simply be closed and re-opened.
+
+    There are wrappers to support for two types of audio APIs: push.c and
+    pull.c. ao.c calls into one of these. They contain generic code to deal
+    with the data flow these APIs impose.
+
+    Note that mpv synchronizes the video to the audio. That's the reason
+    why buggy audio drivers can have a bad influence on playback quality.
+
+sub/:
+    Contains subtitle and OSD rendering.
+
+    osd.c/.h is actually the OSD code. It queries dec_sub.c to retrieve
+    decoded/rendered subtitles. osd_libass.c is the actual implementation of
+    the OSD text renderer (which uses libass, and takes care of all the tricky
+    fontconfig/freetype API usage and text layouting).
+
+    The VOs call osd.c to render OSD and subtitle (via e.g. osd_draw()). osd.c
+    in turn asks dec_sub.c for subtitle overlay bitmaps, which relays the
+    request to one of the sd_*.c subtitle decoders/renderers.
+
+    Subtitle loading is in demux/. The MPlayer subreader.c is mostly gone - parts
+    of it survive in demux_subreader.c. It's used as last fallback, or to handle
+    some text subtitle types on Libav. It should go away eventually. Normally,
+    subtitles are loaded via demux_lavf.c.
+
+    The subtitles are passed to dec_sub.c and the subtitle decoders in sd_*.c
+    as they are demuxed. All text subtitles are rendered by sd_ass.c. If text
+    subtitles are not in the ASS format, the libavcodec subtitle converters are
+    used (lavc_conv.c).
+
+    Text subtitles can be preloaded, in which case they are read fully as soon
+    as the subtitle is selected. In this case, they are effectively stored in
+    sd_ass.c's internal state.
+
+etc/:
+    The file input.conf is actually integrated into the mpv binary by the
+    build system. It contains the default keybindings.
+
+Best practices and Concepts within mpv
+======================================
+
+General contribution etc.
+-------------------------
+
+See: DOCS/contribute.md
+
+Error checking
+--------------
+
+If an error is relevant, it should be handled. If it's interesting, log the
+error. However, mpv often keeps errors silent and reports failures somewhat
+coarsely by propagating them upwards the caller chain. This is OK, as long as
+the errors are not very interesting, or would require a developer to debug it
+anyway (in which case using a debugger would be more convenient, and the
+developer would need to add temporary debug printfs to get extremely detailed
+information which would not be appropriate during normal operation).
+
+Basically, keep a balance on error reporting. But always check them, unless you
+have a good argument not to.
+
+Memory allocation errors (OOM) are a special class of errors. Normally such
+allocation failures are not handled "properly". Instead, abort() is called.
+(New code should use MP_HANDLE_OOM() for this.) This is done out of laziness and
+for convenience, and due to the fact that MPlayer/mplayer2 never handled it
+correctly. (MPlayer varied between handling it correctly, trying to do so but
+failing, and just not caring, while mplayer2 started using abort() for it.)
+
+This is justifiable in a number of ways. Error handling paths are notoriously
+untested and buggy, so merely having them won't make your program more reliable.
+Having these error handling paths also complicates non-error code, due to the
+need to roll back state at any point after a memory allocation.
+
+Take any larger body of code, that is supposed to handle OOM, and test whether
+the error paths actually work, for example by overriding malloc with a version
+that randomly fails. You will find bugs quickly, and often they will be very
+annoying to fix (if you can even reproduce them).
+
+In addition, a clear indication that something went wrong may be missing. On
+error your program may exhibit "degraded" behavior by design. Consider a video
+encoder dropping frames somewhere in the middle of a video due to temporary
+allocation failures, instead of just exiting with an errors. In other cases, it
+may open conceptual security holes. Failing fast may be better.
+
+mpv uses GPU APIs, which may be break on allocation errors (because driver
+authors will have the same issues as described here), or don't even have a real
+concept for dealing with OOM (OpenGL).
+
+libmpv is often used by GUIs, which I predict always break if OOM happens.
+
+Last but not least, OSes like Linux use "overcommit", which basically means that
+your program may crash any time OOM happens, even if it doesn't use malloc() at
+all!
+
+But still, don't just assume malloc() always succeeds. Use MP_HANDLE_OOM(). The
+ta* APIs do this for you. The reason for this is that dereferencing a NULL
+pointer can have security relevant consequences if large offsets are involved.
+Also, a clear error message is better than a random segfault.
+
+Some big memory allocations are checked anyway. For example, all code must
+assume that allocating video frames or packets can fail. (The above example
+of dropping video frames during encoding is entirely possible in mpv.)
+
+Undefined behavior
+------------------
+
+Undefined behavior (UB) is a concept in the C language. C is famous for being a
+language that makes it almost impossible to write working code, because
+undefined behavior is so easily triggered, compilers will happily abuse it to
+generate "faster" code, debugging tools will shout at you, and sometimes it
+even means your code doesn't work.
+
+There is a lot of literature on this topic. Read it.
+
+(In C's defense, UB exists in other languages too, but since they're not used
+for low level infrastructure, and/or these languages are at times not rigorously
+defined, simply nobody cares. However, the C standard committee is still guilty
+for not addressing this. I'll admit that I can't even tell from the standard's
+gibberish whether some specific behavior is UB or not. It's written like tax
+law.)
+
+In mpv, we generally try to avoid undefined behavior. For one, we want portable
+and reliable operation. But more importantly, we want clean output from
+debugging tools, in order to find real bugs more quickly and effectively.
+
+Avoid the "works in practice" argument. Once debugging tools come into play, or
+simply when "in practice" stops being true, this will all get back to you in a
+bad way.
+
+Global state, library safety
+----------------------------
+
+Mutable global state is when code uses global variables that are not read-only.
+This must be avoided in mpv. Always use context structs that the caller of
+your code needs to allocate, and whose pointers are passed to your functions.
+
+Library safety means that your code (or library) can be used by a library
+without causing conflicts with other library users in the same process. To any
+piece of code, a "safe" library's API can simply be used, without having to
+worry about other API users that may be around somewhere.
+
+Libraries are often not library safe, because they use global mutable state
+or other "global" resources. Typical examples include use of signals, simple
+global variables (like hsearch() in libc), or internal caches not protected by
+locks.
+
+A surprisingly high number of libraries are not library safe because they need
+global initialization. Typically they provide an API function, which
+"initializes" the library, and which must be called before calling any other
+API functions. Often, you are to provide global configuration parameters, which
+can change the behavior of the library. If two libraries A and B use library C,
+but A and B initialize C with different parameters, something "bad" may happen.
+In addition, these global initialization functions are often not thread-safe. So
+if A and B try to initialize C at the same time (from different threads and
+without knowing about each other), it may cause undefined behavior. (libcurl is
+a good example of both of these issues. FFmpeg and some TLS libraries used to be
+affected, but improved.)
+
+This is so bad because library A and B from the previous example most likely
+have no way to cooperate, because they're from different authors and have no
+business knowing each others. They'd need a library D, which wraps library C
+in a safe way. Unfortunately, typically something worse happens: libraries get
+"infected" by the unsafeness of its sub-libraries, and export a global init API
+just to initialize the sub-libraries. In the previous example, libraries A and B
+would export global init APIs just to init library C, even though the rest of
+A/B are clean and library safe. (Again, libcurl is an example of this, if you
+subtract other historic anti-features.)
+
+The main problem with library safety is that its lack propagates to all
+libraries using the library.
+
+We require libmpv to be library safe. This is not really possible, because some
+libraries are not library safe (FFmpeg, Xlib, partially ALSA). However, for
+ideological reasons, there is no global init API, and best effort is made to try
+to avoid problems.
+
+libmpv has some features that are not library safe, but which are disabled by
+default (such as terminal usage aka stdout, or JSON IPC blocking SIGPIPE for
+internal convenience).
+
+A notable, very disgustingly library unsafe behavior of libmpv is calling
+abort() on some memory allocation failure. See error checking section.
+
+Logging
+-------
+
+All logging and terminal output in mpv goes through the functions and macros
+provided in common/msg.h. This is in part for library safety, and in part to
+make sure users can silence all output, or to redirect the output elsewhere,
+like a log file or the internal console.lua script.
+
+Locking
+-------
+
+See generally available literature. In mpv, we use mp_thread for this.
+
+Always keep locking clean. Don't skip locking just because it will work "in
+practice". (See undefined behavior section.) If your use case is simple, you may
+use C11 atomics, but most likely you will only hurt yourself and others.
+
+Always make clear which fields in a struct are protected by which lock. If a
+field is immutable, or simply not thread-safe (e.g. state for a single worker
+thread), document it as well.
+
+Internal mpv APIs are assumed to be not thread-safe by default. If they have
+special guarantees (such as being usable by more than one thread at a time),
+these should be explicitly documented.
+
+All internal mpv APIs must be free of global state. Even if a component is not
+thread-safe, multiple threads can use _different_ instances of it without any
+locking.
+
+On a side note, recursive locks may seem convenient at first, but introduce
+additional problems with condition variables and locking hierarchies. They
+should be avoided.
+
+Locking hierarchy
+-----------------
+
+A simple way to avoid deadlocks with classic locking is to define a locking
+hierarchy or lock order. If all threads acquire locks in the same order, no
+deadlocks will happen.
+
+For example, a "leaf" lock is a lock that is below all other locks in the
+hierarchy. You can acquire it any time, as long as you don't acquire other
+locks while holding it.
+
+Unfortunately, C has no way to declare or check the lock order, so you should at
+least document it.
+
+In addition, try to avoid exposing locks to the outside. Making the declaration
+of a lock private to a specific .c file (and _not_ exporting accessors or
+lock/unlock functions that manipulate the lock) is a good idea. Your component's
+API may acquire internal locks, but should release them when returning. Keeping
+the entire locking in a single file makes it easy to check it.
+
+Avoiding callback hell
+----------------------
+
+mpv code is separated in components, like the "frontend" (i.e. MPContext mpctx),
+VOs, AOs, demuxers, and more. The frontend usually calls "down" the usage
+hierarchy: mpctx almost on top, then things like vo/ao, and utility code on the
+very bottom.
+
+"Callback hell" is when components call both up and down the hierarchy,
+which for example leads to accidentally recursion, reentrancy problems, or
+locking nightmares. This is avoided by (mostly) calling only down the hierarchy.
+Basically the call graph forms a DAG. The other direction is handled by event
+queues, wakeup callbacks, and similar mechanisms.
+
+Typically, a component provides an API, and does not know anything about its
+user. The API user (component higher in the hierarchy) polls the state of the
+lower component when needed.
+
+This also enforces some level of modularization, and with some luck the locking
+hierarchy. (Basically, locks of lower components automatically become leaf
+locks.) Another positive effect is simpler memory management.
+
+(Also see e.g.: http://250bpm.com/blog:24)
+
+Wakeup callbacks
+----------------
+
+This is a common concept in mpv. Even the public API uses it. It's used when an
+API has internal threads (or otherwise triggers asynchronous events), but the
+component call hierarchy needs to be kept. The wakeup callback is the only
+exception to the call hierarchy, and always calls up.
+
+For example, vo spawns a thread that the API user (the mpv frontend) does not
+need to know about. vo simply provides a single-threaded API (or that looks like
+one). This API needs a way to notify the API user of new events. But the vo
+event producer is on the vo thread - it can't simply invoke a callback back into
+the API user, because then the API user has to deal with locking, despite not
+using threads. In addition, this will probably cause problems like mentioned in
+the "callback hell" section, especially lock order issues.
+
+The solution is the wakeup callback. It merely unblocks the API user from
+waiting, and the API user then uses the normal vo API to examine whether or
+which state changed. As a concept, it documents what a wakeup callback is
+allowed to do and what not, to avoid the aforementioned problems.
+
+Generally, you are not allowed to call any API from the wakeup callback. You
+just do whatever is needed to unblock your thread. For example, if it's waiting
+on a mutex/condition variable, acquire the mutex, set a change flag, signal
+the condition variable, unlock, return. (This mutex must not be held when
+calling the API. It must be a leaf lock.)
+
+Restricting the wakeup callback like this sidesteps any reentrancy issues and
+other complexities. The API implementation can simply hold internal (and
+non-recursive) locks while invoking the wakeup callback.
+
+The API user still needs to deal with locking (probably), but there's only the
+need to implement a single "receiver", that can handle the entire API of the
+used component. (Or multiple APIs - MPContext for example has only 1 wakeup
+callback that handles all AOs, VOs, input, demuxers, and more. It simple re-runs
+the playloop.)
+
+You could get something more advanced by turning this into a message queue. The
+API would append a message to the queue, and the API user can read it. But then
+you still need a way to "wakeup" the API user (unless you force the API user
+to block on your API, which will make things inconvenient for the API user). You
+also need to worry about what happens if the message queue overruns (you either
+lose messages or have unbounded memory usage). In the mpv public API, the
+distinction between message queue and wakeup callback is sort of blurry, because
+it does provide a message queue, but an additional wakeup callback, so API
+users are not required to call mpv_wait_event() with a high timeout.
+
+mpv itself prefers using wakeup callbacks over a generic event queue, because
+most times an event queue is not needed (or complicates things), and it is
+better to do it manually.
+
+(You could still abstract the API user side of wakeup callback handling, and
+avoid reimplementing it all the time. Although mp_dispatch_queue already
+provides mechanisms for this.)
+
+Condition variables
+-------------------
+
+They're used whenever a thread needs to wait for something, without nonsense
+like sleep calls or busy waiting. mpv uses the mp_thread API for this.
+There's a lot of literature on condition variables, threading in general. Read it.
+
+For initial understanding, it may be helpful to know that condition variables
+are not variables that signal a condition. mp_cond does not have any
+state per-se. Maybe mp_cond would better be named mp_interrupt,
+because its sole purpose is to interrupt a thread waiting via mp_cond_wait()
+(or similar). The "something" in "waiting for something" can be called
+predicate (to avoid confusing it with "condition"). Consult literature for the
+proper terms.
+
+The very short version is...
+
+Shared declarations:
+
+    mp_mutex lock;
+    mp_cond cond_var;
+    struct something state_var; // protected by lock, changes signaled by cond_var
+
+Waiter thread:
+
+    mp_mutex_lock(&lock);
+
+    // Wait for a change in state_var. We want to wait until predicate_fulfilled()
+    // returns true.
+    // Must be a loop for 2 reasons:
+    //  1. cond_var may be associated with other conditions too
+    //  2. mp_cond_wait() can have sporadic wakeups
+    while (!predicate_fulfilled(&state_var)) {
+        // This unlocks, waits for cond_var to be signaled, and then locks again.
+        // The _whole_ point of cond_var is that unlocking and waiting for the
+        // signal happens atomically.
+        mp_cond_wait(&cond_var, &lock);
+    }
+
+    // Here you may react to the state change. The state cannot change
+    // asynchronously as long as you still hold the lock (and didn't release
+    // and reacquire it).
+    // ...
+
+    mp_mutex_unlock(&lock);
+
+Signaler thread:
+
+    mp_mutex_lock(&lock);
+
+    // Something changed. Update the shared variable with the new state.
+    update_state(&state_var);
+
+    // Notify that something changed. This will wake up the waiter thread if
+    // it's blocked in mp_cond_wait(). If not, nothing happens.
+    mp_cond_broadcast(&cond_var);
+
+    // Fun fact: good implementations wake up the waiter only when the lock is
+    // released, to reduce kernel scheduling overhead.
+    mp_mutex_unlock(&lock);
+
+Some basic rules:
+    1. Always access your state under proper locking
+    2. Always check your predicate before every call to mp_cond_wait()
+       (And don't call mp_cond_wait() if the predicate is fulfilled.)
+    3. Always call mp_cond_wait() in a loop
+       (And only if your predicate failed without releasing the lock..)
+    4. Always call mp_cond_broadcast()/_signal() inside of its associated
+       lock
+
+mpv sometimes violates rule 3, and leaves "retrying" (i.e. looping) to the
+caller.
+
+Common pitfalls:
+    - Thinking that mp_cond is some kind of semaphore, or holds any
+       application state or the user predicate (it _only_ wakes up threads
+       that are at the same time blocking on mp_cond_wait() and friends,
+       nothing else)
+    - Changing the predicate, but not updating all mp_cond_broadcast()/
+      _signal() calls correctly
+    - Forgetting that mp_cond_wait() unlocks the lock (other threads can
+      and must acquire the lock)
+    - Holding multiple nested locks while trying to wait (=> deadlock, violates
+      the lock order anyway)
+    - Waiting for a predicate correctly, but unlocking/relocking before acting
+      on it (unlocking allows arbitrary state changes)
+    - Confusing which lock/condition var. is used to manage a bit of state
+
+Generally available literature probably has better examples and explanations.
+
+Using condition variables the proper way is generally preferred over using more
+messy variants of them. (Just saying because on win32, "SetEvent" exists, and
+it's inferior to condition variables. Try to avoid the win32 primitives, even if
+you're dealing with Windows-only code.)
+
+Threads
+-------
+
+Threading should be conservatively used. Normally, mpv code pretends to be
+single-threaded, and provides thread-unsafe APIs. Threads are used coarsely,
+and if you can avoid messing with threads, you should. For example, VOs and AOs
+do not need to deal with threads normally, even though they run on separate
+threads. The glue code "isolates" them from any threading issues.