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