From b6b8bffd2d4438e007da4cbf9b50e9305016bd73 Mon Sep 17 00:00:00 2001
From: Alexander Preisinger <alexander.preisinger@gmail.com>
Date: Thu, 31 Jul 2014 16:32:37 +0200
Subject: manpage: add sections and order by usage

Split the options into the following sections:

 * Playback Control
 * Program Behaviour
 * Video
 * Audio
 * Subtitles
 * Window
 * Disc Devices
 * Equalizer
 * Demuxer
 * Input
 * OSD
 * Screenshot
 * Software Scaler
 * Terminal
 * TV
 * Cache
 * Network
 * DVB
 * PVR
 * Miscellaneous

Most options are sorted by usefullness and how often they're used or how
important they are.
This makes finding the right options easier and adds some sort of structure.
---
 DOCS/man/options.rst | 4113 ++++++++++++++++++++++++++------------------------
 1 file changed, 2123 insertions(+), 1990 deletions(-)

(limited to 'DOCS')

diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 17257844b5..eaab0c48e7 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -1,82 +1,8 @@
 OPTIONS
 =======
 
-``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>``
-    Specify a priority list of audio decoders to be used, according to their
-    family and decoder name. Entries like ``family:*`` prioritize all decoders
-    of the given family. 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!
-
-    ``-`` in front of an entry disables selection of the decoder.
-
-    .. admonition:: Examples
-
-        ``--ad=lavc:mp3float``
-            Prefer the FFmpeg/Libav ``mp3float`` decoder over all other mp3
-            decoders.
-
-        ``--ad=spdif:ac3,lavc:*``
-            Always prefer spdif AC3 over FFmpeg/Libav over anything else.
-
-        ``--ad=help``
-            List all available decoders.
-
-``--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 and 1 (which is the default) means full compression (make loud
-    passages more silent and vice versa). Values up to 2 are also accepted, but
-    are purely experimental. This option only shows an effect if the AC-3 stream
-    contains the required range compression information.
-
-``--ad-lavc-downmix=<yes|no>``
-    Whether to request audio channel downmixing from the decoder (default: yes).
-    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.
-
-``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd``
-    When using DTS passthrough, output any DTS-HD track as-is.
-    With ``ad-spdif-dtshd=no`` (the default), only the DTS Core parts will be
-    output.
-
-    DTS-HD tracks can be sent over HDMI but not over the original
-    coax/toslink S/PDIF system.
-
-    Some receivers don't accept DTS core-only when ``--ad-spdif-dtshd=yes`` is
-    used, even though they accept DTS-HD.
-
-    ``--dtshd`` and ``--no-dtshd`` are deprecated aliases.
-
-``--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``, ``--af-del`` and
-    ``--af-clr`` exist to modify a previously specified list, but you
-    should not need these for typical use.
-
-``--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.
+Track Selection
+---------------
 
 ``--alang=<languagecode[,languagecode,...]>``
     Specify a priority list of audio languages to use. Different container
@@ -92,1222 +18,1354 @@ OPTIONS
         ``mpv --alang=jpn example.mkv``
             Plays a Matroska file in Japanese.
 
-``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>``
-    Specify a priority list of audio output drivers to be used. For
-    interactive use one would normally specify a single one to use, but in
-    configuration files specifying a list of fallbacks may make sense. See
-    `AUDIO OUTPUT DRIVERS`_ for details and descriptions of available drivers.
-
-``--sub-ass``, ``--no-sub-ass``
-    Render ASS subtitles natively (enabled by default).
+``--slang=<languagecode[,languagecode,...]>``
+    Specify a priority list of subtitle languages to use. Different container
+    formats employ different language codes. DVDs use ISO 639-1 two letter
+    language codes, Matroska uses ISO 639-2 three letter language codes while
+    OGM uses a free-form identifier. See also ``--sid``.
 
-    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-text-`` options instead.
+    .. admonition:: Examples
 
-    .. note::
+        - ``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.
 
-        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.
+``--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.
 
-    .. note::
+``--sid=<ID|auto|no>``
+    Display the subtitle stream specified by ``<ID>``. ``auto`` selects
+    the default, ``no`` disables subtitles.
 
