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