Merge branch 'master' into release/current

9 files changed, 166 insertions, 123 deletions

diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index a35b9c1c4e..8bddc98a42 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -20,10 +20,8 @@ normal driver parameters.
 
     See ``--ao=help`` for a list of compiled-in audio output drivers. The
     driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems
-    where PulseAudio is used. On Windows, ``--ao=wasapi`` is preferred,
-    though it might cause trouble sometimes, in which case ``--ao=dsound``
-    should be used. On BSD systems, ``--ao=oss`` or `--ao=sndio`` may work
-    (the latter being experimental). On OS X systems, use ``--ao=coreaudio``.
+    where PulseAudio is used. On BSD systems, ``--ao=oss`` or ``--ao=sndio``
+    may work (the latter being experimental).
 
 .. admonition:: Examples
 
@@ -165,7 +163,7 @@ Available audio output drivers are:
         will actually work. The disadvantage is that it will change the
         system-wide audio settings. This is equivalent to changing the ``Format``
         setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup``
-        utility. Note that this does not effect the selected speaker setup.
+        utility. Note that this does not affect the selected speaker setup.
 
     ``exclusive``
         Use exclusive mode access. This merely redirects to
@@ -205,19 +203,7 @@ Available audio output drivers are:
         (it used to be required to get good behavior on old PulseAudio versions).
 
         If you have stuttering video when using pulse, try to enable this
-        option. (Or alternatively, try to update PulseAudio.)
-
-``dsound`` (Windows only)
-    DirectX DirectSound audio output driver
-
-    .. note:: This driver is for compatibility with old systems.
-
-    ``device=<devicenum>``
-        Sets the device number to use. Playing a file with ``-v`` will show a
-        list of available devices.
-
-    ``buffersize=<ms>``
-        DirectSound buffer size in milliseconds (default: 200).
+        option. (Or try to update PulseAudio.)
 
 ``sdl``
     SDL 1.2+ audio output driver. Should work on any platform supported by SDL
@@ -256,7 +242,7 @@ Available audio output drivers are:
     ``speed``
         Simulated audio playback speed as a multiplier. Usually, a real audio
         device will not go exactly as fast as the system clock. It will deviate
-        just a little, and this option helps simulating this.
+        just a little, and this option helps to simulate this.
 
     ``latency``
         Simulated device latency. This is additional to EOF.
@@ -325,7 +311,7 @@ Available audio output drivers are:
         String are valid; the GUID string is guaranteed to not change
         unless the driver is uninstalled.
 
-        Also supports searching active devices by human readable name. If more
+        Also supports searching active devices by human-readable name. If more
         than one device matches the name, refuses loading it.
 
         This option is mostly deprecated in favour of the more general
diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst
index b3a212368a..794b8a1df2 100644
--- a/DOCS/man/encode.rst
+++ b/DOCS/man/encode.rst
@@ -93,8 +93,8 @@ You can encode files from one format/codec to another using this facility.
         Completely empties the options list.
 
 ``--oafirst``
-    Force the audio stream to become the first stream in the output. By default
-    the order is unspecified.
+    Force the audio stream to become the first stream in the output.
+    By default, the order is unspecified.
 
 ``--ovc=<codec>``
     Specifies the output video codec. This can be a comma separated list of
@@ -134,8 +134,8 @@ You can encode files from one format/codec to another using this facility.
         Completely empties the options list.
 
 ``--ovfirst``
-    Force the video stream to become the first stream in the output. By default
-    the order is unspecified.
+    Force the video stream to become the first stream in the output.
+    By default, the order is unspecified.
 
 ``--ocopyts``
     Copies input pts to the output video (not supported by some output
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index c3e69b3731..ed523b2135 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -418,7 +418,7 @@ List of Input Commands
 
     <reselect> (default)
         Select the default audio and subtitle streams, which typically selects
-        external files with highest preference. (The implementation is not
+        external files with the highest preference. (The implementation is not
         perfect, and could be improved on request.)
 
     <keep-selection>
@@ -546,6 +546,12 @@ Input Commands that are Possibly Subject to Change
         Always bind a key. (The input section that was made active most recently
         wins if there are ambiguities.)
 
+    This command can be used to dispatch arbitrary keys to a script or a client
+    API user. If the input section defines ``script-binding`` commands, it is
+    also possible to get separate events on key up/down, and relatively detailed
+    information about the key state. The special key name ``unmapped`` can be
+    used to match any unmapped key.
+
 ``overlay-add <id> <x> <y> "<file>" <offset> "<fmt>" <w> <h> <stride>``
     Add an OSD overlay sourced from raw data. This might be useful for scripts
     and applications controlling mpv, and which want to display things on top
@@ -647,14 +653,20 @@ Input Commands that are Possibly Subject to Change
     For completeness, here is how this command works internally. The details
     could change any time. On any matching key event, ``script_message_to``
     or ``script_message`` is called (depending on whether the script name is
-    included), where the first argument is the string ``key-binding``, the
-    second argument is the name of the binding, and the third argument is the
-    key state as string. The key state consists of a number of letters. The
-    first letter is one of ``d`` (key was pressed down), ``u`` (was released),
-    ``r`` (key is still down, and was repeated; only if key repeat is enabled
-    for this binding), ``p`` (key was pressed; happens if up/down can't be
-    tracked). The second letter whether the event originates from the mouse,
-    either ``m`` (mouse button) or ``-`` (something else).
+    included), with the following arguments:
+
+    1. The string ``key-binding``.
+    2. The name of the binding (as established above).
+    3. The key state as string (see below).
+    4. The key name (since mpv 0.15.0).
+
+    The key state consists of 2 letters:
+
+    1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key
+       is still down, and was repeated; only if key repeat is enabled for this
+       binding), ``p`` (key was pressed; happens if up/down can't be tracked).
+    2. Whether the event originates from the mouse, either ``m`` (mouse button)
+       or ``-`` (something else).
 
 ``ab-loop``
     Cycle through A-B loop states. The first command will set the ``A`` point
@@ -782,7 +794,7 @@ Input sections group a set of bindings, and enable or disable them at once.
 In ``input.conf``, each key binding is assigned to an input section, rather
 than actually having explicit text sections.
 
-Also see ``enable_section`` and ``disable_section`` commands.
+See also: ``enable_section`` and ``disable_section`` commands.
 
 Predefined bindings:
 
@@ -961,9 +973,8 @@ Property list
 ``playback-time`` (RW)
     Position in current file in seconds. Unlike ``time-pos``, the time is
     clamped to the range of the file. (Inaccurate file durations etc. could
-    make it go out of range. Also helpful when the user attempts to seek
-    outside of the file, as the seek target time is considered the current
-    position during seeking.)
+    make it go out of range. Useful on attempts to seek outside of the file,
+    as the seek target time is considered the current position during seeking.)
 
 ``chapter`` (RW)
     Current chapter number. The number of the first chapter is 0.
@@ -1109,13 +1120,13 @@ Property list
 
 ``vf-metadata/<filter-label>``
     Metadata added by video filters. Accessed by the filter label,
-    which if not explicitly specified using the ``@filter-label:`` syntax,
+    which, if not explicitly specified using the ``@filter-label:`` syntax,
     will be ``<filter-name>NN``.
 
     Works similar to ``metadata`` property. It allows the same access
     methods (using sub-properties).
 
-    An example of these kind of metadata are the cropping parameters
+    An example of this kind of metadata are the cropping parameters
     added by ``--vf=lavfi=cropdetect``.
 
 ``af-metadata/<filter-label>``
@@ -1142,7 +1153,7 @@ Property list
 
 ``cache-size`` (RW)
     Network cache size in KB. This is similar to ``--cache``. This allows
-    to set the cache size at runtime. Currently, it's not possible to enable
+    setting the cache size at runtime. Currently, it's not possible to enable
     or disable the cache at runtime using this property, just to resize an
     existing cache.
 
@@ -1531,6 +1542,15 @@ Property list
 ``program`` (W)
     Switch TS program (write-only).
 
+``dvb-channel`` (W)
+    Pair of integers: card,channel of current DVB stream.
+    Can be switched to switch to another channel on the same card. 
+
+``dvb-channel-name`` (RW)
+    Name of current DVB program.
+    On write, a channel-switch to the named channel on the same
+    card is performed. Can also be used for channel switching. 
+
 ``sid`` (RW)
     Current subtitle track (similar to ``--sid``).
 
diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst
index 31333a2c6a..e3ff1bd243 100644
--- a/DOCS/man/ipc.rst
+++ b/DOCS/man/ipc.rst
@@ -111,7 +111,7 @@ rely on this.
 Commands
 --------
 
-Additionally to  the commands described in `List of Input Commands`_, a few
+In addition to the commands described in `List of Input Commands`_, a few
 extra commands can also be used as part of the protocol:
 
 ``client_name``
@@ -189,7 +189,7 @@ extra commands can also be used as part of the protocol:
 
 ``unobserve_property``
     Undo ``observe_property`` or ``observe_property_string``. This requires the
-    numeric id passed to the observe command as argument.
+    numeric id passed to the observed command as argument.
 
     Example:
 
@@ -228,7 +228,9 @@ extra commands can also be used as part of the protocol:
 
 ``get_version``
     Returns the client API version the C API of the remote mpv instance
-    provides. (Also see ``DOCS/client-api-changes.rst``.)
+    provides.
+
+    See also: ``DOCS/client-api-changes.rst``.
 
 UTF-8
 -----
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index d51a6d95c5..4d47774319 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -198,7 +198,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     be called (unless the user remapped the key with another binding).
 
     The ``name`` argument should be a short symbolic string. It allows the user
-    to remap the key binding via input.conf using the ``script_message``
+    to remap the key binding via input.conf using the ``script-message``
     command, and the name of the key binding (see below for
     an example). The name should be unique across other bindings in the same
     script - if not, the previous binding with the same name will be
@@ -220,8 +220,8 @@ The ``mp`` module is preloaded, although it can be loaded manually with
             has an ``is_mouse`` entry, which tells whether the event was caused
             by a mouse button.
 
-    Internally, key bindings are dispatched via the ``script_message_to`` or
-    ``script_binding`` input commands and ``mp.register_script_message``.
+    Internally, key bindings are dispatched via the ``script-message-to`` or
+    ``script-binding`` input commands and ``mp.register_script_message``.
 
     Trying to map multiple commands to a key will essentially prefer a random
     binding, while the other bindings are not called. It is guaranteed that
@@ -244,7 +244,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
     ::
 
-        y script_binding something
+        y script-binding something
 
 
     This will print the message when the key ``y`` is pressed. (``x`` will
@@ -255,7 +255,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
     ::
 
-        y script_binding fooscript.something
+        y script-binding fooscript.something
 
 ``mp.add_forced_key_binding(...)``
     This works almost the same as ``mp.add_key_binding``, but registers the
@@ -389,7 +389,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 ``mp.get_script_name()``
     Return the name of the current script. The name is usually made of the
     filename of the script, with directory and file extension removed. If
-    there are several script which would have the same name, it's made unique
+    there are several scripts which would have the same name, it's made unique
     by appending a number.
 
     .. admonition:: Example
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 9527b8a3c9..84c5247d2f 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -50,7 +50,7 @@ UP and DOWN
 
 Ctrl+LEFT and Ctrl+RIGHT
     Seek to the previous/next subtitle. Subject to some restrictions and
-    might not work always; see ``sub_seek`` command.
+    might not always work; see ``sub_seek`` command.
 
 [ and ]
     Decrease/increase current playback speed by 10%.
@@ -222,7 +222,10 @@ PREVIOUS and NEXT
 support.)
 
 h and k
-    Select previous/next channel.
+    Select previous/next tv-channel.
+
+H and K
+    Select previous/next dvb-channel.
 
 Mouse Control
 -------------
@@ -520,8 +523,9 @@ 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
-``shotNNNN.jpg`` will be saved in the working directory, using the first
-available number - no files will be overwritten.
+``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
@@ -571,7 +575,7 @@ listed.
   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. Also can be incremented on "hiccups" and when the video
+  rendering is too slow. May also be incremented on "hiccups" and when the video
   frame couldn't be displayed on time. (``vo-drop-frame-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
@@ -602,7 +606,7 @@ PROTOCOLS
     Play a path from  Samba share.
 
 ``bd://[title][/device]`` ``--bluray-device=PATH``
-    Play a Blu-Ray disc. Currently, this does not accept ISO files. Instead,
+    Play a Blu-ray disc. Currently, this does not accept ISO files. Instead,
     you must mount the ISO file as filesystem, and point ``--bluray-device``
     to the mounted directory directly.
 
@@ -654,9 +658,8 @@ PROTOCOLS
     absolute path.
 
 ``fd://123``
-    Read data from the given UNIX FD (for example 123). This is similar to
-    piping data to stdin via ``-``, but can use an arbitrary file descriptor.
-    Will not work correctly on MS Windows.
+    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.
 
 ``edl://[edl specification as in edl-mpv.rst]``
     Stitch together parts of multiple files and play them.
@@ -728,7 +731,7 @@ EMBEDDING INTO OTHER PROGRAMS (LIBMPV)
 ======================================
 
 mpv can be embedded into other programs as video/audio playback backend. The
-recommended way to to so is using libmpv. See ``libmpv/client.h`` in the mpv
+recommended way to do so is using libmpv. See ``libmpv/client.h`` in the mpv
 source code repository. This provides a C API. Bindings for other languages
 might be available (see wiki).
 
@@ -803,7 +806,7 @@ libdvdcss:
 
         key
            is the default method. libdvdcss will use a set of calculated
-           player keys to try and get the disc key. This can fail if the drive
+           player keys to try to get the disc key. This can fail if the drive
            does not recognize any of the player keys.
 
         disc
@@ -919,7 +922,7 @@ 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\Application Data\mpv\mpv.conf``
+    ``C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf``
 
 You can find the exact path by running ``echo %APPDATA%\mpv\mpv.conf`` in cmd.exe.
 
@@ -942,8 +945,8 @@ 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 lowest priority is the directory named ``mpv``
-in the same directory as ``mpv.exe``. This used to be the directory with
+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.
 
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 14a0a7bec9..e5fe542712 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -136,7 +136,9 @@ Playback Control
 
 ``--chapter=<start[-end]>``
     Specify which chapter to start playing at. Optionally specify which
-    chapter to end playing at. Also see ``--start``.
+    chapter to end playing at.
+
+    See also: ``--start``.
 
 ``--playlist-pos=<no|index>``
     Set which file on the internal playlist to start playback with. The index
@@ -321,7 +323,7 @@ Program Behavior
         Files explicitly requested by command line options, like
         ``--include`` or ``--use-filedir-conf``, will still be loaded.
 
-    Also see ``--config-dir``.
+    See also: ``--config-dir``.
 
 ``--list-options``
     Prints all available options.
@@ -558,7 +560,7 @@ 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
+    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.
 
@@ -613,7 +615,7 @@ Video
 
     For ``opengl-cb``, if set, load the interop context as soon as the OpenGL
     context is created. Since ``opengl-cb`` has no on-demand loading, this
-    allows enabling hardware decoding at runtime at all, without having to
+    allows enabling hardware decoding at runtime at all, without having
     to temporarily set the ``hwdec`` option just during OpenGL context
     initialization with ``mpv_opengl_cb_init_gl()``.
 
@@ -675,7 +677,7 @@ Video
     example ``--video-zoom`` does nothing if this option is enabled.)
 
     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
+    would require scaling the video in the X or Y direction, but this option
     disables scaling, disabling all aspect correction.
 
     Note that the scaler algorithm may still be used, even if the video isn't
@@ -695,7 +697,7 @@ Video
 
     This option is disabled if the ``--no-keepaspect`` option is used.
 
-``--video-rotate=<0-360|no>``
+``--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,
@@ -820,7 +822,7 @@ Video
     You can get the list of allowed codecs with ``mpv --vd=help``. Remove the
     prefix, e.g. instead of ``lavc:h264`` use ``h264``.
 
-    By default this is set to ``h264,vc1,wmv3,hevc,mpeg2video``. Note that the
+    By default, this is set to ``h264,vc1,wmv3,hevc,mpeg2video``. 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.
 
@@ -1027,7 +1029,9 @@ Audio
 
 ``--mute=<auto|yes|no>``
     Set startup audio mute status. ``auto`` (default) will not change the mute
-    status. Also see ``--volume``.
+    status.
+
+    See also: ``--volume``.
 
 ``--softvol=<mode>``
     Control whether to use the volume controls of the audio output driver or
@@ -1152,8 +1156,8 @@ Audio
     point of file change. Default: ``weak``.
 
     :no:    Disable gapless audio.
-    :yes:   The audio device is opened using parameters chosen according to the
-            first file played and is then kept open for gapless playback. This
+    :yes:   The audio device is opened using parameters chosen for the first
+            file played and is then kept open for gapless playback. This
             means that if the first file for example has a low sample rate, then
             the following files may get resampled to the same low sample rate,
             resulting in reduced sound quality. If you play files with different
@@ -1200,7 +1204,11 @@ Audio
     :no:    Don't automatically load external audio files.
     :exact: Load the media filename with audio file extension (default).
     :fuzzy: Load all audio files containing media filename.
-    :all:   Load all audio files in the current directory.
+    :all:   Load all aufio files in the current and ``--audio-file-paths``
+            directories.
+
+``--audio-file-paths=<path1:path2:...>``
+    Equivalent to ``--sub-paths`` option, but for auto-loaded audio files.
 
 ``--audio-client-name=<name>``
     The application name the player reports to the audio API. Can be useful
@@ -1237,6 +1245,14 @@ Audio
 Subtitles
 ---------
 
+.. note::
+
+    Changing styling and position does not work with all subtitles. Image-based
+    subtitles (DVD, Bluray/PGS, DVB) can not changed for fundamental reasons.
+    Subtitles in ASS format are normally not changed intentionally, but
+    overriding them can be controlled with ``--ass-style-override``.
+
+
 ``--no-sub``
     Do not select any subtitle when the file is loaded.
 
@@ -1600,10 +1616,10 @@ Subtitles
         ``<rate>`` > video fps speeds the subtitles up for frame-based
         subtitle files and slows them down for time-based ones.
 
-    Also see ``--sub-speed`` option.
+    See also: ``--sub-speed``.
 
 ``--sub-gauss=<0.0-3.0>``
-    Apply Gaussian blur to image subtitles (default: 0). This can help making
+    Apply Gaussian blur to image subtitles (default: 0). This can help to make
     pixelated DVD/Vobsubs look nicer. A value other than 0 also switches to
     software subtitle scaling. Might be slow.
 
@@ -1612,7 +1628,7 @@ Subtitles
         Never applied to text subtitles.
 
 ``--sub-gray``
-    Convert image subtitles to grayscale. Can help making yellow DVD/Vobsubs
+    Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs
     look nicer.
 
     .. note::
@@ -1984,8 +2000,8 @@ Window
     always re-enabled when the player is paused.
 
     This is not supported on all video outputs or platforms. Sometimes it is
-    implemented, but does not work (happens often on GNOME). You might be able
-    to to work this around using ``--heartbeat-cmd`` instead.
+    implemented, but does not work (known to happen with GNOME). You might be
+    able to work around this using ``--heartbeat-cmd`` instead.
 
 ``--wid=<ID>``
     This tells mpv to attach to an existing window. If a VO is selected that
@@ -2004,7 +2020,7 @@ Window
     parent, like with X11.
 
     On OSX/Cocoa, the ID is interpreted as ``NSView*``. Pass it as value cast
-    to ``intptr_t``. mpv will creates its own sub-view. Because OSX does not
+    to ``intptr_t``. mpv will create its own sub-view. Because OSX does not
     support window embedding of foreign processes, this works only with libmpv,
     and will crash when used from the command line.
 
@@ -2213,7 +2229,7 @@ Demuxer
     Encryption key the demuxer should use. This is the raw binary data of
     the key converted to a hexadecimal string.
 
-``--demuxer-mkv-subtitle-preroll``, ``--mkv-subtitle-preroll``
+``--demuxer-mkv-subtitle-preroll=<yes|index|no>``, ``--mkv-subtitle-preroll``
     Try harder to show embedded soft subtitles when seeking somewhere. Normally,
     it can happen that the subtitle at the seek target is not shown due to how
     some container file formats are designed. The subtitles appear only if
@@ -2245,7 +2261,11 @@ Demuxer
     overlap with a seek target. In these cases, mpv will reduce the amount
     of data read to a minimum. (Although it will still read *all* data between
     the cluster that contains the first wanted subtitle packet, and the seek
-    target.)
+    target.) If the ``index`` choice (which is the default) is specified, then
+    prerolling will be done only if this information is actually available. If
+    this method is used, the maximum amount of data to skip can be additionally
+    controlled by ``--demuxer-mkv-subtitle-preroll-secs-index`` (it still uses
+    the value of the option without ``-index`` if that is higher).
 
     See also ``--hr-seek-demuxer-offset`` option. This option can achieve a
     similar effect, but only if hr-seek is active. It works with any demuxer,
@@ -2257,6 +2277,9 @@ Demuxer
 ``--demuxer-mkv-subtitle-preroll-secs=<value>``
     See ``--demuxer-mkv-subtitle-preroll``.
 
+``--demuxer-mkv-subtitle-preroll-secs-index=<value>``
+    See ``--demuxer-mkv-subtitle-preroll``.
+
 ``--demuxer-mkv-probe-video-duration=<yes|no|full>``
     When opening the file, seek to the end of it, and check what timestamp the
     last video packet has, and report that as file duration. This is strictly
@@ -2381,7 +2404,7 @@ Input
 
 ``--input-key-fifo-size=<2-65000>``
     Specify the size of the FIFO that buffers key events (default: 7). If it
-    is too small some events may be lost. The main disadvantage of setting it
+    is too small, some events may be lost. The main disadvantage of setting it
     to a very large value is that if you hold down a key triggering some
     particularly slow command then the player may be unresponsive while it
     processes all the queued commands.
@@ -2448,7 +2471,7 @@ Input
 
     On X11, a sub-window with input enabled grabs all keyboard input as long
     as it is 1. a child of a focused window, and 2. the mouse is inside of
-    the sub-window. The can steal away all keyboard input from the
+    the sub-window. It can steal away all keyboard input from the
     application embedding the mpv window, and on the other hand, the mpv
     window will receive no input if the mouse is outside of the mpv window,
     even though mpv has focus. Modern toolkits work around this weird X11
@@ -2718,7 +2741,7 @@ Screenshot
     Specify the filename template used to save screenshots. The template
     specifies the filename without file extension, and can contain format
     specifiers, which will be substituted when taking a screenshot.
-    By default the template is ``mpv-shot%n``, which results in filenames like
+    By default, the template is ``mpv-shot%n``, which results in filenames like
     ``mpv-shot0012.png`` for example.
 
     The template can start with a relative or absolute path, in order to
@@ -2874,7 +2897,7 @@ Terminal
     Particularly useful on slow terminals or broken ones which do not properly
     handle carriage return (i.e. ``\r``).
 
-    Also see ``--really-quiet`` and ``--msg-level``.
+    See also: ``--really-quiet`` and ``--msg-level``.
 
 ``--really-quiet``
     Display even less output and status messages than with ``--quiet``.
@@ -3007,8 +3030,9 @@ TV
     maximum size of the capture buffer in megabytes (default: dynamical)
 
 ``--tv-norm=<value>``
-    See the console output for a list of all available norms, also see the
-    ``normid`` option below.
+    See the console output for a list of all available norms.
+
+    See also: ``--tv-normid``.
 
 ``--tv-normid=<value> (v4l2 only)``
     Sets the TV norm to the given numeric ID. The TV norm depends on the
@@ -3218,7 +3242,7 @@ Cache
        multiple cache streams, and using the same file for them obviously
        clashes.
 
-    Also see ``--cache-file-size``.
+    See also: ``--cache-file-size``.
 
 ``--cache-file-size=<kBytes>``
     Maximum size of the file created with ``--cache-file``. For read accesses
@@ -3346,8 +3370,13 @@ DVB
 
 ``--dvbin-full-transponder=<yes|no>``
     Apply no filters on program PIDs, only tune to frequency and pass full
-    transponder to demuxer. This is useful to record multiple programs
-    on a single transponder, or to work around issues in the ``channels.conf``.
+    transponder to demuxer.
+    The player frontend selects the streams from the full TS in this case,
+    so the program which is shown initially may not match the chosen channel.
+    Switching between the programs is possible by cycling the ``program``
+    property.
+    This is useful to record multiple programs on a single transponder,
+    or to work around issues in the ``channels.conf``.
     It is also recommended to use this for channels which switch PIDs
     on-the-fly, e.g. for regional news.
 
@@ -3380,7 +3409,7 @@ Miscellaneous
     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.
+    side effect of turning this option on, for all sound drivers.
 
 ``--video-sync=<audio|...>``
     How the player synchronizes audio and video.
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index 72e1559d76..ff3f539416 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -151,15 +151,15 @@ Available filters are:
         :yes: Enable accurate rounding.
 
 ``dsize[=w:h:aspect-method:r:aspect]``
-    Changes the intended display size/aspect at an arbitrary point in the
+    Changes the intended display aspect at an arbitrary point in the
     filter chain. Aspect can be given as a fraction (4/3) or floating point
-    number (1.33). Alternatively, you may specify the exact display width and
-    height desired. Note that this filter does *not* do any scaling itself; it
+    number (1.33). Note that this filter does *not* do any scaling itself; it
     just affects what later scalers (software or hardware) will do when
     auto-scaling to the correct aspect.
 
     ``<w>,<h>``
-        New display width and height.
+        New aspect ratio given by a display width and height. Unlike older mpv
+        versions or MPlayer, this does not set the display size.
 
         Can also be these special values:
 
@@ -438,9 +438,8 @@ Available filters are:
         generating an occasional mismatched frame, but it may also cause an
         excessive number of frames to be dropped during high motion sequences.
         Conversely, setting it to -1 will make ``pullup`` match fields more
-        easily. This may help processing of video where there is slight
-        blurring between the fields, but may also cause there to be interlaced
-        frames in the output.
+        easily. This may help process video with slight blurring between the
+        fields, but may also cause interlaced frames in the output.
 
     ``mp`` (metric plane)
         This option may be set to ``u`` or ``v`` to use a chroma plane instead of the
@@ -455,16 +454,15 @@ Available filters are:
 
     ``<mode>``
         :frame: Output 1 frame for each frame.
-        :field: Output 1 frame for each field.
+        :field: Output 1 frame for each field (default).
         :frame-nospatial: Like ``frame`` but skips spatial interlacing check.
         :field-nospatial: Like ``field`` but skips spatial interlacing check.
 
     ``<interlaced-only>``
-        :no:  Deinterlace all frames (default).
-        :yes: Only deinterlace frames marked as interlaced (default if this
-              filter is inserted via ``deinterlace`` property).
+        :no:  Deinterlace all frames.
+        :yes: Only deinterlace frames marked as interlaced (default).
 
-    This filter, is automatically inserted when using the ``d`` key (or any
+    This filter is automatically inserted when using the ``d`` key (or any
     other key that toggles the ``deinterlace`` property or when using the
     ``--deinterlace`` switch), assuming the video output does not have native
     deinterlacing support.
@@ -473,7 +471,7 @@ Available filters are:
     into ``--vf-defaults`` instead, and enable deinterlacing with ``d`` or
     ``--deinterlace``.
 
-    Also note that the ``d`` key is stupid enough to insert a deinterlacer twice
+    Also, note that the ``d`` key is stupid enough to insert a deinterlacer twice
     when inserting yadif with ``--vf``, so using the above methods is
     recommended.
 
@@ -645,10 +643,11 @@ Available filters are:
     ``buffered-frames``
         Maximum number of decoded video frames that should be buffered before
         the filter (default: 4). This specifies the maximum number of frames
-        the script can requests backwards. E.g. if ``buffered-frames=5``, and
-        the script just requested frame 15, it can still request frame 10, but
-        frame 9 is not available anymore. If it requests frame 30, mpv will
-        decode 15 more frames, and keep only frames 25-30.
+        the script can request in reverse direction.
+        E.g. if ``buffered-frames=5``, and the script just requested frame 15,
+        it can still request frame 10, but frame 9 is not available anymore.
+        If it requests frame 30, mpv will decode 15 more frames, and keep only
+        frames 25-30.
 
         The actual number of buffered frames also depends on the value of the
         ``concurrent-frames`` option. Currently, both option values are
@@ -803,6 +802,6 @@ Available filters are:
 
 ``buffer=<num>``
     Buffer ``<num>`` frames in the filter chain. This filter is probably pretty
-    useless, except for debugging. (Note that this won't help smoothing out
+    useless, except for debugging. (Note that this won't help to smooth out
     latencies with decoding, because the filter will never output a frame if<