Statistics
| Branch: | Revision:

ffmpeg / doc / libavfilter.texi @ fc8b1075

History | View | Annotate | Download (7.27 KB)

1 1f09ab5e Stefano Sabatini
\input texinfo @c -*- texinfo -*-
2
3 dba755fa Stefano Sabatini
@settitle Libavfilter Documentation
4 1f09ab5e Stefano Sabatini
@titlepage
5
@sp 7
6 dba755fa Stefano Sabatini
@center @titlefont{Libavfilter Documentation}
7 1f09ab5e Stefano Sabatini
@sp 3
8
@end titlepage
9
10
11
@chapter Introduction
12
13
Libavfilter is the filtering API of FFmpeg. It is the substitute of the
14
now deprecated 'vhooks' and started as a Google Summer of Code project.
15
16
Integrating libavfilter into the main FFmpeg repository is a work in
17
progress. If you wish to try the unfinished development code of
18
libavfilter then check it out from the libavfilter repository into
19
some directory of your choice by:
20
21
@example
22
   svn checkout svn://svn.ffmpeg.org/soc/libavfilter
23
@end example
24
25
And then read the README file in the top directory to learn how to
26
integrate it into ffmpeg and ffplay.
27
28
But note that there may still be serious bugs in the code and its API
29
and ABI should not be considered stable yet!
30
31 f6112d7f Stefano Sabatini
@chapter Tutorial
32
33 1f09ab5e Stefano Sabatini
In libavfilter, it is possible for filters to have multiple inputs and
34
multiple outputs.
35
To illustrate the sorts of things that are possible, we can
36
use a complex filter graph. For example, the following one:
37
38
@example
39
input --> split --> fifo -----------------------> overlay --> output
40
            |                                        ^
41
            |                                        |
42
            +------> fifo --> crop --> vflip --------+
