70047839a5e91b388c2c31a47b26cd0ff0a28f3d
[ffmpeg.git] / doc / filters.texi
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 Video Filters
18 @c man begin VIDEO FILTERS
19
20 When you configure your FFmpeg build, you can disable any of the
21 existing filters using --disable-filters.
22 The configure output will show the video filters included in your
23 build.
24
25 Below is a description of the currently available video filters.
26
27 @section crop
28
29 Crop the input video to @var{x}:@var{y}:@var{width}:@var{height}.
30
31 @example
32 ./ffmpeg -i in.avi -vf "crop=0:0:0:240" out.avi
33 @end example
34
35 @var{x} and @var{y} specify the position of the top-left corner of the
36 output (non-cropped) area.
37
38 The default value of @var{x} and @var{y} is 0.
39
40 The @var{width} and @var{height} parameters specify the width and height
41 of the output (non-cropped) area.
42
43 A value of 0 is interpreted as the maximum possible size contained in
44 the area delimited by the top-left corner at position x:y.
45
46 For example the parameters:
47
48 @example
49 "crop=100:100:0:0"
50 @end example
51
52 will delimit the rectangle with the top-left corner placed at position
53 100:100 and the right-bottom corner corresponding to the right-bottom
54 corner of the input image.
55
56 The default value of @var{width} and @var{height} is 0.
57
58 @section fifo
59
60 Buffer input images and send them when they are requested.
61
62 This filter is mainly useful when auto-inserted by the libavfilter
63 framework.
64
65 The filter does not take parameters.
66
67 @section format
68
69 Convert the input video to one of the specified pixel formats.
70 Libavfilter will try to pick one that is supported for the input to
71 the next filter.
72
73 The filter accepts a list of pixel format names, separated by ``:'',
74 for example ``yuv420p:monow:rgb24''.
75
76 The following command:
77
78 @example
79 ./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
80 @end example
81
82 will convert the input video to the format ``yuv420p''.
83
84 @section hflip
85
86 Flip the input video horizontally.
87
88 For example to horizontally flip the video in input with
89 @file{ffmpeg}:
90 @example
91 ffmpeg -i in.avi -vf "hflip" out.avi
92 @end example
93
94 @section noformat
95
96 Force libavfilter not to use any of the specified pixel formats for the
97 input to the next filter.
98
99 The filter accepts a list of pixel format names, separated by ``:'',
100 for example ``yuv420p:monow:rgb24''.
101
102 The following command:
103
104 @example
105 ./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
106 @end example
107
108 will make libavfilter use a format different from ``yuv420p'' for the
109 input to the vflip filter.
110
111 @section null
112
113 Pass the video source unchanged to the output.
114
115 @section ocv_smooth
116
117 Apply smooth transform using libopencv.
118
119 To enable this filter install libopencv library and headers and
120 configure FFmpeg with --enable-libopencv.
121
122 It accepts the following parameters:
123 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
124
125 @var{type} is the type of smooth filter to apply, and can be one of
126 the following value: "blur", "blur_no_scale", "median", "gaussian",
127 "bilateral". The default value is "gaussian".
128
129 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
130 parameters whose meanings depend on smooth type. @var{param1} and
131 @var{param2} accept integer positive values or 0, @var{param3} and
132 @var{param4} accept float values.
133
134 The default value for @var{param1} is 3, the default value for the
135 other parameters is 0.
136
137 These parameters corresponds to the parameters assigned to the
138 libopencv function @code{cvSmooth}. Refer the official libopencv
139 documentation for the exact meaning of the parameters:
140 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
141
142 @section pad
143
144 Add paddings to the input image, and places the original input at the
145 given coordinates @var{x}, @var{y}.
146
147 It accepts the following parameters:
148 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
149
150 Follows the description of the accepted parameters.
151
152 @table @option
153 @item width, height
154
155 Specify the size of the output image with the paddings added. If the
156 value for @var{width} or @var{height} is 0, the corresponding input size
157 is used for the output.
158
159 The default value of @var{width} and @var{height} is 0.
160
161 @item x, y
162
163 Specify the offsets where to place the input image in the padded area
164 with respect to the top/left border of the output image.
165
166 The default value of @var{x} and @var{y} is 0.
167
168 @item color
169
170 Specify the color of the padded area, it can be the name of a color
171 (case insensitive match) or a 0xRRGGBB[AA] sequence.
172
173 The default value of @var{color} is ``black''.
174
175 @end table
176
177 @section pixdesctest
178
179 Pixel format descriptor test filter, mainly useful for internal
180 testing. The output video should be equal to the input video.
181
182 For example:
183 @example
184 format=monow, pixdesctest
185 @end example
186
187 can be used to test the monowhite pixel format descriptor definition.
188
189 @section scale
190
191 Scale the input video to @var{width}:@var{height} and/or convert the image format.
192
193 For example the command:
194
195 @example
196 ./ffmpeg -i in.avi -vf "scale=200:100" out.avi
197 @end example
198
199 will scale the input video to a size of 200x100.
200
201 If the input image format is different from the format requested by
202 the next filter, the scale filter will convert the input to the
203 requested format.
204
205 If the value for @var{width} or @var{height} is 0, the respective input
206 size is used for the output.
207
208 If the value for @var{width} or @var{height} is -1, the scale filter will
209 use, for the respective output size, a value that maintains the aspect
210 ratio of the input image.
211
212 The default value of @var{width} and @var{height} is 0.
213
214 @section slicify
215
216 Pass the images of input video on to next video filter as multiple
217 slices.
218
219 @example
220 ./ffmpeg -i in.avi -vf "slicify=32" out.avi
221 @end example
222
223 The filter accepts the slice height as parameter. If the parameter is
224 not specified it will use the default value of 16.
225
226 Adding this in the beginning of filter chains should make filtering
227 faster due to better use of the memory cache.
228
229 @section unsharp
230
231 Sharpen or blur the input video.
232
233 It accepts the following parameters:
234 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
235
236 Negative values for the amount will blur the input video, while positive
237 values will sharpen. All parameters are optional and default to the
238 equivalent of the string '5:5:1.0:0:0:0.0'.
239
240 @table @option
241
242 @item luma_msize_x
243 Set the luma matrix horizontal size. It can be an integer between 3
244 and 13, default value is 5.
245
246 @item luma_msize_y
247 Set the luma matrix vertical size. It can be an integer between 3
248 and 13, default value is 5.
249
250 @item luma_amount
251 Set the luma effect strength. It can be a float number between -2.0
252 and 5.0, default value is 1.0.
253
254 @item chroma_msize_x
255 Set the chroma matrix horizontal size. It can be an integer between 3
256 and 13, default value is 0.
257
258 @item chroma_msize_y
259 Set the chroma matrix vertical size. It can be an integer between 3
260 and 13, default value is 0.
261
262 @item luma_amount
263 Set the chroma effect strength. It can be a float number between -2.0
264 and 5.0, default value is 0.0.
265
266 @end table
267
268 @example
269 # Strong luma sharpen effect parameters
270 unsharp=7:7:2.5
271
272 # Strong blur of both luma and chroma parameters
273 unsharp=7:7:-2:7:7:-2
274
275 # Use the default values with @command{ffmpeg}
276 ./ffmpeg -i in.avi -vf "unsharp" out.mp4
277 @end example
278
279 @section vflip
280
281 Flip the input video vertically.
282
283 @example
284 ./ffmpeg -i in.avi -vf "vflip" out.avi
285 @end example
286
287 @c man end VIDEO FILTERS
288
289 @chapter Video Sources
290 @c man begin VIDEO SOURCES
291
292 Below is a description of the currently available video sources.
293
294 @section buffer
295
296 Buffer video frames, and make them available to the filter chain.
297
298 This source is mainly intended for a programmatic use, in particular
299 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
300
301 It accepts the following parameters:
302 @var{width}:@var{height}:@var{pix_fmt_string}
303
304 All the parameters need to be explicitely defined.
305
306 Follows the list of the accepted parameters.
307
308 @table @option
309
310 @item width, height
311 Specify the width and height of the buffered video frames.
312
313 @item pix_fmt_string
314
315 A string representing the pixel format of the buffered video frames.
316 It may be a number corresponding to a pixel format, or a pixel format
317 name.
318
319 @end table
320
321 For example:
322 @example
323 buffer=320:240:yuv410p
324 @end example
325
326 will instruct the source to accept video frames with size 320x240 and
327 with format "yuv410p". Since the pixel format with name "yuv410p"
328 corresponds to the number 6 (check the enum PixelFormat definition in
329 @file{libavutil/pixfmt.h}), this example corresponds to:
330 @example
331 buffer=320:240:6
332 @end example
333
334 @section color
335
336 Provide an uniformly colored input.
337
338 It accepts the following parameters:
339 @var{color}:@var{frame_size}:@var{frame_rate}
340
341 Follows the description of the accepted parameters.
342
343 @table @option
344
345 @item color
346 Specify the color of the source. It can be the name of a color (case
347 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
348 alpha specifier. The default value is "black".
349
350 @item frame_size
351 Specify the size of the sourced video, it may be a string of the form
352 @var{width}x@var{heigth}, or the name of a size abbreviation. The
353 default value is "320x240".
354
355 @item frame_rate
356 Specify the frame rate of the sourced video, as the number of frames
357 generated per second. It has to be a string in the format
358 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
359 number or a valid video frame rate abbreviation. The default value is
360 "25".
361
362 @end table
363
364 For example the following graph description will generate a red source
365 with an opacity of 0.2, with size "qcif" and a frame rate of 10
366 frames per second, which will be overlayed over the source connected
367 to the pad with identifier "in".
368
369 @example
370 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
371 @end example
372
373 @section nullsrc
374
375 Null video source, never return images. It is mainly useful as a
376 template and to be employed in analysis / debugging tools.
377
378 It accepts as optional parameter a string of the form
379 @var{width}:@var{height}, where @var{width} and @var{height} specify the size of
380 the configured source.
381
382 The default values of @var{width} and @var{height} are respectively 352
383 and 288 (corresponding to the CIF size format).
384
385 @c man end VIDEO SOURCES
386
387 @chapter Video Sinks
388 @c man begin VIDEO SINKS
389
390 Below is a description of the currently available video sinks.
391
392 @section nullsink
393
394 Null video sink, do absolutely nothing with the input video. It is
395 mainly useful as a template and to be employed in analysis / debugging
396 tools.
397
398 @c man end VIDEO SINKS
399