-        Try using ``--ass-style-override=force`` instead.
+    See also ``--slang``, ``--no-sub``.
 
-``--ass-force-style=<[Style.]Param=Value[,...]>``
-    Override some style or script info parameters.
+``--vid=<ID|auto|no>``
+    Select video channel. ``auto`` selects the default, ``no`` disables video.
 
-    .. admonition:: Examples
+``--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.
 
-        - ``--ass-force-style=FontName=Arial,Default.Bold=1``
-        - ``--ass-force-style=PlayResY=768``
 
-    .. note::
+Playback Control
+----------------
 
-        Using this option may lead to incorrect subtitle rendering.
+``--start=<relative time>``
+    Seek to given time position.
 
-``--ass-hinting=none|light|normal|native``
-    Set font hinting type. <type> can be:
+    The general format for absolute times is ``[[hh:]mm:]ss[.ms]``. If the time
+    is given with a prefix of ``+`` or ``-``, the seek is relative from the start
+    or end of the file.
 
-    :none:       no hinting (default)
-    :light:      FreeType autohinter, light mode
-    :normal:     FreeType autohinter, normal mode
-    :native:     font native hinter
+    ``pp%`` seeks to percent position pp (0-100).
 
-    .. admonition:: Warning
+    ``#c`` seeks to chapter number c. (Chapters start from 1.)
 
-        Enabling hinting can lead to mispositioned text (in situations it's
-        supposed to match up with 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.
+    .. admonition:: Examples
 
-``--ass-line-spacing=<value>``
-    Set line spacing value for SSA/ASS renderer.
+        ``--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.
 
-``--ass-shaper=simple|complex``
-    Set the text layout engine used by libass.
+``--end=<time>``
+    Stop at given absolute time. Use ``--length`` if the time should be relative
+    to ``--start``. See ``--start`` for valid option values and examples.
 
-    :simple:   uses Fribidi only, fast, doesn't render some languages correctly
-    :complex:  uses HarfBuzz, slower, wider language support
+``--length=<relative time>``
+    Stop after a given time relative to the start time.
+    See ``--start`` for valid option values and examples.
 
-    ``complex`` is the default. If libass hasn't been compiled against HarfBuzz,
-    libass silently reverts to ``simple``.
+``--speed=<0.01-100>``
+    Slow down or speed up playback by the factor given as parameter.
 
-``--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.
+``--loop=<N|inf|no>``
+    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.
 
-    .. note::
+``--pause``
+    Start the player in paused state.
 
-        Using this option may lead to incorrect subtitle rendering.
+``--shuffle``
+    Play files in random order.
 
-``--ass-style-override=<yes|no|force>``
-    Control whether user style overrides should be applied.
+``--chapter=<start[-end]>``
+    Specify which chapter to start playing at. Optionally specify which
+    chapter to end playing at. Also see ``--start``.
 
-    :yes:   Apply all the ``--ass-*`` style override options. Changing the default
-            for any of these options can lead to incorrect subtitle rendering
-            (default).
-    :no:    Render subtitles as forced by subtitle scripts.
-    :force: Try to force the font style as defined by the ``--sub-text-*``
-            options. Requires a modified libass, can break rendering easily.
-            Probably more reliable than ``force``.
+``--playlist=<filename>``
+    Play files according to a playlist file (Supports some common formats.If
+    no format is detected, t will be treated as list of files, separated by
+    newline characters. Note that XML playlist formats are not supported.)
 
-``--ass-use-margins``
-    Enables placing toptitles and subtitles in black borders when they are
-    available.
+    .. warning::
 
-``--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 way mpv uses playlist files is not safe against maliciously
+        constructed files. Such files may trigger harmful actions.
+        This has been the case for all mpv and MPlayer versions, but
+        unfortunately this fact was not well documented earlier, and some people
+        have even misguidedly recommended use of ``--playlist`` with untrusted
+        sources. Do NOT use ``--playlist`` with random internet sources or files
+        you do not trust!
 
-    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).
+        The main problem is that playlists can point to arbitrary network
+        addresses (including local addresses inside of your LAN), and thus
+        can't be considered secure. Playlists also can contain entries using
+        other protocols, such as local files, or (most severely), special
+        protocols like ``avdevice://``, which are inherently unsafe.
 
