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 Libav. 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 Libav 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.libav.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 avplay.
  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 avplay. 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 Libav @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