Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ 94498ec9

History | View | Annotate | Download (19.6 KB)

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 cropdetect
194

    
195
Auto-detect crop size.
196

    
197
Calculate necessary cropping parameters and prints the recommended
198
parameters through the logging system. The detected dimensions
199
correspond to the non-black area of the input video.
200

    
201
It accepts the syntax:
202
@example
203
cropdetect[=@var{limit}:@var{round}[:@var{reset}]]
204
@end example
205

    
206
@table @option
207

    
208
@item limit
209
Threshold, which can be optionally specified from nothing (0) to
210
everything (255), defaults to 24.
211

    
212
@item round
213
Value which the width/height should be divisible by, defaults to
214
16. The offset is automatically adjusted to center the video. Use 2 to
215
get only even dimensions (needed for 4:2:2 video). 16 is best when
216
encoding to most video codecs.
217

    
218
@item reset
219
Counter that determines after how many frames cropdetect will reset
220
the previously detected largest video area and start over to detect
221
the current optimal crop area. Defaults to 0.
222

    
223
This can be useful when channel logos distort the video area. 0
224
indicates never reset and return the largest area encountered during
225
playback.
226
@end table
227

    
228
@section drawbox
229

    
230
Draw a colored box on the input image.
231

    
232
It accepts the syntax:
233
@example
234
drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
235
@end example
236

    
237
@table @option
238

    
239
@item x, y
240
Specify the top left corner coordinates of the box. Default to 0.
241

    
242
@item width, height
243
Specify the width and height of the box, if 0 they are interpreted as
244
the input width and height. Default to 0.
245

    
246
@item color
247
Specify the color of the box to write, it can be the name of a color
248
(case insensitive match) or a 0xRRGGBB[AA] sequence.
249
@end table
250

    
251
Follow some examples:
252
@example
253
# draw a black box around the edge of the input image
254
drawbox
255

    
256
# draw a box with color red and an opacity of 50%
257
drawbox=10:20:200:60:red@@0.5"
258
@end example
259

    
260
@section fifo
261

    
262
Buffer input images and send them when they are requested.
263

    
264
This filter is mainly useful when auto-inserted by the libavfilter
265
framework.
266

    
267
The filter does not take parameters.
268

    
269
@section format
270

    
271
Convert the input video to one of the specified pixel formats.
272
Libavfilter will try to pick one that is supported for the input to
273
the next filter.
274

    
275
The filter accepts a list of pixel format names, separated by ":",
276
for example "yuv420p:monow:rgb24".
277

    
278
The following command:
279

    
280
@example
281
./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
282
@end example
283

    
284
will convert the input video to the format "yuv420p".
285

    
286
@section frei0r
287

    
288
Apply a frei0r effect to the input video.
289

    
290
To enable compilation of this filter you need to install the frei0r
291
header and configure FFmpeg with --enable-frei0r.
292

    
293
The filter supports the syntax:
294
@example
295
@var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
296
@end example
297

    
298
@var{filter_name} is the name to the frei0r effect to load. If the
299
environment variable @env{FREI0R_PATH} is defined, the frei0r effect
300
is searched in each one of the directories specified by the colon
301
separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
302
paths, which are in this order: @file{HOME/.frei0r-1/lib/},
303
@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
304

    
305
@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
306
for the frei0r effect.
307

    
308
A frei0r effect parameter can be a boolean (whose values are specified
309
with "y" and "n"), a double, a color (specified by the syntax
310
@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
311
numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
312
description), a position (specified by the syntax @var{X}/@var{Y},
313
@var{X} and @var{Y} being float numbers) and a string.
314

    
315
The number and kind of parameters depend on the loaded effect. If an
316
effect parameter is not specified the default value is set.
317

    
318
Some examples follow:
319
@example
320
# apply the distort0r effect, set the first two double parameters
321
frei0r=distort0r:0.5:0.01
322

    
323
# apply the colordistance effect, takes a color as first parameter
324
frei0r=colordistance:0.2/0.3/0.4
325
frei0r=colordistance:violet
326
frei0r=colordistance:0x112233
327

    
328
# apply the perspective effect, specify the top left and top right
329
# image positions
330
frei0r=perspective:0.2/0.2:0.8/0.2
331
@end example
332

    
333
For more information see:
334
@url{http://piksel.org/frei0r}
335

    
336
@section hflip
337

    
338
Flip the input video horizontally.
339

    
340
For example to horizontally flip the video in input with
341
@file{ffmpeg}:
342
@example
343
ffmpeg -i in.avi -vf "hflip" out.avi
344
@end example
345

    
346
@section noformat
347

    
348
Force libavfilter not to use any of the specified pixel formats for the
349
input to the next filter.
350

    
351
The filter accepts a list of pixel format names, separated by ":",
352
for example "yuv420p:monow:rgb24".
353

    
354
The following command:
355

    
356
@example
357
./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
358
@end example
359

    
360
will make libavfilter use a format different from "yuv420p" for the
361
input to the vflip filter.
362

    
363
@section null
364

    
365
Pass the video source unchanged to the output.
366

    
367
@section ocv_smooth
368

    
369
Apply smooth transform using libopencv.
370

    
371
To enable this filter install libopencv library and headers and
372
configure FFmpeg with --enable-libopencv.
373

    
374
The filter accepts the following parameters:
375
@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
376

    
377
@var{type} is the type of smooth filter to apply, and can be one of
378
the following values: "blur", "blur_no_scale", "median", "gaussian",
379
"bilateral". The default value is "gaussian".
380

    
381
@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
382
parameters whose meanings depend on smooth type. @var{param1} and
383
@var{param2} accept integer positive values or 0, @var{param3} and
384
@var{param4} accept float values.
385

    
386
The default value for @var{param1} is 3, the default value for the
387
other parameters is 0.
388

    
389
These parameters correspond to the parameters assigned to the
390
libopencv function @code{cvSmooth}. Refer to the official libopencv
391
documentation for the exact meaning of the parameters:
392
@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
393

    
394
@section pad
395

    
396
Add paddings to the input image, and places the original input at the
397
given coordinates @var{x}, @var{y}.
398

    
399
It accepts the following parameters:
400
@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
401

    
402
Follows the description of the accepted parameters.
403

    
404
@table @option
405
@item width, height
406

    
407
Specify the size of the output image with the paddings added. If the
408
value for @var{width} or @var{height} is 0, the corresponding input size
409
is used for the output.
410

    
411
The default value of @var{width} and @var{height} is 0.
412

    
413
@item x, y
414

    
415
Specify the offsets where to place the input image in the padded area
416
with respect to the top/left border of the output image.
417

    
418
The default value of @var{x} and @var{y} is 0.
419

    
420
@item color
421

    
422
Specify the color of the padded area, it can be the name of a color
423
(case insensitive match) or a 0xRRGGBB[AA] sequence.
424

    
425
The default value of @var{color} is "black".
426

    
427
@end table
428

    
429
@section pixdesctest
430

    
431
Pixel format descriptor test filter, mainly useful for internal
432
testing. The output video should be equal to the input video.
433

    
434
For example:
435
@example
436
format=monow, pixdesctest
437
@end example
438

    
439
can be used to test the monowhite pixel format descriptor definition.
440

    
441
@section scale
442

    
443
Scale the input video to @var{width}:@var{height} and/or convert the image format.
444

    
445
For example the command:
446

    
447
@example
448
./ffmpeg -i in.avi -vf "scale=200:100" out.avi
449
@end example
450

    
451
will scale the input video to a size of 200x100.
452

    
453
If the input image format is different from the format requested by
454
the next filter, the scale filter will convert the input to the
455
requested format.
456

    
457
If the value for @var{width} or @var{height} is 0, the respective input
458
size is used for the output.
459

    
460
If the value for @var{width} or @var{height} is -1, the scale filter will
461
use, for the respective output size, a value that maintains the aspect
462
ratio of the input image.
463

    
464
The default value of @var{width} and @var{height} is 0.
465

    
466
@section settb
467

    
468
Set the timebase to use for the output frames timestamps.
469
It is mainly useful for testing timebase configuration.
470

    
471
It accepts in input an arithmetic expression representing a rational.
472
The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
473
default timebase), and "intb" (the input timebase).
474

    
475
The default value for the input is "intb".
476

    
477
Follow some examples.
478

    
479
@example
480
# set the timebase to 1/25
481
settb=1/25
482

    
483
# set the timebase to 1/10
484
settb=0.1
485

    
486
#set the timebase to 1001/1000
487
settb=1+0.001
488

    
489
#set the timebase to 2*intb
490
settb=2*intb
491

    
492
#set the default timebase value
493
settb=AVTB
494
@end example
495

    
496
@section slicify
497

    
498
Pass the images of input video on to next video filter as multiple
499
slices.
500

    
501
@example
502
./ffmpeg -i in.avi -vf "slicify=32" out.avi
503
@end example
504

    
505
The filter accepts the slice height as parameter. If the parameter is
506
not specified it will use the default value of 16.
507

    
508
Adding this in the beginning of filter chains should make filtering
509
faster due to better use of the memory cache.
510

    
511
@section unsharp
512

    
513
Sharpen or blur the input video.
514

    
515
It accepts the following parameters:
516
@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
517

    
518
Negative values for the amount will blur the input video, while positive
519
values will sharpen. All parameters are optional and default to the
520
equivalent of the string '5:5:1.0:0:0:0.0'.
521

    
522
@table @option
523

    
524
@item luma_msize_x
525
Set the luma matrix horizontal size. It can be an integer between 3
526
and 13, default value is 5.
527

    
528
@item luma_msize_y
529
Set the luma matrix vertical size. It can be an integer between 3
530
and 13, default value is 5.
531

    
532
@item luma_amount
533
Set the luma effect strength. It can be a float number between -2.0
534
and 5.0, default value is 1.0.
535

    
536
@item chroma_msize_x
537
Set the chroma matrix horizontal size. It can be an integer between 3
538
and 13, default value is 0.
539

    
540
@item chroma_msize_y
541
Set the chroma matrix vertical size. It can be an integer between 3
542
and 13, default value is 0.
543

    
544
@item luma_amount
545
Set the chroma effect strength. It can be a float number between -2.0
546
and 5.0, default value is 0.0.
547

    
548
@end table
549

    
550
@example
551
# Strong luma sharpen effect parameters
552
unsharp=7:7:2.5
553

    
554
# Strong blur of both luma and chroma parameters
555
unsharp=7:7:-2:7:7:-2
556

    
557
# Use the default values with @command{ffmpeg}
558
./ffmpeg -i in.avi -vf "unsharp" out.mp4
559
@end example
560

    
561
@section vflip
562

    
563
Flip the input video vertically.
564

    
565
@example
566
./ffmpeg -i in.avi -vf "vflip" out.avi
567
@end example
568

    
569
@section yadif
570

    
571
yadif is "yet another deinterlacing filter".
572

    
573
It accepts the syntax:
574
@example
575
yadif=[@var{mode}[:@var{parity}]]
576
@end example
577

    
578
@table @option
579

    
580
@item mode
581
Specify the interlacing mode to adopt, accepts one of the following values.
582

    
583
0: Output 1 frame for each frame.
584

    
585
1: Output 1 frame for each field.
586

    
587
2: Like 0 but skips spatial interlacing check.
588

    
589
3: Like 1 but skips spatial interlacing check.
590

    
591
Default value is 0.
592

    
593
@item parity
594
0 if is bottom field first, 1 if the interlaced video is top field
595
first, -1 to enable automatic detection.
596

    
597
@end table
598

    
599
@c man end VIDEO FILTERS
600

    
601
@chapter Video Sources
602
@c man begin VIDEO SOURCES
603

    
604
Below is a description of the currently available video sources.
605

    
606
@section buffer
607

    
608
Buffer video frames, and make them available to the filter chain.
609

    
610
This source is mainly intended for a programmatic use, in particular
611
through the interface defined in @file{libavfilter/vsrc_buffer.h}.
612

    
613
It accepts the following parameters:
614
@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}
615

    
616
All the parameters need to be explicitely defined.
617

    
618
Follows the list of the accepted parameters.
619

    
620
@table @option
621

    
622
@item width, height
623
Specify the width and height of the buffered video frames.
624

    
625
@item pix_fmt_string
626

    
627
A string representing the pixel format of the buffered video frames.
628
It may be a number corresponding to a pixel format, or a pixel format
629
name.
630

    
631
@item timebase_num, timebase_den
632
Specify numerator and denomitor of the timebase assumed by the
633
timestamps of the buffered frames.
634
@end table
635

    
636
For example:
637
@example
638
buffer=320:240:yuv410p:1:24
639
@end example
640

    
641
will instruct the source to accept video frames with size 320x240 and
642
with format "yuv410p" and assuming 1/24 as the timestamps timebase.
643
Since the pixel format with name "yuv410p" corresponds to the number 6
644
(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
645
this example corresponds to:
646
@example
647
buffer=320:240:6:1:24
648
@end example
649

    
650
@section color
651

    
652
Provide an uniformly colored input.
653

    
654
It accepts the following parameters:
655
@var{color}:@var{frame_size}:@var{frame_rate}
656

    
657
Follows the description of the accepted parameters.
658

    
659
@table @option
660

    
661
@item color
662
Specify the color of the source. It can be the name of a color (case
663
insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
664
alpha specifier. The default value is "black".
665

    
666
@item frame_size
667
Specify the size of the sourced video, it may be a string of the form
668
@var{width}x@var{heigth}, or the name of a size abbreviation. The
669
default value is "320x240".
670

    
671
@item frame_rate
672
Specify the frame rate of the sourced video, as the number of frames
673
generated per second. It has to be a string in the format
674
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
675
number or a valid video frame rate abbreviation. The default value is
676
"25".
677

    
678
@end table
679

    
680
For example the following graph description will generate a red source
681
with an opacity of 0.2, with size "qcif" and a frame rate of 10
682
frames per second, which will be overlayed over the source connected
683
to the pad with identifier "in".
684

    
685
@example
686
"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
687
@end example
688

    
689
@section nullsrc
690

    
691
Null video source, never return images. It is mainly useful as a
692
template and to be employed in analysis / debugging tools.
693

    
694
It accepts as optional parameter a string of the form
695
@var{width}:@var{height}:@var{timebase}.
696

    
697
@var{width} and @var{height} specify the size of the configured
698
source. The default values of @var{width} and @var{height} are
699
respectively 352 and 288 (corresponding to the CIF size format).
700

    
701
@var{timebase} specifies an arithmetic expression representing a
702
timebase. The expression can contain the constants "PI", "E", "PHI",
703
"AVTB" (the default timebase), and defaults to the value "AVTB".
704

    
705
@c man end VIDEO SOURCES
706

    
707
@chapter Video Sinks
708
@c man begin VIDEO SINKS
709

    
710
Below is a description of the currently available video sinks.
711

    
712
@section nullsink
713

    
714
Null video sink, do absolutely nothing with the input video. It is
715
mainly useful as a template and to be employed in analysis / debugging
716
tools.
717

    
718
@c man end VIDEO SINKS
719