-    Enabled by default.
+``--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.
 
-``--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.
+``--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.
 
-    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.
+``--hr-seek=<no|absolute|yes>``
+    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 slave mode commands.
 
-``--ass-vsfilter-color-compat=<basic|full|force-601|no>``
-    Mangle colors like (xy-)vsfilter do (default: basic). Historically, VSFilter
-    was not colorspace aware. This was no problem as long as the colorspace
-    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.
+    :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).
+    :yes:      Use precise seeks whenever possible.
 
-    :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 colorspaces
-            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 colorspace.
-    :no:    Disable color mangling completely. All colors are RGB.
+``--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.
 
-    Choosing anything other than ``no`` will make the subtitle color depend on
-    the video colorspace, and it's for example in theory not possible to reuse
-    a subtitle script with another video file. The ``--ass-style-override``
-    option doesn't affect how this option is interpreted.
+``--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.
 
-``--audio-channels=<number|layout>``
-    Request a channel layout for audio output (default: stereo). This  will ask
-    the AO to open a device with the given channel layout. It's up to the AO
-    to accept this layout, or to pick a fallback or to error out if the
-    requested layout is not supported.
+    Default: ``yes``
 
-    The ``--audio-channels`` option either takes a channel number or an explicit
-    channel layout. Channel numbers refer to default layouts, e.g. 2 channels
-    refer to stereo, 6 refers to 5.1.
+``--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.
 
-    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).
+    :default:   use an index if the file has one, or build it if missing
+    :recreate:  don't read or use the file's index
 
-    You can use ``--audio-channels=empty`` to disable this. In this case, the AO
-    use the channel layout as the audio filter chain indicates.
+    .. note::
 
-    This will also request the channel layout from the decoder. If the decoder
-    does not support the layout, it will fall back to its native channel layout.
-    (You can use ``--ad-lavc-downmix=no`` to make the decoder always output
-    its native layout.) Note that only some decoders support remixing audio.
-    Some that do include AC-3, AAC or DTS audio.
+        This option only works if the underlying media supports seeking
+        (i.e. not with stdin, pipe, etc).
 
-    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.
+``--load-unsafe-playlists``
+    Normally, something like ``mpv playlist.m3u`` won't load the playlist. This
+    is because the playlist code is unsafe. (This is the same in all other
+    variations of MPlayer.)
 
-``--audio-delay=<sec>``
-    Audio delay in seconds (positive or negative float value). Positive values
-    delay the audio, and negative values delay the video.
+    See ``--playlist`` for details.
 
-``--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``.
+    Note: this option will allow opening playlists using the ``playlist``
+    special demuxer. The ``--playlist`` uses different code, and supports more
+    playlist formats than the playlist demuxer. This means that for now, the
+    ``--playlist`` option should always be used if you intend to open playlists.
+    Background: the special demuxer contains newly written code, while the
+    ``--playlist`` option uses the old MPlayer code. Adding support for more
+    playlist formats to the special demuxer is work in progress, and eventually
+    the old code should disappear.
 
-``--audio-display=<no|attachment>``
-    Setting this option to ``attachment`` (default) will display image
-    attachments when playing audio files. It will display the first image
-    found, and additional images are available as video tracks.
+``--loop-file``
+    Loop a single file. The difference to ``--loop=inf`` 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.
 
-    Setting this option to ``no`` disables display of video entirely when
-    playing audio files.
+``--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.
 
-    This option has no influence on files with normal video tracks.
+``--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.
 
-``--audio-file=<filename>``
-    Play audio from an external file while viewing a video. Each use of this
-    option will add a new audio track. The details are similar to how
-    ``--sub-file`` works.
+    Useful for loading ordered chapter files that are not located on the local
+    filesystem, or if the referenced files are in different directories.
 
-``--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.
+    Note: a playlist can be as simple as a text file containing filenames
+    separated by newlines.
 
-``--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.
+``--sstep=<sec>``
+    Skip <sec> seconds after every frame.
 
-``--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.
+    .. note::
 
-    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.
+        Without ``--hr-seek``, skipping will snap to keyframes.
 
-    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.
+Program Behaviour
+-----------------
 
-    Use ``--autofit-larger`` instead if you just want to limit the maximum size
-    of the window, rather than always forcing a window size.
+``--help``
+    Show short summary of options.
 
