Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ 1ee410f3

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