vf: improve vf_vapoursynth description

In particular describe dataflow issues (see #7020).

Insert complaint that I'm wasting time on this crap instead of things
that benefit me.

1 files changed, 71 insertions, 18 deletions

diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index c34345a71b..d82af72468 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -395,22 +395,26 @@ Available mpv-only filters are:
     of that will return errors. As such, you can't use the full power of
     VapourSynth, but you can use certain filters.
 
-    If you just want to play video generated by a VapourSynth (i.e. using
+    If you just want to play video generated by VapourSynth (i.e. using
     a native VapourSynth video source), it's better to use ``vspipe`` and a
-    FIFO to feed the video to mpv. The same applies if the filter script
+    pipe or FIFO to feed the video to mpv. The same applies if the filter script
     requires random frame access (see ``buffered-frames`` parameter).
 
-    This filter is experimental. If it turns out that it works well and is
-    used, it will be ported to libavfilter. Otherwise, it will be just removed.
-
     ``file``
         Filename of the script source. Currently, this is always a python
-        script. The variable ``video_in`` is set to the mpv video source,
-        and it is expected that the script reads video from it. (Otherwise,
-        mpv will decode no video, and the video packet queue will overflow,
-        eventually leading to audio being stopped.) The script is also
-        expected to pass through timestamps using the ``_DurationNum`` and
-        ``_DurationDen`` frame properties.
+        script (``.vpy`` in VapourSynth convention).
+
+        The variable ``video_in`` is set to the mpv video source, and it is
+        expected that the script reads video from it. (Otherwise, mpv will
+        decode no video, and the video packet queue will overflow, eventually
+        leading to only audio playing, or worse.)
+
+        The filter graph created by the script is also expected to pass through
+        timestamps using the ``_DurationNum`` and ``_DurationDen`` frame
+        properties.
+
+        See the end of the option list for a full list of script variables
+        defined by mpv.
 
         .. admonition:: Example:
 
@@ -428,21 +432,61 @@ Available mpv-only 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 request in reverse direction.
+        the script can request in backward direction.
+
         E.g. if ``buffered-frames=5``, and the script just requested frame 15,
         it can still request frame 10, but frame 9 is not available anymore.
         If it requests frame 30, mpv will decode 15 more frames, and keep only
         frames 25-30.
 
+        The only reason why this buffer exists is to serve the random access
+        requests the VapourSynth filter can make.
+
+        The VapourSynth API has a ``getFrameAsync`` function, which takes an
+        absolute frame number. Source filters must respond to all requests. For
+        example, a source filter can request frame 2432, and then frame 3.
+        Source filters  typically implement this by pre-indexing the entire
+        file.
+
+        mpv on the other hand is stream oriented, and does not allow filters to
+        seek. (And it would not make sense to allow it, because it would ruin
+        performance.) Filters get frames sequentially in playback direction, and
+        cannot request them out of order.
+
+        To compensate for this mismatch, mpv allows the filter to access frames
+        within a certain window. ``buffered-frames`` controls the size of this
+        window. Most VapourSynth filters happen to work with this, because mpv
+        requests frames sequentially increasing from it, and most filters only
+        require frames "close" to the requested frame.
+
+        If the filter requests a frame that has a higher frame number than the
+        highest buffered frame, new frames will be decoded until the requested
+        frame number is reached. Excessive frames will be flushed out in a FIFO
+        manner (there are only at most ``buffered-frames`` in this buffer).
+
+        If the filter requests a frame that has a lower frame number than the
+        lowest buffered frame, the request cannot be satisfied, and an error
+        is returned to the filter. This kind of error is not supposed to happen
+        in a "proper" VapourSynth environment. What exactly happens depends on
+        the filters involved.
+
+        Increasing this buffer will not improve performance. Rather, it will
+        waste memory, and slow down seeks (when enough frames to fill the buffer
+        need to be decoded at once). It is only needed to prevent the error
+        described in the previous paragraph.
+
+        How many frames a filter requires depends on filter implementation
+        details, and mpv has no way of knowing. A scale filter might need only
+        1 frame, an interpolation filter may require a small number of frames,
+        and the ``Reverse`` filter will require an infinite number of frames.
+
+        If you want reliable operation to the full extend VapourSynth is
+        capable, use ``vspipe``.
+
         The actual number of buffered frames also depends on the value of the
         ``concurrent-frames`` option. Currently, both option values are
         multiplied to get the final buffer size.
 
-        (Normally, VapourSynth source filters must provide random access, but
-        mpv was made for playback, and does not provide frame-exact random
-        access. The way this video filter works is a compromise to make simple
-        filters work anyway.)
-
     ``concurrent-frames``
         Number of frames that should be requested in parallel. The
         level of concurrency depends on the filter and how quickly mpv can
@@ -451,10 +495,19 @@ Available mpv-only filters are:
         making it higher than the number of cores can actually make it
         slower.
 
+        Technically, mpv will call the VapourSynth ``getFrameAsync`` function
+        in a loop, until there are ``concurrent-frames`` frames that have not
+        been returned by the filter yet. This also assumes that the rest of the
+        mpv filter chain reads the output of the ``vapoursynth`` filter quickly
+        enough. (For example, if you pause the player, filtering will stop very
+        soon, because the filtered frames are waiting in a queue.)
+
+        Actual concurrency depends on many other factors.
+
         By default, this uses the special value ``auto``, which sets the option
         to the number of detected logical CPU cores.
 
-    The following variables are defined by mpv:
+    The following ``.vpy`` script variables are defined by mpv:
 
     ``video_in``
         The mpv video source as vapoursynth clip. Note that this has no length