-    Use ``--geometry`` if you want to force both window width and height to a
-    specific size.
+``-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 files. This prevents loading of
+    ``~/.config/mpv/mpv.conf`` and ``~/.config/mpv/input.conf``, as well as
+    loading the same files from system wide configuration directories. Other
+    configuration files are blocked as well, such as resume playback files.
 
     .. note::
 
-        Generally only supported by GUI VOs. Ignored for encoding.
+        Files explicitly requested by command line options, like
+        ``--include`` or ``--use-filedir-conf``, will still be loaded.
+
+    Also see ``--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.
+
+``--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 ``--no-config`` option takes precedence over this option.
+
+``--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.
+
+``--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``
+    Makes mpv wait idly instead of quitting when there is no file to play.
+    Mostly useful in slave mode, where mpv can be controlled through input
+    commands (see also ``--slave-broken``).
+
+``--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 ``~/.mpv/lua/``.
+    (Default: ``yes``)
+
+``--lua=<filename>``
+    Load a Lua script. You can load multiple scripts by separating them with
+    commas (``,``).
+
+``--lua-opts=key1=value1,key2=value2,...``
+    Set options for scripts. A Lua script can query an option by key. If an
+    option is used and what semantics the option value has depends entirely on
+    the loaded Lua scripts. Values not claimed by any scripts are ignored.
+
+``--merge-files``
+    Pretend that all files passed to mpv are concatenated into a single, big
+    file. This uses timeline/EDL support internally. Note that this won't work
+    for ordered chapter files or quvi-resolved URLs (such as youtube links).
+
+    This option is interpreted at program start, and doesn't affect for
+    example files or playlists loaded with the ``loadfile`` or ``loadlist``
+    commands.
+
+``--no-resume-playback``
+    Do not restore playback position from ``~/.mpv/watch_later/``.
+    See ``quit_watch_later`` input command.
+
+``--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.
+
+    In some cases, this might not work as expected. For example, ``--volume``
+    will only be reset if it is explicitly set in the config file or the
+    command line.
+
+    The special name ``all`` resets as many options as possible.
 
     .. 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%:60%``
-            Make the window as large as possible, without being wider than 70%
-            of the screen width, or higher than 60% of the screen height.
+        - ``--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.
 
-``--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.
+``--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.
 
-    .. admonition:: Example
+    .. warning::
 
-        ``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.
+        This option may expose privacy-sensitive information and is thus
+        disabled by default.
 
-``--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.
+``--show-profile=<profile>``
+    Show the description and content of a profile.
+
+``--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.
+
+
+Video
+-----
+
+``--vo=<driver1[:suboption1[=value]:...],driver2,...[,]>``
+    Specify a priority list of video output drivers to be used. For
+    interactive use, one would normally specify a single one to use, but in
+    configuration files, specifying a list of fallbacks may make sense. See
+    `VIDEO OUTPUT DRIVERS`_ for details and descriptions of available drivers.
+
+``--vd=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>``
+    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``, ``--vf-del`` and
+    ``--vf-clr`` exist to modify a previously specified list, but you
+    should not need these for typical use.
+
+``--no-video``
+    Do not play video. With some demuxers this may not work. In those cases
+    you can try ``--vo=null`` instead.
 
 ``--untimed``
     Do not sleep when outputting video frames. Useful for benchmarks when used
     with ``--no-audio.``
 
-``--bluray-angle=<ID>``
-    Some Blu-ray discs contain scenes that can be viewed from multiple angles.
-    This option tells mpv which angle to use (default: 1).
+``--framedrop=<no|yes|hard>``
+    Skip displaying some frames to maintain A/V sync on slow systems. Video
+    filters are not applied to such frames. For B-frames even decoding is
+    skipped completely. May produce unwatchably choppy output. With ``hard``,
+    decoding and output of any frame can be skipped, and will lead to an even
+    worse playback experience.
 
-``--bluray-device=<path>``
-    (Blu-ray only)
-    Specify the Blu-ray disc location. Must be a directory with Blu-ray
-    structure.
+    .. note::
 
-    .. admonition:: Example
+        Practical use of this feature is questionable. Disabled by default.
 
