Revert "replace FFmpeg with Libav in doc/"
[ffmpeg.git] / doc / libavfilter.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle Libavfilter Documentation
4 @titlepage
5 @center @titlefont{Libavfilter Documentation}
6 @end titlepage
7
8 @top
9
10 @contents
11
12 @chapter Introduction
13
14 Libavfilter is the filtering API of FFmpeg. It is the substitute of the
15 now deprecated 'vhooks' and started as a Google Summer of Code project.
16
17 Integrating libavfilter into the main FFmpeg repository is a work in
18 progress. If you wish to try the unfinished development code of
19 libavfilter then check it out from the libavfilter repository into
20 some directory of your choice by:
21
22 @example
23    svn checkout svn://svn.ffmpeg.org/soc/libavfilter
24 @end example
25
26 And then read the README file in the top directory to learn how to
27 integrate it into ffmpeg and ffplay.
28
29 But note that there may still be serious bugs in the code and its API
30 and ABI should not be considered stable yet!
31
32 @chapter Tutorial
33
34 In libavfilter, it is possible for filters to have multiple inputs and
35 multiple outputs.
36 To illustrate the sorts of things that are possible, we can
37 use a complex filter graph. For example, the following one:
38
39 @example
40 input --> split --> fifo -----------------------> overlay --> output
41             |                                        ^
42             |                                        |
43             +------> fifo --> crop --> vflip --------+
44 @end example
45
46 splits the stream in two streams, sends one stream through the crop filter
47 and the vflip filter before merging it back with the other stream by
48 overlaying it on top. You can use the following command to achieve this:
49
50 @example
51 ./ffmpeg -i in.avi -s 240x320 -vf "[in] split [T1], fifo, [T2] overlay= 0:240 [out]; [T1] fifo, crop=0:0:-1:240, vflip [T2]
52 @end example
53
54 where input_video.avi has a vertical resolution of 480 pixels. The
55 result will be that in output the top half of the video is mirrored
56 onto the bottom half.
57
58 Video filters are loaded using the @var{-vf} option passed to
59 ffmpeg or to ffplay. Filters in the same linear chain are separated by
60 commas. In our example, @var{split, fifo, overlay} are in one linear
61 chain, and @var{fifo, crop, vflip} are in another. The points where
62 the linear chains join are labeled by names enclosed in square
63 brackets. In our example, that is @var{[T1]} and @var{[T2]}. The magic
64 labels @var{[in]} and @var{[out]} are the points where video is input
65 and output.
66
67 Some filters take in input a list of parameters: they are specified
68 after the filter name and an equal sign, and are separated each other
69 by a semicolon.
70
71 There exist so-called @var{source filters} that do not have a video
72 input, and we expect in the future some @var{sink filters} that will
73 not have video output.
74
75 @chapter graph2dot
76
77 The @file{graph2dot} program included in the FFmpeg @file{tools}
78 directory can be used to parse a filter graph description and issue a
79 corresponding textual representation in the dot language.
80
81 Invoke the command:
82 @example
83 graph2dot -h
84 @end example
85
86 to see how to use @file{graph2dot}.
87
88 You can then pass the dot description to the @file{dot} program (from
89 the graphviz suite of programs) and obtain a graphical representation
90 of the filter graph.
91
92 For example the sequence of commands:
93 @example
94 echo @var{GRAPH_DESCRIPTION} | \
95 tools/graph2dot -o graph.tmp && \
96 dot -Tpng graph.tmp -o graph.png && \
97 display graph.png
98 @end example
99
100 can be used to create and display an image representing the graph
101 described by the @var{GRAPH_DESCRIPTION} string.
102
103 @include filters.texi
104
105 @bye