[FFmpeg-trac] #2413(documentation:open): Wrong complex filter graph example

[FFmpeg]

#2413: Wrong complex filter graph example
-------------------------------------+-------------------------------------
             Reporter:  littlebat    |                    Owner:
                 Type:  defect       |                   Status:  open
             Priority:  minor        |                Component:
              Version:  git-master   |  documentation
             Keywords:               |               Resolution:
             Blocking:               |               Blocked By:
Analyzed by developer:  0            |  Reproduced by developer:  1
-------------------------------------+-------------------------------------

Comment (by littlebat):

 I am studying ffmpeg filtergraph these days, I found some documentation
 errors and post my sugguetions here, maybe still exist error too, please
 correct me if so.

 Bugs in page: http://ffmpeg.org/ffmpeg-filters.html :

 1, Because this filter example only process one video stream with "-vf"
 option, so it's a simple filtergraph. so, changed:
 "In libavfilter, it is possible for filters to have multiple inputs and
 multiple outputs. To illustrate the sorts of things that are possible, we
 can use a complex filtergraph. "
 to:
 "To illustrate the usage, we can use a filtergraph."

 2, Changed:
 ffmpeg -i input -vf "[in] split [T1], [T2] overlay=0:H/2 [out]; [T1]
 crop=iw:ih/2:0:ih/2, vflip [T2]" output
 to:
 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

 3, Changed:
 "Filters are loaded using the -vf or -af option passed to ffmpeg or to
 ffplay. Filters in the same linear chain are separated by commas. In our
 example, split, overlay are in one linear chain, and 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 [T1] and [T2]. The
 special labels [in] and [out] are the points where video is input and
 output."
 to:
 "Filters are loaded using the -vf or -af option passed to ffmpeg or to
 ffplay. Filters in the same linear chain are separated by commas. For
 example, we separate this filter graph into three filterchains: the first
 filterchain is "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; "crop, vflip" are in
 the second, it has one input pad and output pad; The third filterchain is
 "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 "[split_out_1]", the first and the third with
 "[split_out_0]", the second and the third with "[vflip_out_0]". Linklabel
 "[in_0]" and "[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
 -filter_complex option) which has multiple inputs or/and outputs."

 4, 4.1 Filtergraph syntax, Changed:
 "A filtergraph can be represented using a textual representation, which is
 recognized by the ‘-filter’/‘-vf’ and ‘-filter_complex’ options in ffmpeg
 and ‘-vf’ in ffplay, "
 to:
 "A filtergraph can be represented using a textual representation, which is
 recognized by the ‘-filter:v’/‘-vf’ and '-filter:a'/'-af' and
 ‘-filter_complex’ options in ffmpeg and ‘-vf’ and "-af" in ffplay, "

 5, 8.45.1 Examples, Changed:
 "color=red at .3:WxH [over]; [in][over] overlay [out]"
 to:
 "color=color=red at .3:size=WxH [over]; [in][over] overlay [out]"

 6, 12.2.1 Examples, similar error as the second change above, changed:
 "movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]"
 to:
 "movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
 [in] setpts=PTS-STARTPTS [setpts], [setpts] [movie] overlay=16:16 [out]"

 7, 12.2.1 Examples, similar error as the bug "2" above, changed:
 "movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS
 [movie]; [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]"
 to:
 "movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS
 [movie]; [in] setpts=PTS-STARTPTS [setpts], [setpts] [movie] overlay=16:16
 [out]"

 Bugs in page: http://ffmpeg.org/ffmpeg.html#Main-options :
 8, ‘-filter[:stream_specifier] filtergraph (output,per-stream)’, because
 in recent ffmpeg, it is no necessary to use the "magic" label "[in]" and
 "[out]", so, deleted:
 "In the filtergraph, the input is associated to the label in, and the
 output to the label out. "

 By the way, I found ffmpeg 0.7.13(5:0.7.13-dmo2 Unofficial Multimedia
 Packages:6.0/stable [i386]) works on original command line in the bug
 2,6,7 above in my Debian 6 machine, except need change
 "crop=iw:ih/2:0:ih/2" to "crop=iw:ih/2:0:0" in the change 2. I found
 ffmpeg 0.7.13 breaks its own filter link rule in local documentation "If
 an output pad is not labelled, it is linked by default to the first
 unlabelled input pad of the next filter in the filterchain. ", for
 example, in the bug 7, "[in] setpts=PTS-STARTPTS" created an unlabelled
 output pad, it should be the second unlabelled input pad of "[movie]
 overlay=16:16 [out]", for the "overlay" filter, according to local
 documentation, it should be the second unlabelled input pad overlayed on
 the first "[movie]" label input pad, but, in fact, it's the first
 "[movie]" label input pad overlayed on the second unlabelled input pad.
 It's really a strange behavior. Is it a ffmpeg 0.7.13 bug? And, ffmpeg
 0.7.13 has the special "magic" "[in]" and "[out]" label which has been
 dropped in recent ffmpeg.

-- 
Ticket URL: <https://ffmpeg.org/trac/ffmpeg/ticket/2413#comment:2>
FFmpeg <http://ffmpeg.org>
FFmpeg issue tracker