mirror of https://github.com/mpv-player/mpv
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.
This commit is contained in:
parent
899e0bd16b
commit
45cab1562c
|
@ -395,22 +395,26 @@ Available mpv-only filters are:
|
||||||
of that will return errors. As such, you can't use the full power of
|
of that will return errors. As such, you can't use the full power of
|
||||||
VapourSynth, but you can use certain filters.
|
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
|
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).
|
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``
|
``file``
|
||||||
Filename of the script source. Currently, this is always a python
|
Filename of the script source. Currently, this is always a python
|
||||||
script. The variable ``video_in`` is set to the mpv video source,
|
script (``.vpy`` in VapourSynth convention).
|
||||||
and it is expected that the script reads video from it. (Otherwise,
|
|
||||||
mpv will decode no video, and the video packet queue will overflow,
|
The variable ``video_in`` is set to the mpv video source, and it is
|
||||||
eventually leading to audio being stopped.) The script is also
|
expected that the script reads video from it. (Otherwise, mpv will
|
||||||
expected to pass through timestamps using the ``_DurationNum`` and
|
decode no video, and the video packet queue will overflow, eventually
|
||||||
``_DurationDen`` frame properties.
|
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:
|
.. admonition:: Example:
|
||||||
|
|
||||||
|
@ -428,21 +432,61 @@ Available mpv-only filters are:
|
||||||
``buffered-frames``
|
``buffered-frames``
|
||||||
Maximum number of decoded video frames that should be buffered before
|
Maximum number of decoded video frames that should be buffered before
|
||||||
the filter (default: 4). This specifies the maximum number of frames
|
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,
|
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.
|
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
|
If it requests frame 30, mpv will decode 15 more frames, and keep only
|
||||||
frames 25-30.
|
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
|
The actual number of buffered frames also depends on the value of the
|
||||||
``concurrent-frames`` option. Currently, both option values are
|
``concurrent-frames`` option. Currently, both option values are
|
||||||
multiplied to get the final buffer size.
|
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``
|
``concurrent-frames``
|
||||||
Number of frames that should be requested in parallel. The
|
Number of frames that should be requested in parallel. The
|
||||||
level of concurrency depends on the filter and how quickly mpv can
|
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
|
making it higher than the number of cores can actually make it
|
||||||
slower.
|
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
|
By default, this uses the special value ``auto``, which sets the option
|
||||||
to the number of detected logical CPU cores.
|
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``
|
``video_in``
|
||||||
The mpv video source as vapoursynth clip. Note that this has no length
|
The mpv video source as vapoursynth clip. Note that this has no length
|
||||||
|
|
Loading…
Reference in New Issue