Merge branch 'master' into release/current

7 files changed, 229 insertions, 60 deletions

diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst
index ec6ce3f6c3..be90f09b62 100644
--- a/DOCS/man/af.rst
+++ b/DOCS/man/af.rst
@@ -63,13 +63,9 @@ Available filters are:
         (If you just want to set defaults for this filter that will be used
         even by automatically inserted lavrresample instances, you should
         prefer setting them with ``--af-defaults=lavrresample:...``.)
-    ``normalize=<yes|no>``
-        Whether to normalize when remixing channel layouts (default: yes). This
-        is e.g. applied when downmixing surround audio to stereo. The advantage
-        is that this guarantees that no clipping can happen. Unfortunately,
-        this can also lead to too low volume levels. Whether you enable or
-        disable this is essentially a matter of taste, but the default uses
-        the safer choice.
+    ``normalize=<yes|no|auto>``
+        Whether to normalize when remixing channel layouts (default: auto).
+        ``auto`` uses the value set by ``--audio-normalize-downmix``.
     ``o=<string>``
         Set AVOptions on the SwrContext or AVAudioResampleContext. These should
         be documented by FFmpeg or Libav.
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index ed523b2135..11a8f0021f 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -694,6 +694,18 @@ Input Commands that are Possibly Subject to Change
     field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image
     is freed as soon as the result node is freed.
 
+``vf-command "<label>" "<cmd>" "<args>"``
+    Send a command to the filter with the given ``<label>``. Use ``all`` to send
+    it to all filters at once. The command and argument string is filter
+    specific. Currently, this only works with the ``lavfi`` filter - see
+    the libavfilter documentation for which commands a filter supports.
+
+    Note that the ``<label>`` is a mpv filter label, not a libavfilter filter
+    name.
+
+``af-command "<label>" "<cmd>" "<args>"``
+    Same as ``vf-command``, but for audio filters.
+
 Undocumented commands: ``tv-last-channel`` (TV/DVB only),
 ``ao-reload`` (experimental/internal).
 
@@ -753,6 +765,17 @@ The following hooks are currently defined:
     ``file-local-options/<option name>``. The player will wait until all
     hooks are run.
 
+``on_preloaded``
+    Called after a file has been opened, and before tracks are selected and
+    decoders are created. This has some usefulness if an API users wants
+    to select tracks manually, based on the set of available tracks. It's
+    also useful to initialize ``--lavfi-complex`` in a specific way by API,
+    without having to "probe" the available streams at first.
+
+    Note that this does not yet apply default track selection. Which operations
+    exactly can be done and not be done, and what information is available and
+    what is not yet available yet, is all subject to change.
+
 ``on_unload``
     Run before closing a file, and before actually uninitializing
     everything. It's not possible to resume playback in this state.
@@ -1212,11 +1235,30 @@ Property list
 ``hr-seek`` (RW)
     See ``--hr-seek``.
 
+``mixer-active``
+    Return ``yes`` if the audio mixer is active, ``no`` otherwise. This has
+    implications for ``--softvol=no`` mode: if the mixer is active, changing
+    ``volume`` doesn't actually change anything on the system mixer. If the
+    ``--volume`` or ``--mute`` option are used, these might not be applied
+    property until the mixer becomes active either. (The options, if set, will
+    just overwrite the mixer state at audio initialization.)
+
+    While the behavior with ``mixer-active==yes`` is relatively well-defined,
+    the ``no`` case will provide possibly wrong or insignificant values.
+
+    Note that an active mixer does not necessarily imply active audio output,
+    although this is implied in the current implementation.
+
 ``volume`` (RW)
-    Current volume (see ``--volume`` for details).
+    Current volume (see ``--volume`` for details). Also see ``mixer-active``
+    property.
+
+``volume-max``
+    Current maximum value the volume property can be set to. (This may depend
+    on the ``--softvol-max`` option.)
 
 ``mute`` (RW)
