Adding upstream version 0.37.0.upstream/0.37.0

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

1 files changed, 1690 insertions, 0 deletions

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`_.