[FFmpeg-devel] [PATCH] documentation: Fix several documentation bugs in trac ticket #2413
littlebat
dashing.meng at gmail.com
Fri Apr 5 04:14:18 CEST 2013
On Thu, 4 Apr 2013 19:53:20 +0200
Stefano Sabatini <stefasab at gmail.com> wrote:
> On date Thursday 2013-04-04 23:04:05 +0800, littlebat encoded:
> > Fix trac ticket #2413
> >
> > See: attachment doc.patch.
>
First of all, in fact, I have explained the reason I made the change
at: https://ffmpeg.org/trac/ffmpeg/ticket/2413#comment:2 . But, it
seems the ffmpeg-devel list is a more proper place to discuss this
question, so I am willing to answer your question one by one here:-)
> > diff -Nur a/doc/ffmpeg.texi b/doc/ffmpeg.texi
> > --- a/doc/ffmpeg.texi 2013-04-04 17:35:24.000000000 +0800
> > +++ b/doc/ffmpeg.texi 2013-04-04 22:23:52.000000000 +0800
> > @@ -352,10 +352,8 @@
> >
> > @var{filtergraph} is a description of the filtergraph to apply to
> > the stream, and must have a single input and a single output of the
> > -same type of the stream. In the filtergraph, the input is
> > associated -to the label @code{in}, and the output to the label
> > @code{out}. See -the ffmpeg-filters manual for more information
> > about the filtergraph -syntax.
> > +same type of the stream. See the ffmpeg-filters manual for more
> > information +about the filtergraph syntax.
>
> ffmpeg -i INPUT -vf "[in]null[out]" OUTPUT
>
> So what's wrong with this syntax? Note that the syntax for
> -vf/filter:v is different from the syntax for -filter_complex.
In the old ffmpeg version(e.g., ffmpeg 0.7.13 on my Debian 6 machine),
label "[in]" and "[out]" are the special "magic" label, sometime, "-vf"
option will stop work if missing them. But, in the recent ffmpeg, these
two labels are not necessary, the command line below will works in
recent ffmpeg(except the different result) when it stop work in ffmpeg
0.7.13:
ffmpeg -i in.avi -vf \
"split [T1], [T2] overlay=0:H/2; \
[T1] crop=iw:ih/2:0:0, vflip [T2]" out.avi
"In the filtergraph, the input is associated -to the label @code{in},
and the output to the label @code{out}.", this misguide me that [in]
and [out] label is still the necessary part in the recent ffmpeg.
> >
> > See the @ref{filter_complex_option,,-filter_complex option} if you
> > want to create filtergraphs with multiple inputs and/or outputs.
> > diff -Nur a/doc/ffplay.texi b/doc/ffplay.texi
> > --- a/doc/ffplay.texi 2013-04-04 17:35:24.000000000 +0800
> > +++ b/doc/ffplay.texi 2013-04-04 22:23:52.000000000 +0800
> > @@ -79,10 +79,8 @@
> >
> > @var{filtergraph} is a description of the filtergraph to apply to
> > the stream, and must have a single video input and a single video
> > -output. In the filtergraph, the input is associated to the label
> > - at code{in}, and the output to the label @code{out}. See the
> > -ffmpeg-filters manual for more information about the filtergraph
> > -syntax.
> > +output. See the ffmpeg-filters manual for more information about
> > the +filtergraph syntax.
>
> Ditto.
Ditto.
>
> > @item -af @var{filtergraph}
> > @var{filtergraph} is a description of the filtergraph to apply to
> > diff -Nur a/doc/filters.texi b/doc/filters.texi
> > --- a/doc/filters.texi 2013-04-04 17:35:24.000000000 +0800
> > +++ b/doc/filters.texi 2013-04-04 22:23:52.000000000 +0800
> > @@ -3,10 +3,7 @@
> >
> > Filtering in FFmpeg is enabled through the libavfilter library.
> >
>
> > -In libavfilter, it is possible for filters to have multiple inputs
> > and -multiple outputs.
>
> Why did you remove this sentence?
>
> > -To illustrate the sorts of things that are possible, we can
> > -use a complex filtergraph. For example, the following one:
The example here is talking about a simple filter and not a complex
filter, "-vf" option process only one video stream in and out. The
words above misguide me this example is a complex filter example.
of course, we can still use option "-filter_complex" here to achieve the
same needs as below, but, we have used "-vf" option here.
ffmpeg -i input -filter_complex \
"[0:v] split [split_out_0] [split_out_1]; \
[split_out_1] crop=iw:ih/2:0:0, vflip [vflip_out_0]; \
[split_out_0] [vflip_out_0] overlay=0:H/2 [out_v_0]" \
-map [out_v_0] -map 0:a output
> > +To illustrate the usage, we can use a filtergraph. For example,
> > the following one:
> > @example
> > input --> split ---------------------> overlay --> output
> > @@ -20,7 +17,10 @@
> > overlaying it on top. You can use the following command to achieve
> > this:
> > @example
> > -ffmpeg -i input -vf "[in] split [T1], [T2] overlay=0:H/2 [out];
> > [T1] crop=iw:ih/2:0:ih/2, vflip [T2]" output
>
> According to current doc, we have that the first unlabelled output of
> split is connected to the first unlabelled output of overlay, thus the
> main uncropped video is sent to the overlay second input, and moved to
> lower part of the screen, while the first half contains the lower part
> vflipped.
>
> So we have:
> +--------------+
> |lower vflipped|
> |higher |
> +--------------+
>
> > +ffmpeg -i input -vf \
> > + "[in_0] split [split_out_0] [split_out_1];
> > + [split_out_1] crop=iw:ih/2:0:0, vflip [vflip_out_0];
> > + [split_out_0] [vflip_out_0] overlay=0:H/2 [out_0]" output
> > @end example
>
> You may replace [in_0] to [in] since there is no ambiguity,
> [vflip_out_0] -> [vflip_out], [out_0] -> [out].
Replace [in] to [in_0] and [out] to [out_0], it's my intent. "[in_0]"
will break the misguiding me that special magic "[in]" and "[out]"
label is still necessary in the recent ffmpeg.
>
> I suggest to specify a shortest syntax for the same command:
>
> ffmpeg -i input -vf "split[T1], crop=iw:ih/2:0:0, vflip, [T1]
> overlay=0:H/2"
>
> or even:
>
> which makes minimal use of intermediate labels and is a oneliner, so
> the user can easily do copy&paste on the commandline.
Yes, your command line is more tidy. But, I think the purpose of
documentation is help the beginner understand the command line more
easier. Seperate filters into three groups(filterchain) according to
their function and label every entry and exit of filterchain is helpful
for me to understand the command line. In you command line, you used the
unlabelled link, this will increase the difficulty for me to understand
it.
>
> >
> > The result will be that in output the top half of the video is
> > mirrored @@ -28,12 +28,20 @@
> >
> > Filters are loaded using the @var{-vf} or @var{-af} option passed
> > to @command{ffmpeg} or to @command{ffplay}. Filters in the same
> > linear -chain are separated by commas. In our example, @var{split,
> > -overlay} are in one linear chain, and @var{crop, vflip} are in
> > -another. The points where the linear chains join are labeled by
> > names -enclosed in square brackets. In our example, that is @var
> > {[T1]} and - at var{[T2]}. The special labels @var{[in]} and @var
> > {[out]} are the points -where video is input and output.
>
> > +chain are separated by commas. For example, we separate this
> > filtergraph into +three filterchains: the first filterchain is @var
> > {split} filter(according to +the filtergraph BNF description below,
> > a filter can be a filterchain, even a +filtergraph) has one default
> > input pad(a video stream), and has two ouput pads; + at var{crop,
> > vflip} are in the second, it has one input pad and output pad; +The
> > third filterchain is @var{overlay} filter, has two input pads and
> > one +output pad. These three filterchains are linked with
> > linklabels: Link the first +and the second filterchain with
> > linklabel @var{[split_out_1]}, the first and +the third with @var
> > {[split_out_0]}, the second and the third with + at var{[vflip_out_0]}.
>
> > Linklabel @var{[in_0]} and @var{[out_0]} has no any
> > +special meaning, they even can be omitted, putting them there only
> > is an +indicating the video stream in and out point, they will be
> > meaningful in a +complex filtergraph(with @var{-filter_complex}
> > option) which has multiple +inputs or/and outputs.
>
> This is partially inconsistent.
>
> In general I find your description more confusing than the replaced
> text. In particular I don't like the mention to terms which are
> defined later in the document (it is like a math book using terms
> which are defined later). Also the terms are related to the syntax,
> "filter" in the BNF should be rather interpreted like a filter
> description.
I think putting the example at the beginning is just showing the usage
of the filtergraph, so, it can't be avoided to mention the term defined
later. In the long text above, I try to explain how my command line
works. And try to make documentation user to understand filtergraph
more quickly. If my description confuse you, it is not my willing. I am
just a ffmpeg beginner and a non-english user. Any error please fix me.
>
> > Some filters take in input a list of parameters: they are specified
> > after the filter name and an equal sign, and are separated from
> > each other @@ -107,10 +115,11 @@
> > @section Filtergraph syntax
> >
> > A filtergraph can be represented using a textual representation,
> > which is -recognized by the @option{-filter}/@option{-vf} and
> > @option{-filter_complex} -options in @command{ffmpeg} and @option
> > {-vf} in @command{ffplay}, and by the - at code{avfilter_graph_parse
> > ()}/@code{avfilter_graph_parse2()} function defined in - at file
> > {libavfilter/avfiltergraph.h}. +recognized by the @option
> > {-filter:v}/@option{-vf} and + at option{-filter:a}/@option{-af} and
> > @option{-filter_complex} options in + at command{ffmpeg} and @option
> > {-vf} and @option{-af} in @command{ffplay}, +and by the @code
> > {avfilter_graph_parse()}/@code{avfilter_graph_parse2()} +function
> > defined in @file{libavfilter/avfiltergraph.h}.
>
> > A filterchain consists of a sequence of connected filters, each one
> > connected to the previous one in the sequence. A filterchain is
> > @@ -4326,7 +4335,7 @@
> > Add a transparent color layer on top of the main video, WxH
> > specifies the size of the main input to the overlay filter:
> > @example
> > -color=red@@.3:WxH [over]; [in][over] overlay [out]
> > +color=color=red@@0.3:size=WxH [over]; [in][over] overlay [out]
> > @end example
> >
> > @item
> > @@ -7128,7 +7137,7 @@
> > on top of the input labelled as "in":
> > @example
>
> > movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS
> > [movie]; -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
> > +[in] setpts=PTS-STARTPTS [setpts], [setpts] [movie] overlay=16:16
> > [out] @end example
> >
> > @item
> > @@ -7136,7 +7145,7 @@
> > labelled as "in":
> > @example
>
> > movie=/dev/video0:f=video4linux2, scale=180:-1,
> > setpts=PTS-STARTPTS [movie]; -[in] setpts=PTS-STARTPTS, [movie]
> > overlay=16:16 [out] +[in] setpts=PTS-STARTPTS [setpts], [setpts]
> > [movie] overlay=16:16 [out]
>
> I find this slightly more complex to understand than:
> [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
>
> What's the rationale?
If miss linklabel "[setpts]", the "[movie]" as the first input pad
of filter "overlay", the unlabelled output pad of filter "setpts" will
become the second unlabelled input pad of filter "overlay", it will
overlay on top of the input pad "[movie]". But, the docmentation's needs
is "Read from a video4linux2 device, and overlay it on top of the input
labelled as "in": ".
I suppose this is a bug similar to the filtergprah example at the
beginning of this email.
> --
> FFmpeg = Frightening & Fanciful Minimalistic Puristic Explosive
> Gangster _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
More information about the ffmpeg-devel
mailing list