c6b9161a6b44e37552d8ac9937b4a91b0227aa06
[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 scale
116
117 Scale the input video to @var{width}:@var{height} and/or convert the image format.
118
119 For example the command:
120
121 @example
122 ./ffmpeg -i in.avi -vf "scale=200:100" out.avi
123 @end example
124
125 will scale the input video to a size of 200x100.
126
127 If the input image format is different from the format requested by
128 the next filter, the scale filter will convert the input to the
129 requested format.
130
131 If the value for @var{width} or @var{height} is 0, the respective input
132 size is used for the output.
133
134 If the value for @var{width} or @var{height} is -1, the scale filter will
135 use, for the respective output size, a value that maintains the aspect
136 ratio of the input image.
137
138 The default value of @var{width} and @var{height} is 0.
139
140 @section slicify
141
142 Pass the images of input video on to next video filter as multiple
143 slices.
144
145 @example
146 ./ffmpeg -i in.avi -vf "slicify=32" out.avi
147 @end example
148
149 The filter accepts the slice height as parameter. If the parameter is
150 not specified it will use the default value of 16.
151
152 Adding this in the beginning of filter chains should make filtering
153 faster due to better use of the memory cache.
154
155 @section unsharp
156
157 Sharpen or blur the input video.
158
159 It accepts the following parameters:
160 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
161
162 Negative values for the amount will blur the input video, while positive
163 values will sharpen. All parameters are optional and default to the
164 equivalent of the string '5:5:1.0:0:0:0.0'.
165
166 @table @option
167
168 @item luma_msize_x
169 Set the luma matrix horizontal size. It can be an integer between 3
170 and 13, default value is 5.
171
172 @item luma_msize_y
173 Set the luma matrix vertical size. It can be an integer between 3
174 and 13, default value is 5.
175
176 @item luma_amount
177 Set the luma effect strength. It can be a float number between -2.0
178 and 5.0, default value is 1.0.
179
180 @item chroma_msize_x
181 Set the chroma matrix horizontal size. It can be an integer between 3
182 and 13, default value is 0.
183
184 @item chroma_msize_y
185 Set the chroma matrix vertical size. It can be an integer between 3
186 and 13, default value is 0.
187
188 @item luma_amount
189 Set the chroma effect strength. It can be a float number between -2.0
190 and 5.0, default value is 0.0.
191
192 @end table
193
194 @example
195 # Strong luma sharpen effect parameters
196 unsharp=7:7:2.5
197
198 # Strong blur of both luma and chroma parameters
199 unsharp=7:7:-2:7:7:-2
200
201 # Use the default values with @command{ffmpeg}
202 ./ffmpeg -i in.avi -vf "unsharp" out.mp4
203 @end example
204
205 @section vflip
206
207 Flip the input video vertically.
208
209 @example
210 ./ffmpeg -i in.avi -vf "vflip" out.avi
211 @end example
212
213 @c man end VIDEO FILTERS
214
215 @chapter Video Sources
216 @c man begin VIDEO SOURCES
217
218 Below is a description of the currently available video sources.
219
220 @section nullsrc
221
222 Null video source, never return images. It is mainly useful as a
223 template and to be employed in analysis / debugging tools.
224
225 It accepts as optional parameter a string of the form
226 @var{width}:@var{height}, where @var{width} and @var{height} specify the size of
227 the configured source.
228
229 The default values of @var{width} and @var{height} are respectively 352
230 and 288 (corresponding to the CIF size format).
231
232 @c man end VIDEO SOURCES
233
234 @chapter Video Sinks
235 @c man begin VIDEO SINKS
236
237 Below is a description of the currently available video sinks.
238
239 @section nullsink
240
241 Null video sink, do absolutely nothing with the input video. It is
242 mainly useful as a template and to be employed in analysis / debugging
243 tools.
244
245 @c man end VIDEO SINKS
246