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
14Libavfilter is the filtering API of Libav. It is the substitute of the
15now deprecated 'vhooks' and started as a Google Summer of Code project.
16
17But note that there may still be serious bugs in the code and its API
18and ABI should not be considered stable yet!
19
20@chapter Tutorial
21
22In libavfilter, it is possible for filters to have multiple inputs and
23multiple outputs.
24To illustrate the sorts of things that are possible, we can
25use a complex filter graph. For example, the following one:
26
27@example
28input --> split --> fifo -----------------------> overlay --> output
29            |                                        ^
30            |                                        |
31            +------> fifo --> crop --> vflip --------+
32@end example
33
34splits the stream in two streams, sends one stream through the crop filter
35and the vflip filter before merging it back with the other stream by
36overlaying it on top. You can use the following command to achieve this:
37
38@example
39./avconv -i input -vf "[in] split [T1], fifo, [T2] overlay=0:H/2 [out]; [T1] fifo, crop=iw:ih/2:0:ih/2, vflip [T2]" output
40@end example
41
42The result will be that in output the top half of the video is mirrored
43onto the bottom half.
44
45Video filters are loaded using the @var{-vf} option passed to
46avconv or to avplay. Filters in the same linear chain are separated by
47commas. In our example, @var{split, fifo, overlay} are in one linear
48chain, and @var{fifo, crop, vflip} are in another. The points where
49the linear chains join are labeled by names enclosed in square
50brackets. In our example, that is @var{[T1]} and @var{[T2]}. The magic
51labels @var{[in]} and @var{[out]} are the points where video is input
52and output.
53
54Some filters take in input a list of parameters: they are specified
55after the filter name and an equal sign, and are separated each other
56by a semicolon.
57
58There exist so-called @var{source filters} that do not have a video
59input, and we expect in the future some @var{sink filters} that will
60not have video output.
61
62@chapter graph2dot
63
64The @file{graph2dot} program included in the Libav @file{tools}
65directory can be used to parse a filter graph description and issue a
66corresponding textual representation in the dot language.
67
68Invoke the command:
69@example
70graph2dot -h
71@end example
72
73to see how to use @file{graph2dot}.
74
75You can then pass the dot description to the @file{dot} program (from
76the graphviz suite of programs) and obtain a graphical representation
77of the filter graph.
78
79For example the sequence of commands:
80@example
81echo @var{GRAPH_DESCRIPTION} | \
82tools/graph2dot -o graph.tmp && \
83dot -Tpng graph.tmp -o graph.png && \
84display graph.png
85@end example
86
87can be used to create and display an image representing the graph
88described by the @var{GRAPH_DESCRIPTION} string.
89
90@include filters.texi
91
92@bye
93