43
@end example
44
45
splits the stream in two streams, sends one stream through the crop filter
46
and the vflip filter before merging it back with the other stream by
47
overlaying it on top. You can use the following command to achieve this:
48
49
@example
50
./ffmpeg -i in.avi -s 240x320 -vfilters "[in] split [T1], fifo, [T2] overlay= 0:240 [out]; [T1] fifo, crop=0:0:-1:240, vflip [T2]
51
@end example
52
53
where input_video.avi has a vertical resolution of 480 pixels. The
54
result will be that in output the top half of the video is mirrored
55
onto the bottom half.
56
57
Video filters are loaded using the @var{-vfilters} option passed to
58
ffmpeg or to ffplay. Filters in the same linear chain are separated by
59
commas. In our example, @var{split, fifo, overlay} are in one linear
60
chain, and @var{fifo, crop, vflip} are in another. The points where
61
the linear chains join are labeled by names enclosed in square
62
brackets. In our example, that is @var{[T1]} and @var{[T2]}. The magic
63
labels @var{[in]} and @var{[out]} are the points where video is input
64
and output.
65
66
Some filters take in input a list of parameters: they are specified
67
after the filter name and an equal sign, and are separated each other
68
by a semicolon.
69
70
There exist so-called @var{source filters} that do not have a video
71
input, and we expect in the future some @var{sink filters} that will
72
not have video output.
73
74 11ab237e Stefano Sabatini
@chapter graph2dot
75
76
The @file{graph2dot} program included in the FFmpeg @file{tools}
77
directory can be used to parse a filter graph description and issue a
78
corresponding textual representation in the dot language.
79
80
Invoke the command:
81
@example
82
graph2dot -h
83
@end example
84
85
to see how to use @file{graph2dot}.
86
87
You can then pass the dot description to the @file{dot} program (from
88
the graphviz suite of programs) and obtain a graphical representation
89
of the filter graph.
90
91
For example the sequence of commands:
92
@example
93
echo @var{GRAPH_DESCRIPTION} | \
94
tools/graph2dot -o graph.tmp && \
95
dot -Tpng graph.tmp -o graph.png && \
96
display graph.png
97
@end example
98
99
can be used to create and display an image representing the graph
100
described by the @var{GRAPH_DESCRIPTION} string.
101
102 1f09ab5e Stefano Sabatini
@chapter Available video filters
103
104
When you configure your FFmpeg build, you can disable any of the
105
existing video filters.
106
The configure output will show the video filters included in your
107
build.
108
109
Below is a description of the currently available video filters.
110
111 190c1669 Stefano Sabatini
@section crop
112
113
Crop the input video to x:y:width:height.
114
115
@example
116
./ffmpeg -i in.avi -vfilters "crop=0:0:0:240" out.avi
117
@end example
118
119
``x'' and ``y'' specify the position of the top-left corner of the
120
output (non-cropped) area.
121
122
The default value of ``x'' and ``y'' is 0.
123
124 debfab4a Stefano Sabatini
The ``width'' and ``height'' parameters specify the width and height
125
of the output (non-cropped) area.
126 190c1669 Stefano Sabatini
127
A value of 0 is interpreted as the maximum possible size contained in
128
the area delimited by the top-left corner at position x:y.
129
130
For example the parameters:
131
132
@example
133
"crop=100:100:0:0"
134
@end example
135
136
will delimit the rectangle with the top-left corner placed at position
137
100:100 and the right-bottom corner corresponding to the right-bottom
138
corner of the input image.
139
140 29b5a3aa Stefano Sabatini
The default value of ``width'' and ``height'' is 0.
141 190c1669 Stefano Sabatini
142 fcbed3c7 Stefano Sabatini
@section format
143
144
Convert the input video to one of the specified pixel formats.
145 143e3aa0 Stefano Sabatini
Libavfilter will try to pick one that is supported for the input to
146 fcbed3c7 Stefano Sabatini
the next filter.
147
148 143e3aa0 Stefano Sabatini
The filter accepts a list of pixel format names, separated by ``:'',
149
for example ``yuv420p:monow:rgb24''.
150 fcbed3c7 Stefano Sabatini
151
The following command:
152
153
@example
154
./ffmpeg -i in.avi -vfilters "format=yuv420p" out.avi
155
@end example
156
157
will convert the input video to the format ``yuv420p''.
158
159
@section noformat
160
161 143e3aa0 Stefano Sabatini
Force libavfilter not to use any of the specified pixel formats for the
162 fcbed3c7 Stefano Sabatini
input to the next filter.
163
164 143e3aa0 Stefano Sabatini
The filter accepts a list of pixel format names, separated by ``:'',
165
for example ``yuv420p:monow:rgb24''.
166 fcbed3c7 Stefano Sabatini
167
The following command:
168
169
@example
170
./ffmpeg -i in.avi -vfilters "noformat=yuv420p, vflip" out.avi
171
@end example
172
173 143e3aa0 Stefano Sabatini
will make libavfilter use a format different from ``yuv420p'' for the
174 fcbed3c7 Stefano Sabatini
input to the vflip filter.
175
176 415e6d29 Stefano Sabatini
@section null
177
178
Pass the source unchanged to the output.
179
180 c3eabb7d Stefano Sabatini
@section scale
181
182
Scale the input video to width:height and/or convert the image format.
183
184
For example the command:
185
186
@example
187
./ffmpeg -i in.avi -vfilters "scale=200:100" out.avi
188
@end example
189
190
will scale the input video to a size of 200x100.
191
192
If the input image format is different from the format requested by
193
the next filter, the scale filter will convert the input to the
194
requested format.
195
196
If the value for ``width'' or ``height'' is 0, the respective input
197
size is used for the output.
198
199
If the value for ``width'' or ``height'' is -1, the scale filter will
200
use, for the respective output size, a value that maintains the aspect
201
ratio of the input image.
202
203
The default value of ``width'' and ``height'' is 0.
204
205 0c0ccc28 Stefano Sabatini
@section slicify
206
207
Pass the images of input video on to next video filter as multiple
208
slices.
209
210
@example
211
./ffmpeg -i in.avi -vfilters "slicify=32" out.avi
212
@end example
213
214
The filter accepts the slice height as parameter. If the parameter is
215
not specified it will use the default value of 16.
216
217
Adding this in the beginning of filter chains should make filtering
218
faster due to better use of the memory cache.
219
220 c38ae71f Stefano Sabatini
@section vflip
221
222
Flip the input video vertically.
223
224
@example
225
./ffmpeg -i in.avi -vfilters "vflip" out.avi
226
@end example
227
228 dd08b83c Stefano Sabatini
@chapter Available video sources
229
230
Below is a description of the currently available video sources.
231
232
@section nullsrc
233
234
Null video source, never return images. It is mainly useful as a
235
template and to be employed in analysis / debugging tools.
236
237
It accepts as optional parameter a string of the form
238
``width:height'', where ``width'' and ``height'' specify the size of
239
the configured source.
240
241
The default values of ``width'' and ``height'' are respectively 352
242
and 288 (corresponding to the CIF size format).
243
244 006aa1a4 Stefano Sabatini
@chapter Available video sinks
245
246
Below is a description of the currently available video sinks.
247
248
@section nullsink
249
250
Null video sink, do absolutely nothing with the input video. It is
251
mainly useful as a template and to be employed in analysis / debugging
252
tools.
253
254 1f09ab5e Stefano Sabatini
@bye