-        ``mpv bd:// --bluray-device=/path/to/bd/``
+``--hwdec=<api>``
+    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.
 
-``--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.
+    ``<api>`` can be one of the following:
 
-``--brightness=<-100-100>``
-    Adjust the brightness of the video signal (default: 0). Not supported by
-    all video output drivers.
+    :no:        always use software decoding (default)
+    :auto:      see below
+    :vdpau:     requires ``--vo=vdpau`` or ``--vo=opengl`` (Linux only)
+    :vaapi:     requires ``--vo=opengl`` or ``--vo=vaapi`` (Linux with Intel GPUs only)
+    :vaapi-copy: copies video back into system RAM (Linux with Intel GPUs only)
+    :vda:       requires ``--vo=opengl`` or ``--vo=corevideo`` (OSX only)
 
-``--cache=<kBytes|no|auto>``
-    Set the size of the cache in kilobytes, disable it with ``no``, or
-    automatically enable it if needed with ``auto`` (default: ``auto``).
-    With ``auto``, the cache will usually be enabled for network streams,
-    using the size set by ``--cache-default``.
+    ``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=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.
 
-    May be useful when playing files from slow media, but can also have
-    negative effects, especially with file formats that require a lot of
-    seeking, such as mp4.
+    The ``vaapi-copy`` function allows you to use vaapi with any VO. Because
+    this copies the decoded video back to system RAM, it's quite inefficient.
 
-    Note that half the cache size will be used to allow fast seeking back. This
-    is also the reason why a full cache is usually reported as 50% full. The
-    cache fill display does not include the part of the cache reserved for
-    seeking back. Likewise, when starting a file the cache will be at 100%,
-    because no space is reserved for seeking back yet.
+    .. note::
 
-``--cache-default=<kBytes|no>``
-    Set the size of the cache in kilobytes (default: 25000 KB). Using ``no``
-    will not automatically enable the cache e.g. when playing from a network
-    stream. Note that using ``--cache`` will always override this option.
+        When using this switch, hardware decoding is still only done for some
+        codecs. See ``--hwdec-codecs`` to enable hardware decoding for more
+        codecs.
 
-``--cache-pause-below=<kBytes|no>``
-    If the cache size goes below the specified value (in KB), pause and wait
-    until the size set by ``--cache-pause-restart`` is reached, then  resume
-    playback (default: 50). If ``no`` is specified, this behavior is disabled.
+``--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.
 
-    When the player is paused this way, the status line shows ``Buffering``
-    instead of ``Paused``, and the OSD uses a clock symbol instead of the
-    normal paused symbol.
+``--video-aspect=<ratio>``
+    Override video aspect ratio, in case aspect information is incorrect or
+    missing in the file being played. See also ``--no-video-aspect``.
 
-``--cache-pause-restart=<kBytes>``
-    If the cache is paused due to the ``--cache-pause-below`` functionality,
-    then the player unpauses as soon as the cache has this much data (in KB).
-    (Default: 100)
+    Two values have special meaning:
 
-``--cache-initial=<kBytes>``
-    Playback will start when the cache has been filled up with this many
-    kilobytes of data (default: 0).
+    :0:  disable aspect ratio handling, pretend the video has square pixels
+    :-1: use the video stream or container aspect (default)
 
-``--cache-seek-min=<kBytes>``
-    If a seek is to be made to a position within ``<kBytes>`` of the cache
-    size from the current position, mpv will wait for the cache to be
-    filled to this position rather than performing a stream seek (default:
-    500).
+    But note that handling of these special values might change in the future.
 
-    This matters for small forward seeks. With slow streams (especially http
-    streams) there is a tradeoff between skipping the data between current
-    position and seek destination, or performing an actual seek. Depending
-    on the situation, either of these might be slower than the other method.
-    This option allows control over this.
+    .. admonition:: Examples
 
-``--cache-file=<path>``
-    Create a cache file on the filesystem with the given name. The file is
-    always overwritten. When the general cache is enabled, this file cache
-    will be used to store whatever is read from the source stream.
+        - ``--video-aspect=4:3``  or ``--video-aspect=1.3333``
+        - ``--video-aspect=16:9`` or ``--video-aspect=1.7777``
+
+``--no-video-aspect``
+    Ignore aspect ratio information from video file and assume the video has
+    square pixels. See also ``--video-aspect``.
 
