[FFmpeg-devel] [PATCH] documentation: Fix several documentation bugs in trac ticket #2413
littlebat
dashing.meng at gmail.com
Fri Apr 5 15:58:09 CEST 2013
On Fri, 5 Apr 2013 12:40:40 +0200
Stefano Sabatini <stefasab at gmail.com> wrote:
> 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
This command line will fail in ffmpeg 0.7.13, its detail console output
as below:
mdx at debian:~/desk$ /usr/bin/ffmpeg -i in.avi -vf "split [T1], [T2]
overlay=0:H/2; [T1] crop=iw:ih/2:0:0, vflip [T2]" out.avi ffmpeg
version 0.7.13, Copyright (c) 2000-2011 the FFmpeg developers built on
Jun 13 2012 14:01:54 with gcc 4.4.5 configuration: --enable-libdc1394
--prefix=/usr --extra-cflags='-Wall -g ' --cc='ccache cc'
--enable-shared --enable-libmp3lame --enable-gpl --enable-libvorbis
--enable-pthreads --enable-libfaac --enable-libxvid --enable-postproc
--enable-x11grab --enable-libgsm --enable-libtheora
--enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libx264
--enable-libspeex --enable-nonfree --disable-stripping
--enable-avfilter --enable-libdirac --disable-decoder=libdirac
--enable-libfreetype --enable-libschroedinger
--disable-encoder=libschroedinger --enable-version3
--enable-libopenjpeg --enable-libvpx --enable-librtmp
--extra-libs=-lgcrypt --disable-altivec --disable-armv5te
--disable-armv6 --disable-vis libavutil 50. 43. 0 / 50. 43. 0
libavcodec 52.123. 0 / 52.123. 0 libavformat 52.111. 0 / 52.111. 0
libavdevice 52. 5. 0 / 52. 5. 0 libavfilter 1. 80. 0 / 1. 80. 0
libswscale 0. 14. 1 / 0. 14. 1 libpostproc 51. 2. 0 / 51. 2. 0
Input #0, avi, from 'in.avi': Metadata: encoder : Lavf52.111.0
Duration: 00:00:06.74, start: 0.000000, bitrate: 309 kb/s Stream #0.0:
Video: mpeg4, yuv420p, 240x320 [PAR 64:27 DAR 16:9], 50 tbr, 50 tbn, 50
tbc Stream #0.1: Audio: mp2, 48000 Hz, stereo, s16, 64 kb/s File
'out.avi' already exists. Overwrite ? [y/N] y [buffer @ 0x966eae0]
w:240 h:320 pixfmt:yuv420p tb:1/1000000 sar:64/27 sws_param: Invalid
filterchain containing an unlabelled output pad: " [T2] overlay=0:H/2;
[T1] crop=iw:ih/2:0:0, vflip [T2]" Error opening filters!
But, it works in the recent ffmpeg as below:
mdx at debian:~/desk$ /opt/ffmpeggit/bin/ffmpeg -i in.avi -vf "split [T1],
[T2] overlay=0:H/2; [T1] crop=iw:ih/2:0:0, vflip [T2]" out.avi ffmpeg
version N-51433-g551f683 Copyright (c) 2000-2013 the FFmpeg developers
built on Mar 29 2013 10:01:04 with gcc 4.4.5 (Debian 4.4.5-8)
configuration: --prefix=/opt/ffmpeggit --enable-static --disable-shared
--enable-gpl --enable-version3 --enable-nonfree --enable-fontconfig
--enable-libass --enable-libfreetype --enable-swscale --enable-postproc
--enable-pthreads --enable-libfaac --enable-libopencore-amrnb
--enable-libopencore-amrwb --enable-libmp3lame --enable-libopenjpeg
--enable-libvorbis --enable-libvpx --enable-libx264 --enable-libxvid
--extra-cflags=-I/opt/custom/include --extra-ldflags=-L/opt/custom/lib
libavutil 52. 22.101 / 52. 22.101 libavcodec 55. 2.100 / 55.
2.100 libavformat 55. 0.100 / 55. 0.100 libavdevice 55.
0.100 / 55. 0.100 libavfilter 3. 48.105 / 3. 48.105
libswscale 2. 2.100 / 2. 2.100 libswresample 0. 17.102 / 0.
17.102 libpostproc 52. 2.100 / 52. 2.100 Input #0, avi, from
'in.avi': Metadata: encoder : Lavf52.111.0 Duration:
00:00:06.74, start: 0.000000, bitrate: 309 kb/s Stream #0:0: Video:
mpeg4 (Simple Profile) (FMP4 / 0x34504D46), yuv420p, 240x320 [SAR 64:27
DAR 16:9], 50 tbr, 50 tbn, 50 tbc Stream #0:1: Audio: mp2 (P[0][0][0] /
0x0050), 48000 Hz, stereo, s16p, 64 kb/s File 'out.avi' already exists.
Overwrite ? [y/N] y Overlay area with coordinates x1:0 y1:80 x2:240
y2:400 is not completely contained within the output with size 240x160
Output #0, avi, to 'out.avi': Metadata: ISFT : Lavf55.0.100
Stream #0:0: Video: mpeg4 (FMP4 / 0x34504D46), yuv420p, 240x160 [SAR
64:27 DAR 32:9], q=2-31, 200 kb/s, 50 tbn, 50 tbc Stream #0:1: Audio:
mp3 (U[0][0][0] / 0x0055), 48000 Hz, stereo, s16p Stream mapping:
Stream #0:0 -> #0:0 (mpeg4 -> mpeg4) Stream #0:1 -> #0:1 (mp2 ->
libmp3lame) Press [q] to stop, [?] for help
frame= 35 fps=0.0 q=4.6 size= 70kB time=00:00:01.42 bitrate=
406.2kbits/sframe= 76 fps= 76 q=5.3 size= 132kB time=00:00:03.06
bitrate= 352.1kbits/sframe= 117 fps= 78 q=6.4 size= 192kB
time=00:00:04.70 bitrate= 335.3kbits/sframe= 157 fps= 78 q=4.7
size= 249kB time=00:00:06.30 bitrate= 324.0kbits/sframe= 166 fps=
78 q=4.5 Lsize= 273kB time=00:00:06.74 bitrate= 331.5kbits/s
video:145kB audio:104kB subtitle:0 global headers:0kB muxing overhead
9.755618%
> >
> > 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.
>
In your words, you are saying these "[in]" and "[out]" are still have
special meaning, the input and output stream will link to them
in default if missing them. But, in my tests, in the recent ffmpeg,
these two labels has no any special meaning, it can be missing or
even replaced them by any other string! For example:
/opt/ffmpeggit/bin/ffmpeg -i in.avi -vf \
"movie=logo.png [logo]; [out] [logo] overlay [in_0]" out.avi
It seems the input video stream linked [out] automatically, and the
command line works well! I suppose these two special links "[in]" and
"[out]" have been dropped in the current ffmpeg, or they don't
function properly if they are still designed as special labels.
> >
> > > >
> > > > 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.
Append "separately" after "and @var{split} and @var{overlay} are in
another" maybe more accurate?
>
> 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}.
Typo, "lables" should be "labels"
> 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?
You have done it:-)
> --
> FFmpeg = Fundamentalist and Faithful Mere Powerful Empowered Gigant
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
More information about the ffmpeg-devel
mailing list