-    Current mute status (``yes``/``no``).
+    Current mute status (``yes``/``no``). Also see ``mixer-active`` property.
 
 ``audio-delay`` (RW)
     See ``--audio-delay``.
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 84c5247d2f..6716c382f2 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -37,6 +37,10 @@ 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`` for
+a list of default bindings. User ``input.conf`` files and Lua scripts can
+define additional key bindings.
+
 Keyboard Control
 ----------------
 
@@ -381,6 +385,45 @@ 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.
 
+
+Playing DVDs
+------------
+
+DVDs can be played with the ``dvd://[title]`` syntax. The optional
+title specifier is a number which selects between separate video
+streams on the DVD. If no title is given (``dvd://``) then the longest
+title is selected automatically by the library. This is usually what
+you want. mpv does not support DVD menus.
+
+DVDs which have been copied on to a hard drive or other mounted
+filesystem (by e.g. the ``dvdbackup`` tool) are accommodated by
+specifying the path to the local copy: ``--dvd-device=PATH``.
+Alternatively, running ``mpv PATH`` should auto-detect a DVD directory
+tree and play the longest title.
+
+.. note::
+
+    mpv uses a different default DVD library than MPlayer. MPlayer
+    uses libdvdread by default, and mpv uses libdvdnav by default.
+    Both libraries are developed in parallel, but libdvdnav is
+    intended to support more sophisticated DVD features such as menus
+    and multi-angle playback. mpv uses libdvdnav for files specified
+    as either ``dvd://...`` or ``dvdnav://...``. To use libdvdread,
+    which will produce behavior more like MPlayer, specify
+    ``dvdread://...`` instead. Some users have experienced problems
+    when using libdvdnav, in which playback gets stuck in a DVD menu
+    stream. These problems are reported to go away when auto-selecting
+    the title (``dvd://`` rather than ``dvd://1``) or when using
+    libdvdread (e.g. ``dvdread://0``).
+
+    DVDs use image-based subtitles. Image subtitles are implemented as
+    a bitmap video stream which can be superimposed over the main
+    movie. mpv's subtitle styling and positioning options and keyboard
+    shortcuts generally do not work with image-based subtitles.
+    Exceptions include options like ``--stretch-dvd-subs`` and 
+    ``--stretch-image-subs-to-screen``.
+
+
 CONFIGURATION FILES
 ===================
 
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index e5fe542712..ec71dd762b 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -394,8 +394,7 @@ Program Behavior
 
 ``--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.
+    file. This uses timeline/EDL support internally.
 
 ``--no-resume-playback``
     Do not restore playback position from the ``watch_later`` configuration
@@ -539,7 +538,7 @@ Video
         filters all frames, but doesn't render them on the VO. It tries to query
         the display FPS (X11 only, not correct on multi-monitor systems), or
         assumes infinite display FPS if that fails. Drops are indicated in
-        the terminal status line as ``D:`` field. If the decoder is too slow,
+        the terminal status line as ``Dropped:`` field. If the decoder is too slow,
         in theory all frames would have to be dropped (because all frames are
         too late) - to avoid this, frame dropping stops if the effective
         framerate is below 10 FPS.
@@ -560,9 +559,13 @@ Video
 
 ``--display-fps=<fps>``
     Set the display FPS used with the ``--video-sync=display-*`` modes. By
-    default, a detected value is used (X11 only, not correct on multi-monitor
-    systems). Keep in mind that setting an incorrect value (even if slightly
-    incorrect) can ruin video playback.
+    default, a detected value is used. Keep in mind that setting an incorrect
+    value (even if slightly incorrect) can ruin video playback. On multi-monitor
+    systems, there is a chance that the detected value is from the wrong
+    monitor.
+
+    Set this option only if you have reason to believe the automatically
+    determined value is wrong.
 
 ``--hwdec=<api>``
     Specify the hardware video decoding API that should be used if possible.
@@ -975,7 +978,7 @@ Audio
 
         There is not much reason to use this. HDMI supports uncompressed
         multichannel PCM, and mpv supports lossless DTS-HD decoding via
-        FFmpeg's libdcadec wrapper.
+        FFmpeg's new DCA decoder (based on libdcadec).
 
 ``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>``
     Specify a priority list of audio decoders to be used, according to their
@@ -1089,8 +1092,8 @@ Audio
         This and enabling passthrough via ``--ad`` are deprecated in favor of
         using ``--audio-spdif=dts-hd``.
 
-``--audio-channels=<number|layout>``
-    Request a channel layout for audio output (default: auto). This  will ask
+``--audio-channels=<auto|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.
@@ -1103,9 +1106,10 @@ Audio
     lists speaker names, which can be used to express arbitrary channel
     layouts (e.g. ``fl-fr-lfe`` is 2.1).
 
-    The default is ``--audio-channels=auto``, which tries to play audio using
-    the input file's channel layout. (Or more precisely, the output of the
-    audio filter chain.) (``empty`` is an accepted obsolete alias for ``auto``.)
+    ``--audio-channels=auto`` tries to play audio using the input file's
+    channel layout. There is no guarantee that the audio API handles this
+    correctly. See the HDMI warning below.
+    (``empty`` is an accepted obsolete alias for ``auto``.)
 
     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.
@@ -1124,6 +1128,16 @@ Audio
         channel layout, random things can happen, such as dropping the
         additional channels, or adding noise.
 
+``--audio-normalize-downmix=<yes|no>``
+    Enable/disable normalization if surround audio is downmixed to stereo
+    (default: no). If this is disabled, downmix can cause clipping. If it's
+    enabled, the output might be too silent. It depends on the source audio.
+
+    Technically, this changes the ``normalize`` suboption of the
+    ``lavrresample`` audio filter, which performs the downmixing.
+
+    If downmix happens outside of mpv for some reason, this has no effect.
+
 ``--audio-display=<no|attachment>``
     Setting this option to ``attachment`` (default) will display image
     attachments (e.g. album cover art) when playing audio files. It will
@@ -1381,7 +1395,7 @@ Subtitles
     .. admonition:: Warning
 
         Enabling hinting can lead to mispositioned text (in situations it's
-        supposed to match up with video background), or reduce the smoothness
+        supposed to match up video background), or reduce the smoothness
         of animations with some badly authored ASS scripts. It is recommended
         to not use this option, unless really needed.
 
@@ -3538,3 +3552,58 @@ Miscellaneous
     Force the contents of the ``media-title`` property to this value. Useful
     for scripts which want to set a title, without overriding the user's
     setting in ``--title``.
+
+``--external-file=<filename>``
+    Add all tracks from the given file. Unlike ``--sub-file`` and
+    ``--audio-file``, this includes all tracks, and does not cause default
+    stream selection over the "proper" file.
+
+``--lavfi-complex=<string>``
+    Set a "complex" libavfilter filter, which means a single filter graph can
+    take input from multiple source audio and video tracks. The graph can result
+    in a single audio or video output (or both).
+
+    Currently, the filter graph labels are used to select the participating
+    input tracks and audio/video output. The following rules apply:
+
+    - A label of the form ``aidN`` selects audio track N as input (e.g.
+      ``aid1``).
+    - A label of the form ``vidN`` selects video track N as input.
+    - A label named ``ao`` will be connected to the audio input.
+    - A label named ``vo`` will be connected to the video output.
+
+    Each label can be used only once. If you want to use e.g. an audio stream
+    for multiple filters, you need to use the ``asplit`` filter. Multiple
+    video or audio outputs are not possible, but you can use filters to merge
+    them into one.
+
+    The complex filter can not be changed yet during playback. It's also not
+    possible to change the tracks connected to the filter at runtime. Other
+    tracks, as long as they're not connected to the filter, and the
+    corresponding output is not connected to the filter, can still be freely
+    changed.
+
+    Note that the normal filter chains (``--af``, ``--vf``) are applied between
+    the complex graphs (e.g. ``ao`` label) and the actual output.
+
+    .. admonition:: Examples
+
+        - ``--lavfi-complex='[aid1] asplit [ao] [t] ; [t] aphasemeter [vo]'``
+          Play audio track 1, and visualize it as video using the ``aphasemeter``
+          filter.
+        - ``--lavfi-complex='[aid1] [aid2] amix [ao]'``
+          Play audio track 1 and 2 at the same time.
+        - ``--lavfi-complex='[vid1] [vid2] vstack [vo]'``
+          Stack video track 1 and 2 and play them at the same time. Note that
+          both tracks need to have the same width, or filter initialization
+          will fail (you can add ``scale`` filters before the ``vstack`` filter
+          to fix the size).
+        - ``--lavfi-complex='[aid1] asplit [ao] [t] ; [t] aphasemeter [t2] ; [vid1] [t2] overlay [vo]'``
+          Play audio track 1, and overlay its visualization over video track 1.
+        - ``--lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]'``
+          Play audio track 1, and overlay the measured volume for each speaker
+          over video track 1.
+
+    See the FFmpeg libavfilter documentation for details on the filter.
+
+
diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst
index f4f8d66496..587b8104d2 100644
--- a/DOCS/man/osc.rst
+++ b/DOCS/man/osc.rst
@@ -130,7 +130,7 @@ these keys. In case of collision, the function needs to be bound to a
 different key. See the `Script Commands`_ section.
 
 =============   ================================================
