60ecf5676d91821f67d2589719c42704515517e0
[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 pad
116
117 Add paddings to the input image, and places the original input at the
118 given coordinates @var{x}, @var{y}.
119
120 It accepts the following parameters:
121 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
122
123 Follows the description of the accepted parameters.
124
125 @table @option
126 @item width, height
127
128 Specify the size of the output image with the paddings added. If the
129 value for @var{width} or @var{height} is 0, the corresponding input size
130 is used for the output.
131
132 The default value of @var{width} and @var{height} is 0.
133
134 @item x, y
135
136 Specify the offsets where to place the input image in the padded area
137 with respect to the top/left border of the output image.
138
139 The default value of @var{x} and @var{y} is 0.
140
141 @item color
142
143 Specify the color of the padded area, it can be the name of a color
144 (case insensitive match) or a 0xRRGGBB[AA] sequence.
145
146 The default value of @var{color} is ``black''.
147
148 @end table
149
150 @section pixdesctest
151
152 Pixel format descriptor test filter, mainly useful for internal
153 testing. The output video should be equal to the input video.
154
155 For example:
156 @example
157 format=monow, pixdesctest
158 @end example
159
160 can be used to test the monowhite pixel format descriptor definition.
161
162 @section scale
163
164 Scale the input video to @var{width}:@var{height} and/or convert the image format.
165
166 For example the command:
167
168 @example
169 ./ffmpeg -i in.avi -vf "scale=200:100" out.avi
170 @end example
171
172 will scale the input video to a size of 200x100.
173
174 If the input image format is different from the format requested by
175 the next filter, the scale filter will convert the input to the
176 requested format.
177
178 If the value for @var{width} or @var{height} is 0, the respective input
179 size is used for the output.
180
181 If the value for @var{width} or @var{height} is -1, the scale filter will
182 use, for the respective output size, a value that maintains the aspect
183 ratio of the input image.
184
185 The default value of @var{width} and @var{height} is 0.
186
187 @section slicify
188
189 Pass the images of input video on to next video filter as multiple
190 slices.
191
192 @example
193 ./ffmpeg -i in.avi -vf "slicify=32" out.avi
194 @end example
195
196 The filter accepts the slice height as parameter. If the parameter is
197 not specified it will use the default value of 16.
198
199 Adding this in the beginning of filter chains should make filtering
200 faster due to better use of the memory cache.
201
202 @section unsharp
203
204 Sharpen or blur the input video.
205
206 It accepts the following parameters:
207 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
208
209 Negative values for the amount will blur the input video, while positive
210 values will sharpen. All parameters are optional and default to the
211 equivalent of the string '5:5:1.0:0:0:0.0'.
212
213 @table @option
214
215 @item luma_msize_x
216 Set the luma matrix horizontal size. It can be an integer between 3
217 and 13, default value is 5.
218
219 @item luma_msize_y
220 Set the luma matrix vertical size. It can be an integer between 3
221 and 13, default value is 5.
222
223 @item luma_amount
224 Set the luma effect strength. It can be a float number between -2.0
225 and 5.0, default value is 1.0.
226
227 @item chroma_msize_x
228 Set the chroma matrix horizontal size. It can be an integer between 3
229 and 13, default value is 0.
230
231 @item chroma_msize_y
232 Set the chroma matrix vertical size. It can be an integer between 3
233 and 13, default value is 0.
234
235 @item luma_amount
236 Set the chroma effect strength. It can be a float number between -2.0
237 and 5.0, default value is 0.0.
238
239 @end table
240
241 @example
242 # Strong luma sharpen effect parameters
243 unsharp=7:7:2.5
244
245 # Strong blur of both luma and chroma parameters
246 unsharp=7:7:-2:7:7:-2
247
248 # Use the default values with @command{ffmpeg}
249 ./ffmpeg -i in.avi -vf "unsharp" out.mp4
250 @end example
251
252 @section vflip
253
254 Flip the input video vertically.
255
256 @example
257 ./ffmpeg -i in.avi -vf "vflip" out.avi
258 @end example
259
260 @c man end VIDEO FILTERS
261
262 @chapter Video Sources
263 @c man begin VIDEO SOURCES
264
265 Below is a description of the currently available video sources.
266
267 @section buffer
268
269 Buffer video frames, and make them available to the filter chain.
270
271 This source is mainly intended for a programmatic use, in particular
272 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
273
274 It accepts the following parameters:
275 @var{width}:@var{height}:@var{pix_fmt_string}
276
277 All the parameters need to be explicitely defined.
278
279 Follows the list of the accepted parameters.
280
281 @table @option
282
283 @item width, height
284 Specify the width and height of the buffered video frames.
285
286 @item pix_fmt_string
287
288 A string representing the pixel format of the buffered video frames.
289 It may be a number corresponding to a pixel format, or a pixel format
290 name.
291
292 @end table
293
294 For example:
295 @example
296 buffer=320:240:yuv410p
297 @end example
298
299 will instruct the source to accept video frames with size 320x240 and
300 with format "yuv410p". Since the pixel format with name "yuv410p"
301 corresponds to the number 6 (check the enum PixelFormat definition in
302 @file{libavutil/pixfmt.h}), this example corresponds to:
303 @example
304 buffer=320:240:6
305 @end example
306
307 @section color
308
309 Provide an uniformly colored input.
310
311 It accepts the following parameters:
312 @var{color}:@var{frame_size}:@var{frame_rate}
313
314 Follows the description of the accepted parameters.
315
316 @table @option
317
318 @item color
319 Specify the color of the source. It can be the name of a color (case
320 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
321 alpha specifier. The default value is "black".
322
323 @item frame_size
324 Specify the size of the sourced video, it may be a string of the form
325 @var{width}x@var{heigth}, or the name of a size abbreviation. The
326 default value is "320x240".
327
328 @item frame_rate
329 Specify the frame rate of the sourced video, as the number of frames
330 generated per second. It has to be a string in the format
331 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
332 number or a valid video frame rate abbreviation. The default value is
333 "25".
334
335 @end table
336
337 For example the following graph description will generate a red source
338 with an opacity of 0.2, with size "qcif" and a frame rate of 10
339 frames per second, which will be overlayed over the source connected
340 to the pad with identifier "in".
341
342 @example
343 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
344 @end example
345
346 @section nullsrc
347
348 Null video source, never return images. It is mainly useful as a
349 template and to be employed in analysis / debugging tools.
350
351 It accepts as optional parameter a string of the form
352 @var{width}:@var{height}, where @var{width} and @var{height} specify the size of
353 the configured source.
354
355 The default values of @var{width} and @var{height} are respectively 352
356 and 288 (corresponding to the CIF size format).
357
358 @c man end VIDEO SOURCES
359
360 @chapter Video Sinks
361 @c man begin VIDEO SINKS
362
363 Below is a description of the currently available video sinks.
364
365 @section nullsink
366
367 Null video sink, do absolutely nothing with the input video. It is
368 mainly useful as a template and to be employed in analysis / debugging
369 tools.
370
371 @c man end VIDEO SINKS
372