Add unsharp video filter.
[libav.git] / doc / libavfilter.texi
CommitLineData
1f09ab5e
SS
1\input texinfo @c -*- texinfo -*-
2
dba755fa 3@settitle Libavfilter Documentation
1f09ab5e
SS
4@titlepage
5@sp 7
dba755fa 6@center @titlefont{Libavfilter Documentation}
1f09ab5e
SS
7@sp 3
8@end titlepage
9
10
11@chapter Introduction
12
13Libavfilter is the filtering API of FFmpeg. It is the substitute of the
14now deprecated 'vhooks' and started as a Google Summer of Code project.
15
16Integrating libavfilter into the main FFmpeg repository is a work in
17progress. If you wish to try the unfinished development code of
18libavfilter then check it out from the libavfilter repository into
19some directory of your choice by:
20
21@example
22 svn checkout svn://svn.ffmpeg.org/soc/libavfilter
23@end example
24
25And then read the README file in the top directory to learn how to
26integrate it into ffmpeg and ffplay.
27
28But note that there may still be serious bugs in the code and its API
29and ABI should not be considered stable yet!
30
f6112d7f
SS
31@chapter Tutorial
32
1f09ab5e
SS
33In libavfilter, it is possible for filters to have multiple inputs and
34multiple outputs.
35To illustrate the sorts of things that are possible, we can
36use a complex filter graph. For example, the following one:
37
38@example
39input --> split --> fifo -----------------------> overlay --> output
40 | ^
41 | |
42 +------> fifo --> crop --> vflip --------+
43@end example
44
45splits the stream in two streams, sends one stream through the crop filter
46and the vflip filter before merging it back with the other stream by
47overlaying it on top. You can use the following command to achieve this:
48
49@example
50./ffmpeg -i in.avi -s 240x320 -vfilters "[in] split [T1], fifo, [T2] overlay= 0:240 [out]; [T1] fifo, crop=0:0:-1:240, vflip [T2]
51@end example
52
53where input_video.avi has a vertical resolution of 480 pixels. The
54result will be that in output the top half of the video is mirrored
55onto the bottom half.
56
57Video filters are loaded using the @var{-vfilters} option passed to
58ffmpeg or to ffplay. Filters in the same linear chain are separated by
59commas. In our example, @var{split, fifo, overlay} are in one linear
60chain, and @var{fifo, crop, vflip} are in another. The points where
61the linear chains join are labeled by names enclosed in square
62brackets. In our example, that is @var{[T1]} and @var{[T2]}. The magic
63labels @var{[in]} and @var{[out]} are the points where video is input
64and output.
65
66Some filters take in input a list of parameters: they are specified
67after the filter name and an equal sign, and are separated each other
68by a semicolon.
69
70There exist so-called @var{source filters} that do not have a video
71input, and we expect in the future some @var{sink filters} that will
72not have video output.
73
11ab237e
SS
74@chapter graph2dot
75
76The @file{graph2dot} program included in the FFmpeg @file{tools}
77directory can be used to parse a filter graph description and issue a
78corresponding textual representation in the dot language.
79
80Invoke the command:
81@example
82graph2dot -h
83@end example
84
85to see how to use @file{graph2dot}.
86
87You can then pass the dot description to the @file{dot} program (from
88the graphviz suite of programs) and obtain a graphical representation
89of the filter graph.
90
91For example the sequence of commands:
92@example
93echo @var{GRAPH_DESCRIPTION} | \
94tools/graph2dot -o graph.tmp && \
95dot -Tpng graph.tmp -o graph.png && \
96display graph.png
97@end example
98
99can be used to create and display an image representing the graph
100described by the @var{GRAPH_DESCRIPTION} string.
101
1f09ab5e
SS
102@chapter Available video filters
103
104When you configure your FFmpeg build, you can disable any of the
105existing video filters.
106The configure output will show the video filters included in your
107build.
108
109Below is a description of the currently available video filters.
110
190c1669
SS
111@section crop
112
113Crop the input video to x:y:width:height.
114
115@example
116./ffmpeg -i in.avi -vfilters "crop=0:0:0:240" out.avi
117@end example
118
119``x'' and ``y'' specify the position of the top-left corner of the
120output (non-cropped) area.
121
122The default value of ``x'' and ``y'' is 0.
123
debfab4a
SS
124The ``width'' and ``height'' parameters specify the width and height
125of the output (non-cropped) area.
190c1669
SS
126
127A value of 0 is interpreted as the maximum possible size contained in
128the area delimited by the top-left corner at position x:y.
129
130For example the parameters:
131
132@example
133"crop=100:100:0:0"
134@end example
135
136will delimit the rectangle with the top-left corner placed at position
137100:100 and the right-bottom corner corresponding to the right-bottom
138corner of the input image.
139
29b5a3aa 140The default value of ``width'' and ``height'' is 0.
190c1669 141
fcbed3c7
SS
142@section format
143
144Convert the input video to one of the specified pixel formats.
143e3aa0 145Libavfilter will try to pick one that is supported for the input to
fcbed3c7
SS
146the next filter.
147
143e3aa0
SS
148The filter accepts a list of pixel format names, separated by ``:'',
149for example ``yuv420p:monow:rgb24''.
fcbed3c7
SS
150
151The following command:
152
153@example
154./ffmpeg -i in.avi -vfilters "format=yuv420p" out.avi
155@end example
156
157will convert the input video to the format ``yuv420p''.
158
159@section noformat
160
143e3aa0 161Force libavfilter not to use any of the specified pixel formats for the
fcbed3c7
SS
162input to the next filter.
163
143e3aa0
SS
164The filter accepts a list of pixel format names, separated by ``:'',
165for example ``yuv420p:monow:rgb24''.
fcbed3c7
SS
166
167The following command:
168
169@example
170./ffmpeg -i in.avi -vfilters "noformat=yuv420p, vflip" out.avi
171@end example
172
143e3aa0 173will make libavfilter use a format different from ``yuv420p'' for the
fcbed3c7
SS
174input to the vflip filter.
175
415e6d29
SS
176@section null
177
178Pass the source unchanged to the output.
179
c3eabb7d
SS
180@section scale
181
182Scale the input video to width:height and/or convert the image format.
183
184For example the command:
185
186@example
187./ffmpeg -i in.avi -vfilters "scale=200:100" out.avi
188@end example
189
190will scale the input video to a size of 200x100.
191
192If the input image format is different from the format requested by
193the next filter, the scale filter will convert the input to the
194requested format.
195
196If the value for ``width'' or ``height'' is 0, the respective input
197size is used for the output.
198
199If the value for ``width'' or ``height'' is -1, the scale filter will
200use, for the respective output size, a value that maintains the aspect
201ratio of the input image.
202
203The default value of ``width'' and ``height'' is 0.
204
0c0ccc28
SS
205@section slicify
206
207Pass the images of input video on to next video filter as multiple
208slices.
209
210@example
211./ffmpeg -i in.avi -vfilters "slicify=32" out.avi
212@end example
213
214The filter accepts the slice height as parameter. If the parameter is
215not specified it will use the default value of 16.
216
217Adding this in the beginning of filter chains should make filtering
218faster due to better use of the memory cache.
219
e0728d79
BB
220@section unsharp
221
222Sharpen or blur the input video. It accepts the following parameters:
223
224@multitable @columnfractions .2 .5 .1 .1 .1
225@headitem Name @tab Description @tab Min @tab Max @tab Default
226@item @var{luma_msize_x}
227@tab Luma matrix horizontal size
228@tab 3
229@tab 13
230@tab 5
231@item @var{luma_msize_y}
232@tab Luma matrix vertical size
233@tab 3
234@tab 13
235@tab 5
236@item @var{luma_amount}
237@tab Luma effect strength
238@tab -2.0
239@tab 5.0
240@tab 1.0
241@item @var{chroma_msize_x}
242@tab Chroma matrix horizontal size
243@tab 3
244@tab 13
245@tab 0
246@item @var{chroma_msize_y}
247@tab Chroma matrix vertical size
248@tab 3
249@tab 13
250@tab 0
251@item @var{chroma_amount}
252@tab Chroma effect strength
253@tab -2.0
254@tab 5.0
255@tab 0.0
256@end multitable
257
258Negative values for the amount will blur the input video, while positive
259values will sharpen. All parameters are optional and default to the
260equivalent of the string '5:5:1.0:0:0:0.0'.
261
262@example
263# Strong luma sharpen effect parameters
264unsharp=7:7:2.5
265
266# Strong blur of both luma and chroma parameters
267unsharp=7:7:-2:7:7:-2
268
269# Use the default values with @command{ffmpeg}
270./ffmpeg -i in.avi -vfilters "unsharp" out.mp4
271@end example
272
c38ae71f
SS
273@section vflip
274
275Flip the input video vertically.
276
277@example
278./ffmpeg -i in.avi -vfilters "vflip" out.avi
279@end example
280
dd08b83c
SS
281@chapter Available video sources
282
283Below is a description of the currently available video sources.
284
285@section nullsrc
286
287Null video source, never return images. It is mainly useful as a
288template and to be employed in analysis / debugging tools.
289
290It accepts as optional parameter a string of the form
291``width:height'', where ``width'' and ``height'' specify the size of
292the configured source.
293
294The default values of ``width'' and ``height'' are respectively 352
295and 288 (corresponding to the CIF size format).
296
006aa1a4
SS
297@chapter Available video sinks
298
299Below is a description of the currently available video sinks.
300
301@section nullsink
302
303Null video sink, do absolutely nothing with the input video. It is
304mainly useful as a template and to be employed in analysis / debugging
305tools.
306
1f09ab5e 307@bye