Statistics
| Branch: | Revision:

ffmpeg / doc / libavfilter.texi @ 168b441e

History | View | Annotate | Download (9.52 KB)

1
\input texinfo @c -*- texinfo -*-
2

    
3
@settitle Libavfilter Documentation
4
@titlepage
5
@sp 7
6
@center @titlefont{Libavfilter Documentation}
7
@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
@chapter Tutorial
32

    
33
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 -vf "[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{-vf} 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
@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
@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
@section crop
112

    
113
Crop the input video to @var{x}:@var{y}:@var{width}:@var{height}.
114

    
115
@example
116
./ffmpeg -i in.avi -vf "crop=0:0:0:240" out.avi
117
@end example
118

    
119
@var{x} and @var{y} specify the position of the top-left corner of the
120
output (non-cropped) area.
121

    
122
The default value of @var{x} and @var{y} is 0.
123

    
124
The @var{width} and @var{height} parameters specify the width and height
125
of the output (non-cropped) area.
126

    
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
The default value of @var{width} and @var{height} is 0.
141

    
142
@section format
143

    
144
Convert the input video to one of the specified pixel formats.
145
Libavfilter will try to pick one that is supported for the input to
146
the next filter.
147

    
148
The filter accepts a list of pixel format names, separated by ``:'',
149
for example ``yuv420p:monow:rgb24''.
150

    
151
The following command:
152

    
153
@example
154
./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
155
@end example
156

    
157
will convert the input video to the format ``yuv420p''.
158

    
159
@section noformat
160

    
161
Force libavfilter not to use any of the specified pixel formats for the
162
input to the next filter.
163

    
164
The filter accepts a list of pixel format names, separated by ``:'',
165
for example ``yuv420p:monow:rgb24''.
166

    
167
The following command:
168

    
169
@example
170
./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
171
@end example
172

    
173
will make libavfilter use a format different from ``yuv420p'' for the
174
input to the vflip filter.
175

    
176
@section null
177

    
178
Pass the source unchanged to the output.
179

    
180
@section pad
181

    
182
Add paddings to the input image, and places the original input at the
183
given coordinates @var{x}, @var{y}.
184

    
185
It accepts the following parameters:
186
@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
187

    
188
Follows the description of the accepted parameters.
189

    
190
@table @option
191
@item width, height
192

    
193
Specify the size of the output image with the paddings added. If the
194
value for @var{width} or @var{height} is 0, the corresponding input size
195
is used for the output.
196

    
197
The default value of @var{width} and @var{height} is 0.
198

    
199
@item x, y
200

    
201
Specify the offsets where to place the input image in the padded area
202
with respect to the top/left border of the output image.
203

    
204
The default value of @var{x} and @var{y} is 0.
205

    
206
@item color
207

    
208
Specify the color of the padded area, it can be the name of a color
209
(case insensitive match) or a 0xRRGGBB[AA] sequence.
210

    
211
The default value of @var{color} is ``black''.
212

    
213
@end table
214

    
215
@section scale
216

    
217
Scale the input video to @var{width}:@var{height} and/or convert the image format.
218

    
219
For example the command:
220

    
221
@example
222
./ffmpeg -i in.avi -vf "scale=200:100" out.avi
223
@end example
224

    
225
will scale the input video to a size of 200x100.
226

    
227
If the input image format is different from the format requested by
228
the next filter, the scale filter will convert the input to the
229
requested format.
230

    
231
If the value for @var{width} or @var{height} is 0, the respective input
232
size is used for the output.
233

    
234
If the value for @var{width} or @var{height} is -1, the scale filter will
235
use, for the respective output size, a value that maintains the aspect
236
ratio of the input image.
237

    
238
The default value of @var{width} and @var{height} is 0.
239

    
240
@section slicify
241

    
242
Pass the images of input video on to next video filter as multiple
243
slices.
244

    
245
@example
246
./ffmpeg -i in.avi -vf "slicify=32" out.avi
247
@end example
248

    
249
The filter accepts the slice height as parameter. If the parameter is
250
not specified it will use the default value of 16.
251

    
252
Adding this in the beginning of filter chains should make filtering
253
faster due to better use of the memory cache.
254

    
255
@section unsharp
256

    
257
Sharpen or blur the input video.
258

    
259
It accepts the following parameters:
260
@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
261

    
262
@table @option
263

    
264
@item luma_msize_x
265
Set the luma matrix horizontal size. It can be an integer between 3
266
and 13, default value is 5.
267

    
268
@item luma_msize_y
269
Set the luma matrix vertical size. It can be an integer between 3
270
and 13, default value is 5.
271

    
272
@item luma_amount
273
Set the luma effect strength. It can be a float number between -2.0
274
and 5.0, default value is 1.0.
275

    
276
@item chroma_msize_x
277
Set the chroma matrix horizontal size. It can be an integer between 3
278
and 13, default value is 0.
279

    
280
@item chroma_msize_y
281
Set the chroma matrix vertical size. It can be an integer between 3
282
and 13, default value is 0.
283

    
284
@item chroma_amount
285
Set the chroma effect strength. It can be a float number between -2.0
286
and 5.0, default value is 0.0.
287

    
288
@end table
289

    
290
Negative values for the amount will blur the input video, while positive
291
values will sharpen. All parameters are optional and default to the
292
equivalent of the string '5:5:1.0:0:0:0.0'.
293

    
294
@example
295
# Strong luma sharpen effect parameters
296
unsharp=7:7:2.5
297

    
298
# Strong blur of both luma and chroma parameters
299
unsharp=7:7:-2:7:7:-2
300

    
301
# Use the default values with @command{ffmpeg}
302
./ffmpeg -i in.avi -vf "unsharp" out.mp4
303
@end example
304

    
305
@section vflip
306

    
307
Flip the input video vertically.
308

    
309
@example
310
./ffmpeg -i in.avi -vf "vflip" out.avi
311
@end example
312

    
313
@chapter Available video sources
314

    
315
Below is a description of the currently available video sources.
316

    
317
@section nullsrc
318

    
319
Null video source, never return images. It is mainly useful as a
320
template and to be employed in analysis / debugging tools.
321

    
322
It accepts as optional parameter a string of the form
323
@var{width}:@var{height}, where @var{width} and @var{height} specify the size of
324
the configured source.
325

    
326
The default values of @var{width} and @var{height} are respectively 352
327
and 288 (corresponding to the CIF size format).
328

    
329
@chapter Available video sinks
330

    
331
Below is a description of the currently available video sinks.
332

    
333
@section nullsink
334

    
335
Null video sink, do absolutely nothing with the input video. It is
336
mainly useful as a template and to be employed in analysis / debugging
337
tools.
338

    
339
@bye