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