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