-    This will always overwrite the cache file, and you can't use an existing
-    cache file to resume playback of a stream. (Technically, mpv wouldn't
-    even know which blocks in the file are valid and which not.)
+``--video-unscaled``
+    Disable scaling of the video. If the window is larger than the video,
+    black bars are added. Otherwise, the video is cropped. The video still
+    can be influenced by the other ``--video-...`` options. (If the
+    ``--video-zoom`` option is set to a value other than ``1``, scaling is
+    enabled, but the video isn't automatically scaled to the window size.)
 
-    The resulting file will not necessarily contain all data of the source
-    stream. For example, if you seek, the parts that were skipped over are
-    never read and consequently are not written to the cache. The skipped over
-    parts are filled with zeros. This means that the cache file doesn't
-    necessarily correspond to a full download of the source stream.
+    The video and monitor aspects aspect will be ignored. Aspect correction
+    would require to scale the video in the X or Y direction, but this option
+    disables scaling, disabling all aspect correction.
 
-    Both of these issues could be improved if there is any user interest.
+    Note that the scaler algorithm may still be used, even if the video isn't
+    scaled. For example, this can influence chroma conversion.
 
-    Also see ``--cache-file-size``.
+    This option is disabled if the ``--no-keepaspect`` option is used.
 
-``--cache-file-size=<kBytes>``
-    Maximum size of the file created with ``--cache-file``. For read accesses
-    above this size, the cache is simply not 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).
 
-    (Default: 1048576, 1 GB.)
+    For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen
+    with ``--video-pan-x=-0.1`` would move the video 168 pixels to the left
+    (making 128 pixels of the source video invisible).
 
-``--cdda-...``
-    These options can be used to tune the CD Audio reading feature of mpv.
+    This option is disabled if the ``--no-keepaspect`` option is used.
 
-``--cdda-speed=<value>``
-    Set CD spin speed.
+``--video-rotate=<0-359|no>``
+    Rotate the video clockwise, in degrees. Currently supports 90° steps only.
+    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.)
 
-``--cdda-paranoia=<0-2>``
-    Set paranoia level. Values other than 0 seem to break playback of
-    anything but the first track.
+``--video-zoom=<value>``
+    Adjust the video display scale factor by the given value. The unit is in
+    fractions of the (scaled) window video size.
 
-    :0: disable checking (default)
-    :1: overlap checking only
-    :2: full data correction and verification
+    For example, given a 1280x720 video shown in a 1280x720 window,
+    ``--video-zoom=-0.1`` would make the video by 128 pixels smaller in
+    X direction, and 72 pixels in Y direction.
 
-``--cdda-sector-size=<value>``
-    Set atomic read size.
+    This option is disabled if the ``--no-keepaspect`` option is used.
 
-``--cdda-overlap=<value>``
-    Force minimum overlap search during verification to <value> sectors.
+``--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.
 
-``--cdda-toc-bias``
-    Assume that the beginning offset of track 1 as reported in the TOC
-    will be addressed as LBA 0. Some discs need this for getting track
-    boundaries correctly.
+    If video and screen aspect match perfectly, these options do nothing.
 
-``--cdda-toc-offset=<value>``
-    Add ``<value>`` sectors to the values reported when addressing tracks.
-    May be negative.
+    This option is disabled if the ``--no-keepaspect`` option is used.
 
-``--cdda-skip=<es|no``
-    (Never) accept imperfect data reconstruction.
+``--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 ``--fps``
+    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 and audio synchronization can be completely
+    broken in this mode.
 
-``--cdrom-device=<path>``
-    Specify the CD-ROM device (default: ``/dev/cdrom``).
+``--fps=<float>``
+    Override video framerate. Useful if the original value is wrong or missing.
 
-``--chapter=<start[-end]>``
-    Specify which chapter to start playing at. Optionally specify which
-    chapter to end playing at. Also see ``--start``.
+    .. note::
 
-``--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.
+        Works in ``--no-correct-pts`` mode only.
 
