From 45cab1562c21747ae0721e6173180e0c0ad879fc Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 23 Oct 2019 22:27:07 +0200 Subject: 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. --- DOCS/man/vf.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 71 insertions(+), 18 deletions(-) (limited to 'DOCS') 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 -- cgit v1.2.3