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