Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ e40032e2

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