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

[Stefano Sabatini]

On date Thursday 2013-04-04 23:04:05 +0800, littlebat encoded:
> Fix trac ticket #2413
> 
> See: attachment doc.patch.

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

>  
>  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.
  
>  @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:
> +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].

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.

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

>  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?
-- 
FFmpeg = Frightening & Fanciful Minimalistic Puristic Explosive Gangster