-del             Hide the OSC permanently until mpv is restarted.
+del             Cycles visibility between never / auto (mouse-move) / always
 =============   ================================================
 
 Configuration
@@ -206,8 +206,8 @@ Configurable Options
 
 ``hidetimeout``
     | Default: 500
-    | Duration in ms until the OSC hides if no mouse movement, negative value
-      disables auto-hide
+    | Duration in ms until the OSC hides if no mouse movement, must not be
+      negative
 
 ``fadeduration``
     | Default: 200
@@ -243,28 +243,29 @@ Configurable Options
     | Default: no
     | Display timecodes with milliseconds
 
+``visibility``
+    | Default: auto (auto hide/show on mouse move)
+    | Also supports ``never`` and ``always``
+
 Script Commands
 ~~~~~~~~~~~~~~~
 
 The OSC script listens to certain script commands. These commands can bound
 in ``input.conf``, or sent by other scripts.
 
-``enable-osc``
-    Undoes ``disable-osc`` or the effect of the ``del`` key.
-
-``disable-osc``
-    Hide the OSC permanently. This is also what the ``del`` key does.
-
 ``osc-message``
     Show a message on screen using the OSC. First argument is the message,
     second the duration in seconds.
 
+``osc-visibility``
+    Controls visibility mode ``never`` / ``auto`` (on mouse move) / ``always``
+    and also ``cycle`` to cycle between the modes
 
 Example
 
 You could put this into ``input.conf`` to hide the OSC with the ``a`` key and
