AC-3 decoder, soc revision 55, Aug 17 12:25:24 2006 UTC by cloud9
[ffmpeg.git] / doc / hooks.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle Video Hook Documentation
4 @titlepage
5 @sp 7
6 @center @titlefont{Video Hook Documentation}
7 @sp 3
8 @end titlepage
9
10
11 @chapter Introduction
12
13 @var{Please be aware that vhook is deprecated, and hence its development is
14 frozen (bug fixes are still accepted).
15 The substitute will be the result of our 'Video Filter API' Google Summer of Code
16 project. You may monitor its progress by subscribing to the ffmpeg-soc mailing
17 list at @url{http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-soc}.}
18
19 The video hook functionality is designed (mostly) for live video. It allows
20 the video to be modified or examined between the decoder and the encoder.
21
22 Any number of hook modules can be placed inline, and they are run in the
23 order that they were specified on the ffmpeg command line.
24
25 The video hook modules are provided for use as a base for your own modules,
26 and are described below.
27
28 Modules are loaded using the -vhook option to ffmpeg. The value of this parameter
29 is a space separated list of arguments. The first is the module name, and the rest
30 are passed as arguments to the Configure function of the module.
31
32 The modules are dynamic libraries: They have different suffixes (.so, .dll, .dylib)
33 depending on your platform. And your platform dictates if they need to be
34 somewhere in your PATH, or in your LD_LIBRARY_PATH. Otherwise you will need to
35 specify the full path of the vhook file that you are using.
36
37 @section null.c
38
39 This does nothing. Actually it converts the input image to RGB24 and then converts
40 it back again. This is meant as a sample that you can use to test your setup.
41
42 @section fish.c
43
44 This implements a 'fish detector'. Essentially it converts the image into HSV
45 space and tests whether more than a certain percentage of the pixels fall into
46 a specific HSV cuboid. If so, then the image is saved into a file for processing
47 by other bits of code.
48
49 Why use HSV? It turns out that HSV cuboids represent a more compact range of
50 colors than would an RGB cuboid.
51
52 @section imlib2.c
53
54 This module implements a text overlay for a video image. Currently it
55 supports a fixed overlay or reading the text from a file. The string
56 is passed through strftime() so that it is easy to imprint the date and
57 time onto the image.
58
59 This module depends on the external library imlib2, available on
60 Sourceforge, among other places, if it is not already installed on
61 your system.
62
63 You may also overlay an image (even semi-transparent) like TV stations do.
64 You may move either the text or the image around your video to create
65 scrolling credits, for example.
66
67 The font file used is looked for in a FONTPATH environment variable, and
68 prepended to the point size as a command line option and can be specified
69 with the full path to the font file, as in:
70 @example
71 -F /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf/20
72 @end example
73 where 20 is the point size.
74
75 You can specify the filename to read RGB color names from. If none are
76 specified, these defaults are used: @file{/usr/share/X11/rgb.txt} and
77 @file{/usr/lib/X11/rgb.txt}
78
79 Options:
80 @multitable @columnfractions .2 .8
81 @item @option{-C <rgb.txt>}   @tab The filename to read RGB color names from
82 @item @option{-c <color>}     @tab The color of the text
83 @item @option{-F <fontname>}  @tab The font face and size
84 @item @option{-t <text>}      @tab The text
85 @item @option{-f <filename>}  @tab The filename to read text from
86 @item @option{-x <expression>}@tab x coordinate of text or image
87 @item @option{-y <expression>}@tab y coordinate of text or image
88 @item @option{-i <filename>}  @tab The filename to read a image from
89 @end multitable
90
91 Expressions are functions of these variables:
92 @multitable @columnfractions .2 .8
93 @item @var{N} @tab frame number (starting at zero)
94 @item @var{H} @tab frame height
95 @item @var{W} @tab frame width
96 @item @var{h} @tab image height
97 @item @var{w} @tab image width
98 @item @var{X} @tab previous x coordinate of text or image
99 @item @var{Y} @tab previous y coordinate of text or image
100 @end multitable
101
102 You may also use the constants @var{PI}, @var{E}, and the math functions available at the
103 FFmpeg formula evaluator at (@url{ffmpeg-doc.html#SEC13}), except @var{bits2qp(bits)}
104 and @var{qp2bits(qp)}.
105
106 Usage examples:
107
108 @example
109    # Remember to set the path to your fonts
110    FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
111    FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
112    FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
113    export FONTPATH
114
115    # Bulb dancing in a Lissajous pattern
116    ffmpeg -i input.avi -vhook \
117      'vhook/imlib2.dll -x W*(0.5+0.25*sin(N/47*PI))-w/2 -y H*(0.5+0.50*cos(N/97*PI))-h/2 -i /usr/share/imlib2/data/images/bulb.png' \
118      -acodec copy -sameq output.avi
119
120    # Text scrolling
121    ffmpeg -i input.avi -vhook \
122      'vhook/imlib2.dll -c red -F Vera.ttf/20 -x 150+0.5*N -y 70+0.25*N -t Hello' \
123      -acodec copy -sameq output.avi
124
125    # Date and time stamp, security-camera style:
126    ffmpeg -r 29.97 -s 320x256 -f video4linux -i /dev/video0 \
127      -vhook 'vhook/imlib2.so -x 0 -y 0 -i black-260x20.png' \
128      -vhook 'vhook/imlib2.so -c white -F VeraBd.ttf/12 -x 0 -y 0 -t %A-%D-%T' \
129      output.avi
130
131      In this example the video is captured from the first video capture card as a
132      320x256 AVI, and a black 260 by 20 pixel PNG image is placed in the upper
133      left corner, with the day, date and time overlaid on it in Vera Bold 12
134      point font. A simple black PNG file 260 pixels wide and 20 pixels tall
135      was created in the GIMP for this purpose.
136
137    # Scrolling credits from a text file
138    ffmpeg -i input.avi -vhook \
139      'vhook/imlib2.so -c white -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
140      -sameq output.avi
141
142      In this example, the text is stored in a file, and is positioned 100
143      pixels from the left hand edge of the video. The text is scrolled from the
144      bottom up. Making the y factor positive will scroll from the top down.
145      Increasing the magnitude of the y factor makes the text scroll faster,
146      decreasing it makes it scroll slower. Hint: Blank lines containing only
147      a newline are treated as end-of-file. To create blank lines, use lines
148      that consist of space characters only.
149
150    # Scrolling credits with custom color from a text file
151    ffmpeg -i input.avi -vhook \
152      'vhook/imlib2.so -C rgb.txt -c CustomColor1 -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
153      -sameq output.avi
154
155    This example does the same as the one above, but specifies an rgb.txt file
156    to be used, which has a custom made color in it.
157
158    # Variable colors
159    ffmpeg -i input.avi -vhook \
160      'vhook/imlib2.so -t Hello -R abs(255*sin(N/47*PI)) -G abs(255*sin(N/47*PI)) -B abs(255*sin(N/47*PI))' \
161      -sameq output.avi
162
163      In this example, the color for the text goes up and down from black to
164      white.
165
166    # Text fade-out
167    ffmpeg -i input.avi -vhook \
168      'vhook/imlib2.so -t Hello -A max(0,255-exp(N/47))' \
169      -sameq output.avi
170
171      In this example, the text fades out in about 10 seconds for a 25 fps input
172      video file.
173
174    # scrolling credits from a graphics file
175    ffmpeg -sameq -i input.avi \
176      -vhook 'vhook/imlib2.so -x 0 -y -1.0*N -i credits.png' output.avi
177
178      In this example, a transparent PNG file the same width as the video
179      (e.g. 320 pixels), but very long, (e.g. 3000 pixels), was created, and
180      text, graphics, brushstrokes, etc, were added to the image. The image
181      is then scrolled up, from the bottom of the frame.
182
183 @end example
184
185 @section ppm.c
186
187 It's basically a launch point for a PPM pipe, so you can use any
188 executable (or script) which consumes a PPM on stdin and produces a PPM
189 on stdout (and flushes each frame). The Netpbm utilities are a series of
190 such programs.
191
192 A list of them is here:
193
194 @url{http://netpbm.sourceforge.net/doc/directory.html}
195
196 Usage example:
197
198 @example
199 ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
200 @end example
201
202 @section drawtext.c
203
204 This module implements a text overlay for a video image. Currently it
205 supports a fixed overlay or reading the text from a file. The string
206 is passed through strftime() so that it is easy to imprint the date and
207 time onto the image.
208
209 Features:
210 @itemize @minus
211 @item TrueType, Type1 and others via the FreeType2 library
212 @item Font kerning (better output)
213 @item Line Wrap (put the text that doesn't fit one line on the next line)
214 @item Background box (currently in development)
215 @item Outline
216 @end itemize
217
218 Options:
219 @multitable @columnfractions .2 .8
220 @item @option{-c <color>}          @tab Foreground color of the text ('internet' way) <#RRGGBB> [default #FFFFFF]
221 @item @option{-C <color>}          @tab Background color of the text ('internet' way) <#RRGGBB> [default #000000]
222 @item @option{-f <font-filename>}  @tab font file to use
223 @item @option{-t <text>}           @tab text to display
224 @item @option{-T <filename>}       @tab file to read text from
225 @item @option{-x <pos>}            @tab x coordinate of the start of the text
226 @item @option{-y <pos>}            @tab y coordinate of the start of the text
227 @end multitable
228
229 Text fonts are being looked for in a FONTPATH environment variable.
230 If the FONTPATH environment variable is not available, or is not checked by
231 your target (i.e. Cygwin), then specify the full path to the font file as in:
232 @example
233 -f /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf
234 @end example
235
236 Usage Example:
237 @example
238    # Remember to set the path to your fonts
239    FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
240    FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
241    FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
242    export FONTPATH
243
244    # Time and date display
245    ffmpeg -f video4linux2 -i /dev/video0 \
246    -vhook 'vhook/drawtext.so -f VeraBd.ttf -t %A-%D-%T' movie.mpg
247
248      This example grabs video from the first capture card and outputs it to an
249      MPEG video, and places "Weekday-dd/mm/yy-hh:mm:ss" at the top left of the
250      frame, updated every second, using the Vera Bold TrueType Font, which
251      should exist in: /usr/X11R6/lib/X11/fonts/TTF/
252 @end example
253
254 Check the man page for strftime() for all the various ways you can format
255 the date and time.
256
257 @section watermark.c
258
259 Command Line options:
260 @multitable @columnfractions .2 .8
261 @item @option{-m [0|1]}            @tab Mode (default: 0, see below)
262 @item @option{-t 000000 - FFFFFF}  @tab Threshold, six digit hex number
263 @item @option{-f <filename>}       @tab Watermark image filename, must be specified!
264 @end multitable
265
266 MODE 0:
267  The watermark picture works like this (assuming color intensities 0..0xFF):
268  Per color do this:
269  If mask color is 0x80, no change to the original frame.
270  If mask color is < 0x80 the absolute difference is subtracted from the
271  frame. If result < 0, result = 0.
272  If mask color is > 0x80 the absolute difference is added to the
273  frame. If result > 0xFF, result = 0xFF.
274
275  You can override the 0x80 level with the -t flag. E.g. if threshold is
276  000000 the color value of watermark is added to the destination.
277
278  This way a mask that is visible both in light and dark pictures can be made
279  (e.g. by using a picture generated by the Gimp and the bump map tool).
280
281  An example watermark file is at:
282  @url{http://engene.se/ffmpeg_watermark.gif}
283
284 MODE 1:
285  Per color do this:
286  If mask color > threshold color then the watermark pixel is used.
287
288 Example usage:
289 @example
290    ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif' -an out.mov
291    ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif -m 1 -t 222222' -an out.mov
292 @end example
293
294 @bye