f934082d9a008dae9a66a5bc2326e862137485e3
[ffmpeg.git] / doc / filters.texi
1 @chapter Audio Filters
2 @c man begin AUDIO FILTERS
3
4 When you configure your FFmpeg build, you can disable any of the
5 existing filters using --disable-filters.
6 The configure output will show the audio filters included in your
7 build.
8
9 Below is a description of the currently available audio filters.
10
11 @section anull
12
13 Pass the audio source unchanged to the output.
14
15 @c man end AUDIO FILTERS
16
17 @chapter Video Filters
18 @c man begin VIDEO FILTERS
19
20 When you configure your FFmpeg build, you can disable any of the
21 existing filters using --disable-filters.
22 The configure output will show the video filters included in your
23 build.
24
25 Below is a description of the currently available video filters.
26
27 @section crop
28
29 Crop the input video to @var{width}:@var{height}:@var{x}:@var{y}.
30
31 @example
32 ./ffmpeg -i in.avi -vf "crop=0:240:0:0" out.avi
33 @end example
34
35 The @var{width} and @var{height} parameters specify the width and height
36 of the output (non-cropped) area.
37
38 A value of 0 is interpreted as the maximum possible size contained in
39 the area delimited by the top-left corner at position x:y.
40
41 @var{x} and @var{y} specify the position of the top-left corner of the
42 output (non-cropped) area.
43
44 The default value of @var{x} and @var{y} is 0.
45
46 For example the parameters:
47
48 @example
49 "crop=0:0:100:100"
50 @end example
51
52 will delimit the rectangle with the top-left corner placed at position
53 100:100 and the right-bottom corner corresponding to the right-bottom
54 corner of the input image.
55
56 The default value of @var{width} and @var{height} is 0.
57
58 @section fifo
59
60 Buffer input images and send them when they are requested.
61
62 This filter is mainly useful when auto-inserted by the libavfilter
63 framework.
64
65 The filter does not take parameters.
66
67 @section format
68
69 Convert the input video to one of the specified pixel formats.
70 Libavfilter will try to pick one that is supported for the input to
71 the next filter.
72
73 The filter accepts a list of pixel format names, separated by ":",
74 for example "yuv420p:monow:rgb24".
75
76 The following command:
77
78 @example
79 ./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
80 @end example
81
82 will convert the input video to the format "yuv420p".
83
84 @section frei0r
85
86 Apply a frei0r effect to the input video.
87
88 To enable compilation of this filter you need to install the frei0r
89 header and configure FFmpeg with --enable-frei0r.
90
91 The filter supports the syntax:
92 @example
93 @var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
94 @end example
95
96 @var{filter_name} is the name to the frei0r effect to load. If the
97 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
98 is searched in each one of the directories specified by the colon
99 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
100 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
101 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
102
103 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
104 for the frei0r effect.
105
106 A frei0r effect parameter can be a boolean (whose values are specified
107 with "y" and "n"), a double, a color (specified by the syntax
108 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
109 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
110 description), a position (specified by the syntax @var{X}/@var{Y},
111 @var{X} and @var{Y} being float numbers) and a string.
112
113 The number and kind of parameters depend on the loaded effect. If an
114 effect parameter is not specified the default value is set.
115
116 Some examples follow:
117 @example
118 # apply the distort0r effect, set the first two double parameters
119 frei0r=distort0r:0.5:0.01
120
121 # apply the colordistance effect, takes a color as first parameter
122 frei0r=colordistance:0.2/0.3/0.4
123 frei0r=colordistance:violet
124 frei0r=colordistance:0x112233
125
126 # apply the perspective effect, specify the top left and top right
127 # image positions
128 frei0r=perspective:0.2/0.2:0.8/0.2
129 @end example
130
131 For more information see:
132 @url{http://piksel.org/frei0r}
133
134 @section hflip
135
136 Flip the input video horizontally.
137
138 For example to horizontally flip the video in input with
139 @file{ffmpeg}:
140 @example
141 ffmpeg -i in.avi -vf "hflip" out.avi
142 @end example
143
144 @section noformat
145
146 Force libavfilter not to use any of the specified pixel formats for the
147 input to the next filter.
148
149 The filter accepts a list of pixel format names, separated by ":",
150 for example "yuv420p:monow:rgb24".
151
152 The following command:
153
154 @example
155 ./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
156 @end example
157
158 will make libavfilter use a format different from "yuv420p" for the
159 input to the vflip filter.
160
161 @section null
162
163 Pass the video source unchanged to the output.
164
165 @section ocv_smooth
166
167 Apply smooth transform using libopencv.
168
169 To enable this filter install libopencv library and headers and
170 configure FFmpeg with --enable-libopencv.
171
172 The filter accepts the following parameters:
173 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
174
175 @var{type} is the type of smooth filter to apply, and can be one of
176 the following values: "blur", "blur_no_scale", "median", "gaussian",
177 "bilateral". The default value is "gaussian".
178
179 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
180 parameters whose meanings depend on smooth type. @var{param1} and
181 @var{param2} accept integer positive values or 0, @var{param3} and
182 @var{param4} accept float values.
183
184 The default value for @var{param1} is 3, the default value for the
185 other parameters is 0.
186
187 These parameters correspond to the parameters assigned to the
188 libopencv function @code{cvSmooth}. Refer to the official libopencv
189 documentation for the exact meaning of the parameters:
190 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
191
192 @section pad
193
194 Add paddings to the input image, and places the original input at the
195 given coordinates @var{x}, @var{y}.
196
197 It accepts the following parameters:
198 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
199
200 Follows the description of the accepted parameters.
201
202 @table @option
203 @item width, height
204
205 Specify the size of the output image with the paddings added. If the
206 value for @var{width} or @var{height} is 0, the corresponding input size
207 is used for the output.
208
209 The default value of @var{width} and @var{height} is 0.
210
211 @item x, y
212
213 Specify the offsets where to place the input image in the padded area
214 with respect to the top/left border of the output image.
215
216 The default value of @var{x} and @var{y} is 0.
217
218 @item color
219
220 Specify the color of the padded area, it can be the name of a color
221 (case insensitive match) or a 0xRRGGBB[AA] sequence.
222
223 The default value of @var{color} is "black".
224
225 @end table
226
227 @section pixdesctest
228
229 Pixel format descriptor test filter, mainly useful for internal
230 testing. The output video should be equal to the input video.
231
232 For example:
233 @example
234 format=monow, pixdesctest
235 @end example
236
237 can be used to test the monowhite pixel format descriptor definition.
238
239 @section scale
240
241 Scale the input video to @var{width}:@var{height} and/or convert the image format.
242
243 For example the command:
244
245 @example
246 ./ffmpeg -i in.avi -vf "scale=200:100" out.avi
247 @end example
248
249 will scale the input video to a size of 200x100.
250
251 If the input image format is different from the format requested by
252 the next filter, the scale filter will convert the input to the
253 requested format.
254
255 If the value for @var{width} or @var{height} is 0, the respective input
256 size is used for the output.
257
258 If the value for @var{width} or @var{height} is -1, the scale filter will
259 use, for the respective output size, a value that maintains the aspect
260 ratio of the input image.
261
262 The default value of @var{width} and @var{height} is 0.
263
264 @section slicify
265
266 Pass the images of input video on to next video filter as multiple
267 slices.
268
269 @example
270 ./ffmpeg -i in.avi -vf "slicify=32" out.avi
271 @end example
272
273 The filter accepts the slice height as parameter. If the parameter is
274 not specified it will use the default value of 16.
275
276 Adding this in the beginning of filter chains should make filtering
277 faster due to better use of the memory cache.
278
279 @section unsharp
280
281 Sharpen or blur the input video.
282
283 It accepts the following parameters:
284 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
285
286 Negative values for the amount will blur the input video, while positive
287 values will sharpen. All parameters are optional and default to the
288 equivalent of the string '5:5:1.0:0:0:0.0'.
289
290 @table @option
291
292 @item luma_msize_x
293 Set the luma matrix horizontal size. It can be an integer between 3
294 and 13, default value is 5.
295
296 @item luma_msize_y
297 Set the luma matrix vertical size. It can be an integer between 3
298 and 13, default value is 5.
299
300 @item luma_amount
301 Set the luma effect strength. It can be a float number between -2.0
302 and 5.0, default value is 1.0.
303
304 @item chroma_msize_x
305 Set the chroma matrix horizontal size. It can be an integer between 3
306 and 13, default value is 0.
307
308 @item chroma_msize_y
309 Set the chroma matrix vertical size. It can be an integer between 3
310 and 13, default value is 0.
311
312 @item luma_amount
313 Set the chroma effect strength. It can be a float number between -2.0
314 and 5.0, default value is 0.0.
315
316 @end table
317
318 @example
319 # Strong luma sharpen effect parameters
320 unsharp=7:7:2.5
321
322 # Strong blur of both luma and chroma parameters
323 unsharp=7:7:-2:7:7:-2
324
325 # Use the default values with @command{ffmpeg}
326 ./ffmpeg -i in.avi -vf "unsharp" out.mp4
327 @end example
328
329 @section vflip
330
331 Flip the input video vertically.
332
333 @example
334 ./ffmpeg -i in.avi -vf "vflip" out.avi
335 @end example
336
337 @c man end VIDEO FILTERS
338
339 @chapter Video Sources
340 @c man begin VIDEO SOURCES
341
342 Below is a description of the currently available video sources.
343
344 @section buffer
345
346 Buffer video frames, and make them available to the filter chain.
347
348 This source is mainly intended for a programmatic use, in particular
349 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
350
351 It accepts the following parameters:
352 @var{width}:@var{height}:@var{pix_fmt_string}
353
354 All the parameters need to be explicitely defined.
355
356 Follows the list of the accepted parameters.
357
358 @table @option
359
360 @item width, height
361 Specify the width and height of the buffered video frames.
362
363 @item pix_fmt_string
364
365 A string representing the pixel format of the buffered video frames.
366 It may be a number corresponding to a pixel format, or a pixel format
367 name.
368
369 @end table
370
371 For example:
372 @example
373 buffer=320:240:yuv410p
374 @end example
375
376 will instruct the source to accept video frames with size 320x240 and
377 with format "yuv410p". Since the pixel format with name "yuv410p"
378 corresponds to the number 6 (check the enum PixelFormat definition in
379 @file{libavutil/pixfmt.h}), this example corresponds to:
380 @example
381 buffer=320:240:6
382 @end example
383
384 @section color
385
386 Provide an uniformly colored input.
387
388 It accepts the following parameters:
389 @var{color}:@var{frame_size}:@var{frame_rate}
390
391 Follows the description of the accepted parameters.
392
393 @table @option
394
395 @item color
396 Specify the color of the source. It can be the name of a color (case
397 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
398 alpha specifier. The default value is "black".
399
400 @item frame_size
401 Specify the size of the sourced video, it may be a string of the form
402 @var{width}x@var{heigth}, or the name of a size abbreviation. The
403 default value is "320x240".
404
405 @item frame_rate
406 Specify the frame rate of the sourced video, as the number of frames
407 generated per second. It has to be a string in the format
408 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
409 number or a valid video frame rate abbreviation. The default value is
410 "25".
411
412 @end table
413
414 For example the following graph description will generate a red source
415 with an opacity of 0.2, with size "qcif" and a frame rate of 10
416 frames per second, which will be overlayed over the source connected
417 to the pad with identifier "in".
418
419 @example
420 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
421 @end example
422
423 @section nullsrc
424
425 Null video source, never return images. It is mainly useful as a
426 template and to be employed in analysis / debugging tools.
427
428 It accepts as optional parameter a string of the form
429 @var{width}:@var{height}, where @var{width} and @var{height} specify the size of
430 the configured source.
431
432 The default values of @var{width} and @var{height} are respectively 352
433 and 288 (corresponding to the CIF size format).
434
435 @c man end VIDEO SOURCES
436
437 @chapter Video Sinks
438 @c man begin VIDEO SINKS
439
440 Below is a description of the currently available video sinks.
441
442 @section nullsink
443
444 Null video sink, do absolutely nothing with the input video. It is
445 mainly useful as a template and to be employed in analysis / debugging
446 tools.
447
448 @c man end VIDEO SINKS
449