Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ 16134b7c

History | View | Annotate | Download (18.3 KB)

1 f59e9eaf Stefano Sabatini
@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 99046339 S.N. Hemanth Meenakshisundaram
@section anull
12
13
Pass the audio source unchanged to the output.
14
15 f59e9eaf Stefano Sabatini
@c man end AUDIO FILTERS
16
17 1ee410f3 Stefano Sabatini
@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 6ef93402 Stefano Sabatini
@file{libavcodec/audioconvert.c} for the mapping between strings and
38
channel layout values.
39 1ee410f3 Stefano Sabatini
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 f0a55438 S.N. Hemanth Meenakshisundaram
@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 3275ac6a Stefano Sabatini
@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 13fabd7a Stefano Sabatini
@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 3275ac6a Stefano Sabatini
@section crop
96
97 75b67a8a Stefano Sabatini
Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
98 3275ac6a Stefano Sabatini
99 75b67a8a Stefano Sabatini
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 3275ac6a Stefano Sabatini
131 75b67a8a Stefano Sabatini
@end table
132 3275ac6a Stefano Sabatini
133 75b67a8a Stefano Sabatini
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 3275ac6a Stefano Sabatini
137 75b67a8a Stefano Sabatini
The default value of @var{out_w} is "in_w", and the default value of
138
@var{out_h} is "in_h".
139 2bc05d35 Stefano Sabatini
140 75b67a8a Stefano Sabatini
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 2bc05d35 Stefano Sabatini
145 75b67a8a Stefano Sabatini
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 3275ac6a Stefano Sabatini
150 75b67a8a Stefano Sabatini
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 3275ac6a Stefano Sabatini
@example
159 75b67a8a Stefano Sabatini
# 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 3275ac6a Stefano Sabatini
173 75b67a8a Stefano Sabatini
# 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 3275ac6a Stefano Sabatini
177 75b67a8a Stefano Sabatini
# 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 3275ac6a Stefano Sabatini
193 e40032e2 Stefano Sabatini
@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 7f1af825 Stefano Sabatini
@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 3275ac6a Stefano Sabatini
@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 b1094275 Stefano Sabatini
The filter accepts a list of pixel format names, separated by ":",
241
for example "yuv420p:monow:rgb24".
242 3275ac6a Stefano Sabatini
243
The following command:
244
245
@example
246
./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
247
@end example
248
249 b1094275 Stefano Sabatini
will convert the input video to the format "yuv420p".
250 3275ac6a Stefano Sabatini
251 47941088 Stefano Sabatini
@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 a1e171df Stefano Sabatini
@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 3275ac6a Stefano Sabatini
@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 b1094275 Stefano Sabatini
The filter accepts a list of pixel format names, separated by ":",
317
for example "yuv420p:monow:rgb24".
318 3275ac6a Stefano Sabatini
319
The following command:
320
321
@example
322
./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
323
@end example
324
325 b1094275 Stefano Sabatini
will make libavfilter use a format different from "yuv420p" for the
326 3275ac6a Stefano Sabatini
input to the vflip filter.
327
328
@section null
329
330 99046339 S.N. Hemanth Meenakshisundaram
Pass the video source unchanged to the output.
331 3275ac6a Stefano Sabatini
332 6ebf0bfc Stefano Sabatini
@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 58d94364 Stefano Sabatini
The filter accepts the following parameters:
340 6ebf0bfc Stefano Sabatini
@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 58d94364 Stefano Sabatini
the following values: "blur", "blur_no_scale", "median", "gaussian",
344 6ebf0bfc Stefano Sabatini
"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 58d94364 Stefano Sabatini
These parameters correspond to the parameters assigned to the
355
libopencv function @code{cvSmooth}. Refer to the official libopencv
356 6ebf0bfc Stefano Sabatini
documentation for the exact meaning of the parameters:
357
@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
358
359 3275ac6a Stefano Sabatini
@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 b1094275 Stefano Sabatini
The default value of @var{color} is "black".
391 3275ac6a Stefano Sabatini
392
@end table
393
394 ce2e4ae3 Stefano Sabatini
@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 3275ac6a Stefano Sabatini
@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 214c0d42 Stefano Sabatini
@section settb
432
433
Set the timebase to use for the output frames timestamps.
434
It is mainly useful for testing timebase configuration.
435
436
It accepts in input an arithmetic expression representing a rational.
437
The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
438
default timebase), and "intb" (the input timebase).
439
440
The default value for the input is "intb".
441
442
Follow some examples.
443
444
@example
445
# set the timebase to 1/25
446
settb=1/25
447
448
# set the timebase to 1/10
449
settb=0.1
450
451
#set the timebase to 1001/1000
452
settb=1+0.001
453
454
#set the timebase to 2*intb
455
settb=2*intb
456
457
#set the default timebase value
458
settb=AVTB
459
@end example
460
461 3275ac6a Stefano Sabatini
@section slicify
462
463
Pass the images of input video on to next video filter as multiple
464
slices.
465
466
@example
467
./ffmpeg -i in.avi -vf "slicify=32" out.avi
468
@end example
469
470
The filter accepts the slice height as parameter. If the parameter is
471
not specified it will use the default value of 16.
472
473
Adding this in the beginning of filter chains should make filtering
474
faster due to better use of the memory cache.
475
476
@section unsharp
477
478 843b5fd0 Stefano Sabatini
Sharpen or blur the input video.
479
480
It accepts the following parameters:
481
@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
482 3275ac6a Stefano Sabatini
483
Negative values for the amount will blur the input video, while positive
484
values will sharpen. All parameters are optional and default to the
485
equivalent of the string '5:5:1.0:0:0:0.0'.
486
487
@table @option
488
489
@item luma_msize_x
490
Set the luma matrix horizontal size. It can be an integer between 3
491
and 13, default value is 5.
492
493
@item luma_msize_y
494
Set the luma matrix vertical size. It can be an integer between 3
495
and 13, default value is 5.
496
497
@item luma_amount
498
Set the luma effect strength. It can be a float number between -2.0
499
and 5.0, default value is 1.0.
500
501
@item chroma_msize_x
502
Set the chroma matrix horizontal size. It can be an integer between 3
503
and 13, default value is 0.
504
505
@item chroma_msize_y
506
Set the chroma matrix vertical size. It can be an integer between 3
507
and 13, default value is 0.
508
509
@item luma_amount
510
Set the chroma effect strength. It can be a float number between -2.0
511
and 5.0, default value is 0.0.
512
513
@end table
514
515
@example
516
# Strong luma sharpen effect parameters
517
unsharp=7:7:2.5
518
519
# Strong blur of both luma and chroma parameters
520
unsharp=7:7:-2:7:7:-2
521
522
# Use the default values with @command{ffmpeg}
523
./ffmpeg -i in.avi -vf "unsharp" out.mp4
524
@end example
525
526
@section vflip
527
528
Flip the input video vertically.
529
530
@example
531
./ffmpeg -i in.avi -vf "vflip" out.avi
532
@end example
533
534 acbac567 Michael Niedermayer
@section yadif
535
536
yadif is "yet another deinterlacing filter".
537
538
It accepts the syntax:
539
@example
540
yadif=[@var{mode}[:@var{parity}]]
541
@end example
542
543
@table @option
544
545
@item mode
546
Specify the interlacing mode to adopt, accepts one of the following values.
547
548
0: Output 1 frame for each frame.
549
550
1: Output 1 frame for each field.
551
552
2: Like 0 but skips spatial interlacing check.
553
554
3: Like 1 but skips spatial interlacing check.
555
556
Default value is 0.
557
558
@item parity
559
0 if is bottom field first, 1 if the interlaced video is top field
560
first, -1 to enable automatic detection.
561
562
@end table
563
564 3275ac6a Stefano Sabatini
@c man end VIDEO FILTERS
565
566
@chapter Video Sources
567
@c man begin VIDEO SOURCES
568
569
Below is a description of the currently available video sources.
570
571 24413399 Stefano Sabatini
@section buffer
572
573
Buffer video frames, and make them available to the filter chain.
574
575
This source is mainly intended for a programmatic use, in particular
576 ac1a31ab VĂ­ctor Paesa
through the interface defined in @file{libavfilter/vsrc_buffer.h}.
577 24413399 Stefano Sabatini
578
It accepts the following parameters:
579
@var{width}:@var{height}:@var{pix_fmt_string}
580
581
All the parameters need to be explicitely defined.
582
583
Follows the list of the accepted parameters.
584
585
@table @option
586
587
@item width, height
588
Specify the width and height of the buffered video frames.
589
590
@item pix_fmt_string
591
592
A string representing the pixel format of the buffered video frames.
593
It may be a number corresponding to a pixel format, or a pixel format
594
name.
595
596
@end table
597
598
For example:
599
@example
600
buffer=320:240:yuv410p
601
@end example
602
603
will instruct the source to accept video frames with size 320x240 and
604
with format "yuv410p". Since the pixel format with name "yuv410p"
605
corresponds to the number 6 (check the enum PixelFormat definition in
606
@file{libavutil/pixfmt.h}), this example corresponds to:
607
@example
608
buffer=320:240:6
609
@end example
610
611 23ccf3c7 Stefano Sabatini
@section color
612
613
Provide an uniformly colored input.
614
615
It accepts the following parameters:
616 b5f47309 Stefano Sabatini
@var{color}:@var{frame_size}:@var{frame_rate}
617 23ccf3c7 Stefano Sabatini
618
Follows the description of the accepted parameters.
619
620
@table @option
621
622
@item color
623
Specify the color of the source. It can be the name of a color (case
624
insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
625
alpha specifier. The default value is "black".
626
627
@item frame_size
628
Specify the size of the sourced video, it may be a string of the form
629
@var{width}x@var{heigth}, or the name of a size abbreviation. The
630
default value is "320x240".
631
632
@item frame_rate
633
Specify the frame rate of the sourced video, as the number of frames
634
generated per second. It has to be a string in the format
635
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
636
number or a valid video frame rate abbreviation. The default value is
637
"25".
638
639
@end table
640
641
For example the following graph description will generate a red source
642
with an opacity of 0.2, with size "qcif" and a frame rate of 10
643
frames per second, which will be overlayed over the source connected
644
to the pad with identifier "in".
645
646
@example
647
"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
648
@end example
649
650 3275ac6a Stefano Sabatini
@section nullsrc
651
652
Null video source, never return images. It is mainly useful as a
653
template and to be employed in analysis / debugging tools.
654
655
It accepts as optional parameter a string of the form
656 16134b7c Stefano Sabatini
@var{width}:@var{height}:@var{timebase}.
657 3275ac6a Stefano Sabatini
658 16134b7c Stefano Sabatini
@var{width} and @var{height} specify the size of the configured
659
source. The default values of @var{width} and @var{height} are
660
respectively 352 and 288 (corresponding to the CIF size format).
661
662
@var{timebase} specifies an arithmetic expression representing a
663
timebase. The expression can contain the constants "PI", "E", "PHI",
664
"AVTB" (the default timebase), and defaults to the value "AVTB".
665 3275ac6a Stefano Sabatini
666
@c man end VIDEO SOURCES
667
668
@chapter Video Sinks
669
@c man begin VIDEO SINKS
670
671
Below is a description of the currently available video sinks.
672
673
@section nullsink
674
675
Null video sink, do absolutely nothing with the input video. It is
676
mainly useful as a template and to be employed in analysis / debugging
677
tools.
678
679
@c man end VIDEO SINKS