Add pixdesctest filter and corresponding test.
[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 nullsrc
233
234 Null video source, never return images. It is mainly useful as a
235 template and to be employed in analysis / debugging tools.
236
237 It accepts as optional parameter a string of the form
238 @var{width}:@var{height}, where @var{width} and @var{height} specify the size of
239 the configured source.
240
241 The default values of @var{width} and @var{height} are respectively 352
242 and 288 (corresponding to the CIF size format).
243
244 @c man end VIDEO SOURCES
245
246 @chapter Video Sinks
247 @c man begin VIDEO SINKS
248
249 Below is a description of the currently available video sinks.
250
251 @section nullsink
252
253 Null video sink, do absolutely nothing with the input video. It is
254 mainly useful as a template and to be employed in analysis / debugging
255 tools.
256
257 @c man end VIDEO SINKS
258