| \input texinfo @c -*- texinfo -*- |
| |
| @settitle Libavfilter Documentation |
| @titlepage |
| @center @titlefont{Libavfilter Documentation} |
| @end titlepage |
| |
| @top |
| |
| @contents |
| |
| @chapter Introduction |
| |
| Libavfilter is the filtering API of FFmpeg. It is the substitute of the |
| now deprecated 'vhooks' and started as a Google Summer of Code project. |
| |
| Integrating libavfilter into the main FFmpeg repository is a work in |
| progress. If you wish to try the unfinished development code of |
| libavfilter then check it out from the libavfilter repository into |
| some directory of your choice by: |
| |
| @example |
| svn checkout svn://svn.ffmpeg.org/soc/libavfilter |
| @end example |
| |
| And then read the README file in the top directory to learn how to |
| integrate it into ffmpeg and ffplay. |
| |
| But note that there may still be serious bugs in the code and its API |
| and ABI should not be considered stable yet! |
| |
| @chapter Tutorial |
| |
| 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 filter graph. For example, the following one: |
| |
| @example |
| input --> split --> fifo -----------------------> overlay --> output |
| | ^ |
| | | |
| +------> fifo --> 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 in.avi -s 240x320 -vf "[in] split [T1], fifo, [T2] overlay= 0:240 [out]; [T1] fifo, crop=0:0:-1:240, vflip [T2] |
| @end example |
| |
| where input_video.avi has a vertical resolution of 480 pixels. The |
| result will be that in output the top half of the video is mirrored |
| onto the bottom half. |
| |
| Video filters are loaded using the @var{-vf} option passed to |
| ffmpeg or to ffplay. Filters in the same linear chain are separated by |
| commas. In our example, @var{split, fifo, overlay} are in one linear |
| chain, and @var{fifo, 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 @var{[T1]} and @var{[T2]}. The magic |
| labels @var{[in]} and @var{[out]} are the points where video is input |
| and output. |
| |
| Some filters take in input a list of parameters: they are specified |
| after the filter name and an equal sign, and are separated each other |
| by a semicolon. |
| |
| There exist so-called @var{source filters} that do not have a video |
| input, and we expect in the future some @var{sink filters} that will |
| not have video output. |
| |
| @chapter graph2dot |
| |
| The @file{graph2dot} program included in the FFmpeg @file{tools} |
| directory can be used to parse a filter graph description and issue a |
| corresponding textual representation in the dot language. |
| |
| Invoke the command: |
| @example |
| graph2dot -h |
| @end example |
| |
| to see how to use @file{graph2dot}. |
| |
| You can then pass the dot description to the @file{dot} program (from |
| the graphviz suite of programs) and obtain a graphical representation |
| of the filter graph. |
| |
| For example the sequence of commands: |
| @example |
| echo @var{GRAPH_DESCRIPTION} | \ |
| tools/graph2dot -o graph.tmp && \ |
| dot -Tpng graph.tmp -o graph.png && \ |
| display graph.png |
| @end example |
| |
| can be used to create and display an image representing the graph |
| described by the @var{GRAPH_DESCRIPTION} string. |
| |
| @include filters.texi |
| |
| @bye |