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