-to unhide it with ``b``::
+to set auto mode (the default) with ``b``::
 
-    a script_message disable-osc
-    b script_message enable-osc
+    a script_message osc-visibility never
+    b script_message osc-visibility auto
 
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index ff3f539416..faca4114a9 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -289,27 +289,27 @@ Available filters are:
         :prophoto:     ProPhoto RGB (ROMM)
         :cie1931:      CIE 1931 RGB
 
-     ``<gamma>``
-        Gamma function the source file was encoded with. Normally this should be set
-        in the file header, but when playing broken or mistagged files this can be
-        used to override the setting.
-
-        This option only affects video output drivers that perform color management.
-
-        If this option is set to ``auto`` (which is the default), the gamma will
-        be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for
-        XYZ content.
-
-        Available gamma functions are:
-
-        :auto:         automatic selection (default)
-        :bt.1886:      ITU-R BT.1886 (approximation of BT.601/BT.709/BT.2020 curve)
-        :srgb:         IEC 61966-2-4 (sRGB)
-        :linear:       Linear light
-        :gamma1.8:     Pure power curve (gamma 1.8)
-        :gamma2.2:     Pure power curve (gamma 2.2)
-        :gamma2.8:     Pure power curve (gamma 2.8)
-        :prophoto:     ProPhoto RGB (ROMM) curve
+    ``<gamma>``
+       Gamma function the source file was encoded with. Normally this should be set
+       in the file header, but when playing broken or mistagged files this can be
+       used to override the setting.
+
+       This option only affects video output drivers that perform color management.
+
+       If this option is set to ``auto`` (which is the default), the gamma will
+       be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for
+       XYZ content.
+
+       Available gamma functions are:
+
+       :auto:         automatic selection (default)
+       :bt.1886:      ITU-R BT.1886 (approximation of BT.601/BT.709/BT.2020 curve)
+       :srgb:         IEC 61966-2-4 (sRGB)
+       :linear:       Linear light
+       :gamma1.8:     Pure power curve (gamma 1.8)
+       :gamma2.2:     Pure power curve (gamma 2.2)
+       :gamma2.8:     Pure power curve (gamma 2.8)
+       :prophoto:     ProPhoto RGB (ROMM) curve
 
     ``<stereo-in>``
         Set the stereo mode the video is assumed to be encoded in. Takes the
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index bc0dd9fd12..58bd91cd55 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -444,7 +444,7 @@ Available video output drivers are:
         Disable the scaler if the video image is not resized. In that case,
         ``bilinear`` is used instead whatever is set with ``scale``. Bilinear
         will reproduce the source image perfectly if no scaling is performed.