-``--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.
+``--deinterlace=<yes|no|auto>``
+    Enable or disable interlacing (default: auto, which usually means 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.
 
-``--colormatrix=<colorspace>``
-    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.
+    This behaves exactly like the ``deinterlace`` input property (usually
+    mapped to ``Shift+D``).
 
-    The color space conversion is additionally influenced by the related
-    options --colormatrix-input-range and --colormatrix-output-range.
+    ``auto`` is a technicality. Strictly speaking, the default for this option
+    is deinterlacing disabled, but the ``auto`` case is needed if ``yadif`` was
+    added to the filter chain manually with ``--vf``. Then the core shouldn't
+    disable deinterlacing just because the ``--deinterlace`` was not set.
 
-    These options are not always supported. Different video outputs provide
-    varying degrees of support. The ``opengl`` 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``).
+``--field-dominance=<auto|top|bottom>``
+    Set first field for interlaced content. Useful for deinterlacers that
+    double the framerate: ``--vf=yadif=field`` and ``--vo=vdpau:deint``.
 
-    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.
+    :auto:    (default) If the decoder does not export the appropriate
+              information, it falls back on ``top`` (top field first).
+    :top:     top field first
+    :bottom:  bottom field first
 
-    Available color spaces are:
+``--frames=<number>``
+    Play/convert only first ``<number>`` video frames, then quit.
 
-    :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
+    ``--frames=0`` loads the file, but immediately quits before initializing
+    playback. (Might be useful for scripts which just want to determine some
+    file properties.)
 
-``--colormatrix-input-range=<color-range>``
-    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.
+    For audio-only playback, any value greater than 0 will quit playback
+    immediately after initialization. The value 0 works as with video.
 
-    The same limitations as with --colormatrix apply.
+``--hwdec-codecs=<codec1,codec2,...|all>``
+    Allow hardware decoding for a given list of codecs only. The special value
+    ``all`` always allows all codecs.
 
-    Available color ranges are:
+    You can get the list of allowed codecs with ``mpv --vd=help``. Remove the
+    prefix, e.g. instead of ``lavc:h264`` use ``h264``.
 
-    :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)
+    By default this is set to ``h264,vc1,wmv3``. 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.
 
-``--colormatrix-output-range=<color-range>``
-    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 grey blacks and dim whites.
+    This is usually only needed with broken GPUs, where a codec is reported
+    as supported, but decoding causes more problems than it solves.
 
-    The same limitations as with ``--colormatrix`` apply.
+    .. admonition:: Example
 
-    Available color ranges are:
+        ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video``
+            Enable vdpau decoding for h264 and mpeg2 only.
 
-    :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
+``--quvi-format=<best|default|...>``
+    Video format/quality that is directly passed to libquvi (default: ``best``).
+    This is used when opening links to streaming sites like YouTube. The
+    interpretation of this value is highly specific to the streaming site and
+    the video.
 
-    .. note::
+    libquvi 0.4.x:
 
-        It is advisable to use your graphics driver's color range option
-        instead, if available.
+        The only well-defined values that work on all sites are ``best``
+        (best quality/highest bandwidth, default), and ``default`` (lowest
+        quality).
 
-``--colormatrix-primaries=<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. By default, when unset, BT.709 is used for
-    all files except those tagged with a BT.2020 color matrix.
+        The quvi command line tool can be used to find out which formats are
+        supported for a given URL: ``quvi --query-formats URL``.
 
-    This option only affects video output drivers that perform color
-    management, for example ``opengl`` with the ``srgb`` or ``icc-profile``
-    suboptions set.
+    libquvi 0.9.x:
 
-    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.
+        The following explanations are relevant:
+        `<http://quvi.sourceforge.net/r/api/0.9/glossary_termino.html#m_stream_id>`_
 
-    Available primaries are:
+    The ``quvi-format`` property can be used at runtime to cycle through the
+    list of formats. Unfortunately, this is slow. On libquvi 0.4.x, this
+    functionality is limited to switching between ``best`` and ``default`` if
+    the ``cycle`` input command is used.
 
-    :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)
+``--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.
 
