Statistics
| Branch: | Revision:

ffmpeg / doc / hooks.texi @ 41415d28

History | View | Annotate | Download (11.4 KB)

1 26b4bb70 Philip Gladstone
\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 73609051 Víctor Paesa
@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 26b4bb70 Philip Gladstone
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 289a8e4d Piero Bugoni
The video hook modules are provided for use as a base for your own modules,
26
and are described below.
27 26b4bb70 Philip Gladstone
28
Modules are loaded using the -vhook option to ffmpeg. The value of this parameter
29 79cc8267 Diego Biurrun
is a space separated list of arguments. The first is the module name, and the rest
30 26b4bb70 Philip Gladstone
are passed as arguments to the Configure function of the module.
31
32 af437256 Piero Bugoni
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 26b4bb70 Philip Gladstone
@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 abc7202f Víctor Paesa
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 289a8e4d Piero Bugoni
is passed through strftime() so that it is easy to imprint the date and
57 abc7202f Víctor Paesa
time onto the image.
58
59 af437256 Piero Bugoni
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 abc7202f Víctor Paesa
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 289a8e4d Piero Bugoni
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 abc7202f Víctor Paesa
75 6100cb47 Ramiro Polla
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 abc7202f Víctor Paesa
Options:
80
@multitable @columnfractions .2 .8
81 6100cb47 Ramiro Polla
@item @option{-C <rgb.txt>}   @tab The filename to read RGB color names from
82 abc7202f Víctor Paesa
@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 1bebfde9 Ramiro Polla
@item @option{-x <expression>}@tab x coordinate of text or image
87
@item @option{-y <expression>}@tab y coordinate of text or image
88 abc7202f Víctor Paesa
@item @option{-i <filename>}  @tab The filename to read a image from
89 f0326fde Ramiro Polla
@item @option{-R <expression>}@tab Value for R color
90
@item @option{-G <expression>}@tab Value for G color
91
@item @option{-B <expression>}@tab Value for B color
92
@item @option{-A <expression>}@tab Value for Alpha channel
93 abc7202f Víctor Paesa
@end multitable
94
95 1bebfde9 Ramiro Polla
Expressions are functions of these variables:
96 abc7202f Víctor Paesa
@multitable @columnfractions .2 .8
97
@item @var{N} @tab frame number (starting at zero)
98
@item @var{H} @tab frame height
99
@item @var{W} @tab frame width
100
@item @var{h} @tab image height
101
@item @var{w} @tab image width
102
@item @var{X} @tab previous x coordinate of text or image
103
@item @var{Y} @tab previous y coordinate of text or image
104
@end multitable
105
106
You may also use the constants @var{PI}, @var{E}, and the math functions available at the
107
FFmpeg formula evaluator at (@url{ffmpeg-doc.html#SEC13}), except @var{bits2qp(bits)}
108
and @var{qp2bits(qp)}.
109
110
Usage examples:
111
112
@example
113
   # Remember to set the path to your fonts
114
   FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
115
   FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
116
   FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
117
   export FONTPATH
118
119
   # Bulb dancing in a Lissajous pattern
120
   ffmpeg -i input.avi -vhook \
121
     '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' \
122
     -acodec copy -sameq output.avi
123
124
   # Text scrolling
125
   ffmpeg -i input.avi -vhook \
126
     'vhook/imlib2.dll -c red -F Vera.ttf/20 -x 150+0.5*N -y 70+0.25*N -t Hello' \
127
     -acodec copy -sameq output.avi
128 289a8e4d Piero Bugoni
129
   # Date and time stamp, security-camera style:
130
   ffmpeg -r 29.97 -s 320x256 -f video4linux -i /dev/video0 \
131
     -vhook 'vhook/imlib2.so -x 0 -y 0 -i black-260x20.png' \
132
     -vhook 'vhook/imlib2.so -c white -F VeraBd.ttf/12 -x 0 -y 0 -t %A-%D-%T' \
133
     output.avi
134
135
     In this example the video is captured from the first video capture card as a
136
     320x256 AVI, and a black 260 by 20 pixel PNG image is placed in the upper
137
     left corner, with the day, date and time overlaid on it in Vera Bold 12
138
     point font. A simple black PNG file 260 pixels wide and 20 pixels tall
139
     was created in the GIMP for this purpose.
140
141
   # Scrolling credits from a text file
142
   ffmpeg -i input.avi -vhook \
143
     'vhook/imlib2.so -c white -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
144
     -sameq output.avi
145
146
     In this example, the text is stored in a file, and is positioned 100
147
     pixels from the left hand edge of the video. The text is scrolled from the
148
     bottom up. Making the y factor positive will scroll from the top down.
149
     Increasing the magnitude of the y factor makes the text scroll faster,
150
     decreasing it makes it scroll slower. Hint: Blank lines containing only
151
     a newline are treated as end-of-file. To create blank lines, use lines
152
     that consist of space characters only.
153
154 6100cb47 Ramiro Polla
   # Scrolling credits with custom color from a text file
155
   ffmpeg -i input.avi -vhook \
156
     'vhook/imlib2.so -C rgb.txt -c CustomColor1 -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
157
     -sameq output.avi
158
159
   This example does the same as the one above, but specifies an rgb.txt file
160
   to be used, which has a custom made color in it.
161
162 41e4c556 Ramiro Polla
   # Variable colors
163
   ffmpeg -i input.avi -vhook \
164
     '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))' \
165
     -sameq output.avi
166
167
     In this example, the color for the text goes up and down from black to
168
     white.
169
170 6f176376 Ramiro Polla
   # Text fade-out
171
   ffmpeg -i input.avi -vhook \
172
     'vhook/imlib2.so -t Hello -A max(0,255-exp(N/47))' \
173
     -sameq output.avi
174
175
     In this example, the text fades out in about 10 seconds for a 25 fps input
176
     video file.
177
178 289a8e4d Piero Bugoni
   # scrolling credits from a graphics file
179
   ffmpeg -sameq -i input.avi \
180
     -vhook 'vhook/imlib2.so -x 0 -y -1.0*N -i credits.png' output.avi
181
182
     In this example, a transparent PNG file the same width as the video
183
     (e.g. 320 pixels), but very long, (e.g. 3000 pixels), was created, and
184
     text, graphics, brushstrokes, etc, were added to the image. The image
185
     is then scrolled up, from the bottom of the frame.
186
187 abc7202f Víctor Paesa
@end example
188 26b4bb70 Philip Gladstone
189 56d2d2d0 Benjamin Larsson
@section ppm.c
190
191
It's basically a launch point for a PPM pipe, so you can use any
192
executable (or script) which consumes a PPM on stdin and produces a PPM
193 289a8e4d Piero Bugoni
on stdout (and flushes each frame). The Netpbm utilities are a series of
194
such programs.
195
196
A list of them is here:
197
198
@url{http://netpbm.sourceforge.net/doc/directory.html}
199 56d2d2d0 Benjamin Larsson
200
Usage example:
201
202
@example
203
ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
204
@end example
205 26b4bb70 Philip Gladstone
206 289a8e4d Piero Bugoni
@section drawtext.c
207
208
This module implements a text overlay for a video image. Currently it
209
supports a fixed overlay or reading the text from a file. The string
210
is passed through strftime() so that it is easy to imprint the date and
211
time onto the image.
212
213
Features:
214
@itemize @minus
215
@item TrueType, Type1 and others via the FreeType2 library
216
@item Font kerning (better output)
217
@item Line Wrap (put the text that doesn't fit one line on the next line)
218
@item Background box (currently in development)
219
@item Outline
220
@end itemize
221
222
Options:
223
@multitable @columnfractions .2 .8
224
@item @option{-c <color>}          @tab Foreground color of the text ('internet' way) <#RRGGBB> [default #FFFFFF]
225
@item @option{-C <color>}          @tab Background color of the text ('internet' way) <#RRGGBB> [default #000000]
226
@item @option{-f <font-filename>}  @tab font file to use
227
@item @option{-t <text>}           @tab text to display
228
@item @option{-T <filename>}       @tab file to read text from
229
@item @option{-x <pos>}            @tab x coordinate of the start of the text
230
@item @option{-y <pos>}            @tab y coordinate of the start of the text
231
@end multitable
232
233
Text fonts are being looked for in a FONTPATH environment variable.
234
If the FONTPATH environment variable is not available, or is not checked by
235
your target (i.e. Cygwin), then specify the full path to the font file as in:
236
@example
237
-f /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf
238
@end example
239
240
Usage Example:
241
@example
242
   # Remember to set the path to your fonts
243
   FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
244
   FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
245
   FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
246
   export FONTPATH
247
248
   # Time and date display
249
   ffmpeg -f video4linux2 -i /dev/video0 \
250
   -vhook 'vhook/drawtext.so -f VeraBd.ttf -t %A-%D-%T' movie.mpg
251
252
     This example grabs video from the first capture card and outputs it to an
253
     MPEG video, and places "Weekday-dd/mm/yy-hh:mm:ss" at the top left of the
254
     frame, updated every second, using the Vera Bold TrueType Font, which
255
     should exist in: /usr/X11R6/lib/X11/fonts/TTF/
256
@end example
257
258
Check the man page for strftime() for all the various ways you can format
259
the date and time.
260
261
@section watermark.c
262
263
Command Line options:
264
@multitable @columnfractions .2 .8
265
@item @option{-m [0|1]}            @tab Mode (default: 0, see below)
266
@item @option{-t 000000 - FFFFFF}  @tab Threshold, six digit hex number
267
@item @option{-f <filename>}       @tab Watermark image filename, must be specified!
268
@end multitable
269
270
MODE 0:
271
 The watermark picture works like this (assuming color intensities 0..0xFF):
272
 Per color do this:
273
 If mask color is 0x80, no change to the original frame.
274
 If mask color is < 0x80 the absolute difference is subtracted from the
275
 frame. If result < 0, result = 0.
276
 If mask color is > 0x80 the absolute difference is added to the
277
 frame. If result > 0xFF, result = 0xFF.
278
279
 You can override the 0x80 level with the -t flag. E.g. if threshold is
280
 000000 the color value of watermark is added to the destination.
281
282
 This way a mask that is visible both in light and dark pictures can be made
283
 (e.g. by using a picture generated by the Gimp and the bump map tool).
284
285
 An example watermark file is at:
286
 @url{http://engene.se/ffmpeg_watermark.gif}
287
288
MODE 1:
289
 Per color do this:
290
 If mask color > threshold color then the watermark pixel is used.
291
292
Example usage:
293
@example
294
   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif' -an out.mov
295
   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif -m 1 -t 222222' -an out.mov
296
@end example
297
298 26b4bb70 Philip Gladstone
@bye