-        Note that this option never affects ``cscale``.
+        Enabled by default. Note that this option never affects ``cscale``.
 
     ``pbo``
         Enable use of PBOs. On some drivers this can be faster, especially if
@@ -549,6 +549,20 @@ Available video output drivers are:
         manifest themselves as short flashes or fringes of black, mostly
         around moving edges) in exchange for potentially adding more blur.
 
+    ``interpolation-threshold=<0..1,-1>``
+        Threshold below which frame ratio interpolation gets disabled (default:
+        ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``,
+        where ``vfps`` is the speed-adjusted display FPS, and ``disphz`` the
+        display refresh rate.
+
+        The default is intended to almost always enable interpolation if the
+        playback rate is even slightly different from the display refresh rate.
+        But note that if you use e.g. ``--video-sync=display-vdrop``, small
+        deviations in the rate can disable interpolation and introduce a
+        discontinuity every other minute.
+
+        Set this to ``-1`` to disable this logic.
+
     ``dscale-radius``, ``cscale-radius``, ``tscale-radius``, etc.
         Set filter parameters for ``dscale``, ``cscale`` and ``tscale``,
         respectively.
@@ -657,7 +671,11 @@ Available video output drivers are:
 
         These files must define a function with the following signature::
 
-            vec4 sample(sampler2D tex, vec2 pos, vec2 tex_size)
+            vec4 sample_pixel(sampler2D tex, vec2 pos, vec2 tex_size)
+
+        (If there is no string ``sample_pixel`` in the shader script, it will
+        use ``sample`` instead. This is a compatibility hack for older shader
+        scripts, and is deprecated.)
 
         The meanings of the parameters are as follows:
 
@@ -796,7 +814,7 @@ Available video output drivers are:
         angle
             Direct3D11 through the OpenGL ES translation layer ANGLE. This
             supports almost everything the ``win`` backend does, except ICC
-            profiles, high bit depth video input, and the ``nnedi3`` prescaler.
+            profiles, and the ``nnedi3`` prescaler.
         dxinterop (experimental)
             Win32, using WGL for rendering and Direct3D 9Ex for presentation.
             Works on Nvidia and AMD only.
@@ -824,8 +842,8 @@ Available video output drivers are:
         influence performance and quality of the video output.
         ``fmt`` can be one of: rgb, rgba, rgb8, rgb10, rgb10_a2, rgb16, rgb16f,
         rgb32f, rgba12, rgba16, rgba16f, rgba32f.
-        Default: ``auto``, which maps to rgba16 on desktop GL, and rgb10_a2 on
-        GLES (e.g. ANGLE).
+        Default: ``auto``, which maps to rgba16 on desktop GL, and rgba16f or
+        rgb10_a2 on GLES (e.g. ANGLE).
 
     ``gamma=<0.1..2.0>``
         Set a gamma value (default: 1.0). If gamma is adjusted in other ways