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