-``--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.
+``--vd-lavc-bitexact``
+    Only use bit-exact algorithms in all decoding steps (for codec testing).
+
+``--vd-lavc-fast`` (MPEG-2, MPEG-4, 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.
 
-    Note that the ``--no-config`` option takes precedence over this option.
+``--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.
 
-``--contrast=<-100-100>``
-    Adjust the contrast of the video signal (default: 0). Not supported by all
-    video output drivers.
+    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``.
 
-``--cookies``, ``--no-cookies``
-    (network only)
-    Support cookies when making HTTP requests. Disabled by default.
+    .. admonition:: Example
 
-``--cookies-file=<filename>``
-    (network only)
-    Read HTTP cookies from <filename>. The file is assumed to be in Netscape
-    format.
+        ``--vd--lavc-o=debug=pict``
 
-``--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 ``--fps``
-    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 and audio synchronization can be completely
-    broken in this mode.
+``--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.
 
-``--cursor-autohide=<number|no|always>``
-    Make mouse cursor automatically hide after given number of milliseconds.
-    ``no`` will disable cursor autohide. ``always`` means the cursor will stay
-    hidden.
+``--vd-lavc-skiploopfilter=<skipvalue> (H.264 only)``
+    Skips the loop filter (AKA deblocking) during H.264 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.
 
-``--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``.
+    ``<skipvalue>`` can be one of the following:
 
-``--deinterlace=<yes|no|auto>``
-    Enable or disable interlacing (default: auto, which usually means 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.
+    :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.
 
-    This behaves exactly like the ``deinterlace`` input property (usually
-    mapped to ``Shift+D``).
+``--vd-lavc-skipidct=<skipvalue> (MPEG-1/2 only)``
+    Skips the IDCT step. This degrades quality a lot in almost all cases
+    (see skiploopfilter for available skip values).
 
-    ``auto`` is a technicality. Strictly speaking, the default for this option
-    is deinterlacing disabled, but the ``auto`` case is needed if ``yadif`` was
-    added to the filter chain manually with ``--vf``. Then the core shouldn't
-    disable deinterlacing just because the ``--deinterlace`` was not set.
+``--vd-lavc-skipframe=<skipvalue>``
+    Skips decoding of frames completely. Big speedup, but jerky motion and
+    sometimes bad artifacts (see skiploopfilter for available skip values).
 
-``--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``.
+``--vd-lavc-threads=<0-16>``
+    Number of threads to use for decoding. Whether threading is actually
+    supported depends on codec. 0 means autodetect number of cores on the
+    machine and use that, up to the maximum of 16 (default: 0).
 
-``--demuxer-lavf-analyzeduration=<value>``
-    Maximum length in seconds to analyze the stream properties.
 
-``--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.
+Audio
+-----
 
-    This is default in order to reduce latency when opening HTTP streams.
+``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>``
+    Specify a priority list of audio output drivers to be used. For
+    interactive use one would normally specify a single one to use, but in
+    configuration files specifying a list of fallbacks may make sense. See
+    `AUDIO OUTPUT DRIVERS`_ for details and descriptions of available drivers.
 
-``--demuxer-lavf-format=<name>``
-    Force a specific libavformat demuxer.
+``--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``, ``--af-del`` and
+    ``--af-clr`` exist to modify a previously specified list, but you
+    should not need these for typical use.
 
-``--demuxer-lavf-genpts-mode=<no|lavf>``
-    Mode for deriving missing packet PTS values from packet DTS. ``lavf``
-    enables libavformat's ``genpts`` option. ``no`` disables it. This used
-    to be enabled by default, but then it was deemed as not needed anymore.
-    Enabling this might help with timestamp problems, or make them worse.
+``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>``
+    Specify a priority list of audio decoders to be used, according to their
+    family and decoder name. Entries like ``family:*`` prioritize all decoders
+    of the given family. 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.
 
-``--demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]``
-    Pass AVOptions to libavformat demuxer.
+    ``-`` 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!
 
-    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.
+    ``-`` in front of an entry disables selection of the decoder.
 
-    .. admonition:: Example
+    .. admonition:: Examples
 
-        ``--demuxer-lavf-o=fflags=+ignidx``
+        ``--ad=lavc:mp3float``
+            Prefer the FFmpeg/Libav ``mp3float`` decoder over all other mp3
+            decoders.
 
-``--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.
+        ``--ad=spdif:ac3,lavc:*``
+            Always prefer spdif AC3 over FFmpeg/Libav over anything else.
 
-``--demuxer-lavf-buffers