[FFmpeg-devel] [PATCH] documentation: Fix several documentation bugs in trac ticket #2413

[Stefano Sabatini]

On date Friday 2013-04-05 10:14:18 +0800, littlebat encoded:
> 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:

Can you show a failing command?

> 
> 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.

There is a special rule (possibly undocumented), for which the name of
the input of the first filter in the filtergraph is assumed to be
"in", *if* the filter has just one input and an input was not
specified, so that:
foo,...
is equivalent to:
[in]foo

and the output of the last specified filter is "out" if not specified,
for example:
foo, bar
is equivalent to:
foo, bar[out]

In some cases you may need to define the label explicitly. For
example:
"movie=logo.png[logo]; [in][logo]overlay"

since here the first filter has no inputs.

This was done for simplifying the -vf syntax, so that you don't always
need to specify [in] and [out] in the filtergraph. OTOH this doesn't
always work with the lavfi device and filter_complex.

If you remove that info from the docs you're removing a bit of
information required for understanding the -vf/-af syntax.

> 
> > >  
> > >  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.

What about this:
-----8<-----------------8<--------------------------------------
To illustrate the sorts of things that are possible, we use
the following filtergraph.

@example
input --> split ---------------------> overlay --> output
            |                             ^
            |                             |
            +-----> crop --> vflip -------+
@end example

splits the stream in two streams, sends one stream through the crop filter
and the vflip filter before merging it back with the other stream by
overlaying it on top. You can use the following command to achieve this:

@example
ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
@end example

The result will be that in output the top half of the video is mirrored
onto the bottom half.

Filters in the same linear chain are separated by commas, and distinct
linear chains are separated by semicolons. In our example, @var{crop,
vflip} are in one linear chain, and @var{split} and @var{overlay} are
in another.

The points where the linear chains join are labeled by names enclosed
in square brackets.

In our example, the split filter generates two outputs that are
associated to the lables @var{[main]} and @var{tmp}.
The stream sent to the second output of split, labelled as @var{[tm]},
is processed through the crop filter, which crops away the lower half
part of the video, and vertically flipped.

The overlay filter takes in input the first unchanged output of the
split filter (which was labelled as @var{[main}}, and overlay on its
lower half the output generated by the @var{crop, vflip} filterchain.
 
> > 
> > >  
> > >  The result will be that in output the top half of the video is
> > > mirrored @@ -28,12 +28,20 @@

-----8<-----------------8<--------------------------------------
[...]
> > > @@ -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

I'll push this right away as a separate commit.

> > >  
> > >  @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.

Please can you send this as a separate patch?
-- 
FFmpeg = Fundamentalist and Faithful Mere Powerful Empowered Gigant