1 \input texinfo @c -*- texinfo -*-
3 @settitle Video Hook Documentation
6 @center @titlefont{Video Hook Documentation}
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.
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.
20 The video hook modules are provided for use as a base for your own modules,
21 and are described below.
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.
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.
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.
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.
44 Why use HSV? It turns out that HSV cuboids represent a more compact range of
45 colors than would an RGB cuboid.
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
54 This module depends on the external library imlib2, available on
55 Sourceforge, among other places, if it is not already installed on
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.
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:
66 -F /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf/20
68 where 20 is the point size.
71 @multitable @columnfractions .2 .8
72 @item @option{-c <color>} @tab The color of the text
73 @item @option{-F <fontname>} @tab The font face and size
74 @item @option{-t <text>} @tab The text
75 @item @option{-f <filename>} @tab The filename to read text from
76 @item @option{-x <expresion>} @tab x coordinate of text or image
77 @item @option{-y <expresion>} @tab y coordinate of text or image
78 @item @option{-i <filename>} @tab The filename to read a image from
81 Expresions are functions of these variables:
82 @multitable @columnfractions .2 .8
83 @item @var{N} @tab frame number (starting at zero)
84 @item @var{H} @tab frame height
85 @item @var{W} @tab frame width
86 @item @var{h} @tab image height
87 @item @var{w} @tab image width
88 @item @var{X} @tab previous x coordinate of text or image
89 @item @var{Y} @tab previous y coordinate of text or image
92 You may also use the constants @var{PI}, @var{E}, and the math functions available at the
93 FFmpeg formula evaluator at (@url{ffmpeg-doc.html#SEC13}), except @var{bits2qp(bits)}
94 and @var{qp2bits(qp)}.
99 # Remember to set the path to your fonts
100 FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
101 FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
102 FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
105 # Bulb dancing in a Lissajous pattern
106 ffmpeg -i input.avi -vhook \
107 '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' \
108 -acodec copy -sameq output.avi
111 ffmpeg -i input.avi -vhook \
112 'vhook/imlib2.dll -c red -F Vera.ttf/20 -x 150+0.5*N -y 70+0.25*N -t Hello' \
113 -acodec copy -sameq output.avi
115 # Date and time stamp, security-camera style:
116 ffmpeg -r 29.97 -s 320x256 -f video4linux -i /dev/video0 \
117 -vhook 'vhook/imlib2.so -x 0 -y 0 -i black-260x20.png' \
118 -vhook 'vhook/imlib2.so -c white -F VeraBd.ttf/12 -x 0 -y 0 -t %A-%D-%T' \
121 In this example the video is captured from the first video capture card as a
122 320x256 AVI, and a black 260 by 20 pixel PNG image is placed in the upper
123 left corner, with the day, date and time overlaid on it in Vera Bold 12
124 point font. A simple black PNG file 260 pixels wide and 20 pixels tall
125 was created in the GIMP for this purpose.
127 # Scrolling credits from a text file
128 ffmpeg -i input.avi -vhook \
129 'vhook/imlib2.so -c white -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
132 In this example, the text is stored in a file, and is positioned 100
133 pixels from the left hand edge of the video. The text is scrolled from the
134 bottom up. Making the y factor positive will scroll from the top down.
135 Increasing the magnitude of the y factor makes the text scroll faster,
136 decreasing it makes it scroll slower. Hint: Blank lines containing only
137 a newline are treated as end-of-file. To create blank lines, use lines
138 that consist of space characters only.
140 # scrolling credits from a graphics file
141 ffmpeg -sameq -i input.avi \
142 -vhook 'vhook/imlib2.so -x 0 -y -1.0*N -i credits.png' output.avi
144 In this example, a transparent PNG file the same width as the video
145 (e.g. 320 pixels), but very long, (e.g. 3000 pixels), was created, and
146 text, graphics, brushstrokes, etc, were added to the image. The image
147 is then scrolled up, from the bottom of the frame.
153 It's basically a launch point for a PPM pipe, so you can use any
154 executable (or script) which consumes a PPM on stdin and produces a PPM
155 on stdout (and flushes each frame). The Netpbm utilities are a series of
158 A list of them is here:
160 @url{http://netpbm.sourceforge.net/doc/directory.html}
165 ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
170 This module implements a text overlay for a video image. Currently it
171 supports a fixed overlay or reading the text from a file. The string
172 is passed through strftime() so that it is easy to imprint the date and
177 @item TrueType, Type1 and others via the FreeType2 library
178 @item Font kerning (better output)
179 @item Line Wrap (put the text that doesn't fit one line on the next line)
180 @item Background box (currently in development)
185 @multitable @columnfractions .2 .8
186 @item @option{-c <color>} @tab Foreground color of the text ('internet' way) <#RRGGBB> [default #FFFFFF]
187 @item @option{-C <color>} @tab Background color of the text ('internet' way) <#RRGGBB> [default #000000]
188 @item @option{-f <font-filename>} @tab font file to use
189 @item @option{-t <text>} @tab text to display
190 @item @option{-T <filename>} @tab file to read text from
191 @item @option{-x <pos>} @tab x coordinate of the start of the text
192 @item @option{-y <pos>} @tab y coordinate of the start of the text
195 Text fonts are being looked for in a FONTPATH environment variable.
196 If the FONTPATH environment variable is not available, or is not checked by
197 your target (i.e. Cygwin), then specify the full path to the font file as in:
199 -f /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf
204 # Remember to set the path to your fonts
205 FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
206 FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
207 FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
210 # Time and date display
211 ffmpeg -f video4linux2 -i /dev/video0 \
212 -vhook 'vhook/drawtext.so -f VeraBd.ttf -t %A-%D-%T' movie.mpg
214 This example grabs video from the first capture card and outputs it to an
215 MPEG video, and places "Weekday-dd/mm/yy-hh:mm:ss" at the top left of the
216 frame, updated every second, using the Vera Bold TrueType Font, which
217 should exist in: /usr/X11R6/lib/X11/fonts/TTF/
220 Check the man page for strftime() for all the various ways you can format
225 Command Line options:
226 @multitable @columnfractions .2 .8
227 @item @option{-m [0|1]} @tab Mode (default: 0, see below)
228 @item @option{-t 000000 - FFFFFF} @tab Threshold, six digit hex number
229 @item @option{-f <filename>} @tab Watermark image filename, must be specified!
233 The watermark picture works like this (assuming color intensities 0..0xFF):
235 If mask color is 0x80, no change to the original frame.
236 If mask color is < 0x80 the absolute difference is subtracted from the
237 frame. If result < 0, result = 0.
238 If mask color is > 0x80 the absolute difference is added to the
239 frame. If result > 0xFF, result = 0xFF.
241 You can override the 0x80 level with the -t flag. E.g. if threshold is
242 000000 the color value of watermark is added to the destination.
244 This way a mask that is visible both in light and dark pictures can be made
245 (e.g. by using a picture generated by the Gimp and the bump map tool).
247 An example watermark file is at:
248 @url{http://engene.se/ffmpeg_watermark.gif}
252 If mask color > threshold color then the watermark pixel is used.
256 ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif' -an out.mov
257 ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif -m 1 -t 222222' -an out.mov