Statistics
| Branch: | Revision:

ffmpeg / doc / filters.texi @ f0a55438

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

    
76
Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
77

    
78
The parameters are expressions containing the following constants:
79

    
80
@table @option
81
@item E, PI, PHI
82
the corresponding mathematical approximated values for e
83
(euler number), pi (greek PI), PHI (golden ratio)
84

    
85
@item x, y
86
the computed values for @var{x} and @var{y}. They are evaluated for
87
each new frame.
88

    
89
@item in_w, in_h
90
the input width and heigth
91

    
92
@item iw, ih
93
same as @var{in_w} and @var{in_h}
94

    
95
@item out_w, out_h
96
the output (cropped) width and heigth
97

    
98
@item ow, oh
99
same as @var{out_w} and @var{out_h}
100

    
101
@item n
102
the number of input frame, starting from 0
103

    
104
@item pos
105
the position in the file of the input frame, NAN if unknown
106

    
107
@item t
108
timestamp expressed in seconds, NAN if the input timestamp is unknown
109

    
110
@end table
111

    
112
The @var{out_w} and @var{out_h} parameters specify the expressions for
113
the width and height of the output (cropped) video. They are
114
evaluated just at the configuration of the filter.
115

    
116
The default value of @var{out_w} is "in_w", and the default value of
117
@var{out_h} is "in_h".
118

    
119
The expression for @var{out_w} may depend on the value of @var{out_h},
120
and the expression for @var{out_h} may depend on @var{out_w}, but they
121
cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
122
evaluated after @var{out_w} and @var{out_h}.
123

    
124
The @var{x} and @var{y} parameters specify the expressions for the
125
position of the top-left corner of the output (non-cropped) area. They
126
are evaluated for each frame. If the evaluated value is not valid, it
127
is approximated to the nearest valid value.
128

    
129
The default value of @var{x} is "(in_w-out_w)/2", and the default
130
value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
131
the center of the input image.
132

    
133
The expression for @var{x} may depend on @var{y}, and the expression
134
for @var{y} may depend on @var{x}.
135

    
136
Follow some examples:
137
@example
138
# crop the central input area with size 100x100
139
crop=100:100
140

    
141
# crop the central input area with size 2/3 of the input video
142
"crop=2/3*in_w:2/3*in_h"
143

    
144
# crop the input video central square
145
crop=in_h
146

    
147
# delimit the rectangle with the top-left corner placed at position
148
# 100:100 and the right-bottom corner corresponding to the right-bottom
149
# corner of the input image.
150
crop=in_w-100:in_h-100:100:100
151

    
152
# crop 10 pixels from the lefth and right borders, and 20 pixels from
153
# the top and bottom borders
154
"crop=in_w-2*10:in_h-2*20"
155

    
156
# keep only the bottom right quarter of the input image
157
"crop=in_w/2:in_h/2:in_w/2:in_h/2"
158

    
159
# crop height for getting Greek harmony
160
"crop=in_w:1/PHI*in_w"
161

    
162
# trembling effect
163
"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)"
164

    
165
# erratic camera effect depending on timestamp and position
166
"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)"
167

    
168
# set x depending on the value of y
169
"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
170
@end example
171

    
172
@section fifo
173

    
174
Buffer input images and send them when they are requested.
175

    
176
This filter is mainly useful when auto-inserted by the libavfilter
177
framework.
178

    
179
The filter does not take parameters.
180

    
181
@section format
182

    
183
Convert the input video to one of the specified pixel formats.
184
Libavfilter will try to pick one that is supported for the input to
185
the next filter.
186

    
187
The filter accepts a list of pixel format names, separated by ":",
188
for example "yuv420p:monow:rgb24".
189

    
190
The following command:
191

    
192
@example
193
./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
194
@end example
195

    
196
will convert the input video to the format "yuv420p".
197

    
198
@section frei0r
199

    
200
Apply a frei0r effect to the input video.
201

    
202
To enable compilation of this filter you need to install the frei0r
203
header and configure FFmpeg with --enable-frei0r.
204

    
205
The filter supports the syntax:
206
@example
207
@var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
208
@end example
209

    
210
@var{filter_name} is the name to the frei0r effect to load. If the
211
environment variable @env{FREI0R_PATH} is defined, the frei0r effect
212
is searched in each one of the directories specified by the colon
213
separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
214
paths, which are in this order: @file{HOME/.frei0r-1/lib/},
215
@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
216

    
217
@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
218
for the frei0r effect.
219

    
220
A frei0r effect parameter can be a boolean (whose values are specified
221
with "y" and "n"), a double, a color (specified by the syntax
222
@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
223
numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
224
description), a position (specified by the syntax @var{X}/@var{Y},
225
@var{X} and @var{Y} being float numbers) and a string.
226

    
227
The number and kind of parameters depend on the loaded effect. If an
228
effect parameter is not specified the default value is set.
229

    
230
Some examples follow:
231
@example
232
# apply the distort0r effect, set the first two double parameters
233
frei0r=distort0r:0.5:0.01
234

    
235
# apply the colordistance effect, takes a color as first parameter
236
frei0r=colordistance:0.2/0.3/0.4
237
frei0r=colordistance:violet
238
frei0r=colordistance:0x112233
239

    
240
# apply the perspective effect, specify the top left and top right
241
# image positions
242
frei0r=perspective:0.2/0.2:0.8/0.2
243
@end example
244

    
245
For more information see:
246
@url{http://piksel.org/frei0r}
247

    
248
@section hflip
249

    
250
Flip the input video horizontally.
251

    
252
For example to horizontally flip the video in input with
253
@file{ffmpeg}:
254
@example
255
ffmpeg -i in.avi -vf "hflip" out.avi
256
@end example
257

    
258
@section noformat
259

    
260
Force libavfilter not to use any of the specified pixel formats for the
261
input to the next filter.
262

    
263
The filter accepts a list of pixel format names, separated by ":",
264
for example "yuv420p:monow:rgb24".
265

    
266
The following command:
267

    
268
@example
269
./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
270
@end example
271

    
272
will make libavfilter use a format different from "yuv420p" for the
273
input to the vflip filter.
274

    
275
@section null
276

    
277
Pass the video source unchanged to the output.
278

    
279
@section ocv_smooth
280

    
281
Apply smooth transform using libopencv.
282

    
283
To enable this filter install libopencv library and headers and
284
configure FFmpeg with --enable-libopencv.
285

    
286
The filter accepts the following parameters:
287
@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
288

    
289
@var{type} is the type of smooth filter to apply, and can be one of
290
the following values: "blur", "blur_no_scale", "median", "gaussian",
291
"bilateral". The default value is "gaussian".
292

    
293
@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
294
parameters whose meanings depend on smooth type. @var{param1} and
295
@var{param2} accept integer positive values or 0, @var{param3} and
296
@var{param4} accept float values.
297

    
298
The default value for @var{param1} is 3, the default value for the
299
other parameters is 0.
300

    
301
These parameters correspond to the parameters assigned to the
302
libopencv function @code{cvSmooth}. Refer to the official libopencv
303
documentation for the exact meaning of the parameters:
304
@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
305

    
306
@section pad
307

    
308
Add paddings to the input image, and places the original input at the
309
given coordinates @var{x}, @var{y}.
310

    
311
It accepts the following parameters:
312
@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
313

    
314
Follows the description of the accepted parameters.
315

    
316
@table @option
317
@item width, height
318

    
319
Specify the size of the output image with the paddings added. If the
320
value for @var{width} or @var{height} is 0, the corresponding input size
321
is used for the output.
322

    
323
The default value of @var{width} and @var{height} is 0.
324

    
325
@item x, y
326

    
327
Specify the offsets where to place the input image in the padded area
328
with respect to the top/left border of the output image.
329

    
330
The default value of @var{x} and @var{y} is 0.
331

    
332
@item color
333

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

    
337
The default value of @var{color} is "black".
338

    
339
@end table
340

    
341
@section pixdesctest
342

    
343
Pixel format descriptor test filter, mainly useful for internal
344
testing. The output video should be equal to the input video.
345

    
346
For example:
347
@example
348
format=monow, pixdesctest
349
@end example
350

    
351
can be used to test the monowhite pixel format descriptor definition.
352

    
353
@section scale
354

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

    
357
For example the command:
358

    
359
@example
360
./ffmpeg -i in.avi -vf "scale=200:100" out.avi
361
@end example
362

    
363
will scale the input video to a size of 200x100.
364

    
365
If the input image format is different from the format requested by
366
the next filter, the scale filter will convert the input to the
367
requested format.
368

    
369
If the value for @var{width} or @var{height} is 0, the respective input
370
size is used for the output.
371

    
372
If the value for @var{width} or @var{height} is -1, the scale filter will
373
use, for the respective output size, a value that maintains the aspect
374
ratio of the input image.
375

    
376
The default value of @var{width} and @var{height} is 0.
377

    
378
@section slicify
379

    
380
Pass the images of input video on to next video filter as multiple
381
slices.
382

    
383
@example
384
./ffmpeg -i in.avi -vf "slicify=32" out.avi
385
@end example
386

    
387
The filter accepts the slice height as parameter. If the parameter is
388
not specified it will use the default value of 16.
389

    
390
Adding this in the beginning of filter chains should make filtering
391
faster due to better use of the memory cache.
392

    
393
@section unsharp
394

    
395
Sharpen or blur the input video.
396

    
397
It accepts the following parameters:
398
@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
399

    
400
Negative values for the amount will blur the input video, while positive
401
values will sharpen. All parameters are optional and default to the
402
equivalent of the string '5:5:1.0:0:0:0.0'.
403

    
404
@table @option
405

    
406
@item luma_msize_x
407
Set the luma matrix horizontal size. It can be an integer between 3
408
and 13, default value is 5.
409

    
410
@item luma_msize_y
411
Set the luma matrix vertical size. It can be an integer between 3
412
and 13, default value is 5.
413

    
414
@item luma_amount
415
Set the luma effect strength. It can be a float number between -2.0
416
and 5.0, default value is 1.0.
417

    
418
@item chroma_msize_x
419
Set the chroma matrix horizontal size. It can be an integer between 3
420
and 13, default value is 0.
421

    
422
@item chroma_msize_y
423
Set the chroma matrix vertical size. It can be an integer between 3
424
and 13, default value is 0.
425

    
426
@item luma_amount
427
Set the chroma effect strength. It can be a float number between -2.0
428
and 5.0, default value is 0.0.
429

    
430
@end table
431

    
432
@example
433
# Strong luma sharpen effect parameters
434
unsharp=7:7:2.5
435

    
436
# Strong blur of both luma and chroma parameters
437
unsharp=7:7:-2:7:7:-2
438

    
439
# Use the default values with @command{ffmpeg}
440
./ffmpeg -i in.avi -vf "unsharp" out.mp4
441
@end example
442

    
443
@section vflip
444

    
445
Flip the input video vertically.
446

    
447
@example
448
./ffmpeg -i in.avi -vf "vflip" out.avi
449
@end example
450

    
451
@c man end VIDEO FILTERS
452

    
453
@chapter Video Sources
454
@c man begin VIDEO SOURCES
455

    
456
Below is a description of the currently available video sources.
457

    
458
@section buffer
459

    
460
Buffer video frames, and make them available to the filter chain.
461

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

    
465
It accepts the following parameters:
466
@var{width}:@var{height}:@var{pix_fmt_string}
467

    
468
All the parameters need to be explicitely defined.
469

    
470
Follows the list of the accepted parameters.
471

    
472
@table @option
473

    
474
@item width, height
475
Specify the width and height of the buffered video frames.
476

    
477
@item pix_fmt_string
478

    
479
A string representing the pixel format of the buffered video frames.
480
It may be a number corresponding to a pixel format, or a pixel format
481
name.
482

    
483
@end table
484

    
485
For example:
486
@example
487
buffer=320:240:yuv410p
488
@end example
489

    
490
will instruct the source to accept video frames with size 320x240 and
491
with format "yuv410p". Since the pixel format with name "yuv410p"
492
corresponds to the number 6 (check the enum PixelFormat definition in
493
@file{libavutil/pixfmt.h}), this example corresponds to:
494
@example
495
buffer=320:240:6
496
@end example
497

    
498
@section color
499

    
500
Provide an uniformly colored input.
501

    
502
It accepts the following parameters:
503
@var{color}:@var{frame_size}:@var{frame_rate}
504

    
505
Follows the description of the accepted parameters.
506

    
507
@table @option
508

    
509
@item color
510
Specify the color of the source. It can be the name of a color (case
511
insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
512
alpha specifier. The default value is "black".
513

    
514
@item frame_size
515
Specify the size of the sourced video, it may be a string of the form
516
@var{width}x@var{heigth}, or the name of a size abbreviation. The
517
default value is "320x240".
518

    
519
@item frame_rate
520
Specify the frame rate of the sourced video, as the number of frames
521
generated per second. It has to be a string in the format
522
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
523
number or a valid video frame rate abbreviation. The default value is
524
"25".
525

    
526
@end table
527

    
528
For example the following graph description will generate a red source
529
with an opacity of 0.2, with size "qcif" and a frame rate of 10
530
frames per second, which will be overlayed over the source connected
531
to the pad with identifier "in".
532

    
533
@example
534
"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
535
@end example
536

    
537
@section nullsrc
538

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

    
542
It accepts as optional parameter a string of the form
543
@var{width}:@var{height}, where @var{width} and @var{height} specify the size of
544
the configured source.
545

    
546
The default values of @var{width} and @var{height} are respectively 352
547
and 288 (corresponding to the CIF size format).
548

    
549
@c man end VIDEO SOURCES
550

    
551
@chapter Video Sinks
552
@c man begin VIDEO SINKS
553

    
554
Below is a description of the currently available video sinks.
555

    
556
@section nullsink
557

    
558
Null video sink, do absolutely nothing with the input video. It is
559
mainly useful as a template and to be employed in analysis / debugging
560
tools.
561

    
562
@c man end VIDEO SINKS
563