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