Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ 16134b7c

History | View | Annotate | Download (18.3 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 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 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
@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
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

    
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
@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
@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
@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
through the interface defined in @file{libavfilter/vsrc_buffer.h}.
577

    
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
@section color
612

    
613
Provide an uniformly colored input.
614

    
615
It accepts the following parameters:
616
@var{color}:@var{frame_size}:@var{frame_rate}
617

    
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
@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
@var{width}:@var{height}:@var{timebase}.
657

    
658
@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

    
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
680