Statistics
| Branch: | Revision:

ffmpeg / doc / hooks.texi @ 7cbf432d

History | View | Annotate | Download (10.8 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
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 289a8e4d Piero Bugoni
The video hook modules are provided for use as a base for your own modules,
21
and are described below.
22 26b4bb70 Philip Gladstone
23
Modules are loaded using the -vhook option to ffmpeg. The value of this parameter
24 79cc8267 Diego Biurrun
is a space separated list of arguments. The first is the module name, and the rest
25 26b4bb70 Philip Gladstone
are passed as arguments to the Configure function of the module.
26
27 af437256 Piero Bugoni
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 26b4bb70 Philip Gladstone
@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 abc7202f Víctor Paesa
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 289a8e4d Piero Bugoni
is passed through strftime() so that it is easy to imprint the date and
52 abc7202f Víctor Paesa
time onto the image.
53
54 af437256 Piero Bugoni
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 abc7202f Víctor Paesa
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 289a8e4d Piero Bugoni
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 abc7202f Víctor Paesa
70 6100cb47 Ramiro Polla
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 abc7202f Víctor Paesa
Options:
75
@multitable @columnfractions .2 .8
76 6100cb47 Ramiro Polla
@item @option{-C <rgb.txt>}   @tab The filename to read RGB color names from
77 abc7202f Víctor Paesa
@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 1bebfde9 Ramiro Polla
@item @option{-x <expression>}@tab x coordinate of text or image
82
@item @option{-y <expression>}@tab y coordinate of text or image
83 abc7202f Víctor Paesa
@item @option{-i <filename>}  @tab The filename to read a image from
84
@end multitable
85
86 1bebfde9 Ramiro Polla
Expressions are functions of these variables:
87 abc7202f Víctor Paesa
@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 289a8e4d Piero Bugoni
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 6100cb47 Ramiro Polla
   # 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 41e4c556 Ramiro Polla
   # 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 6f176376 Ramiro Polla
   # Text fade-out
162
   ffmpeg -i input.avi -vhook \
163
     'vhook/imlib2.so -t Hello -A max(0,255-exp(N/47))' \
164
     -sameq output.avi
165
166
     In this example, the text fades out in about 10 seconds for a 25 fps input
167
     video file.
168
169 289a8e4d Piero Bugoni
   # scrolling credits from a graphics file
170
   ffmpeg -sameq -i input.avi \
171
     -vhook 'vhook/imlib2.so -x 0 -y -1.0*N -i credits.png' output.avi
172
173
     In this example, a transparent PNG file the same width as the video
174
     (e.g. 320 pixels), but very long, (e.g. 3000 pixels), was created, and
175
     text, graphics, brushstrokes, etc, were added to the image. The image
176
     is then scrolled up, from the bottom of the frame.
177
178 abc7202f Víctor Paesa
@end example
179 26b4bb70 Philip Gladstone
180 56d2d2d0 Benjamin Larsson
@section ppm.c
181
182
It's basically a launch point for a PPM pipe, so you can use any
183
executable (or script) which consumes a PPM on stdin and produces a PPM
184 289a8e4d Piero Bugoni
on stdout (and flushes each frame). The Netpbm utilities are a series of
185
such programs.
186
187
A list of them is here:
188
189
@url{http://netpbm.sourceforge.net/doc/directory.html}
190 56d2d2d0 Benjamin Larsson
191
Usage example:
192
193
@example
194
ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
195
@end example
196 26b4bb70 Philip Gladstone
197 289a8e4d Piero Bugoni
@section drawtext.c
198
199
This module implements a text overlay for a video image. Currently it
200
supports a fixed overlay or reading the text from a file. The string
201
is passed through strftime() so that it is easy to imprint the date and
202
time onto the image.
203
204
Features:
205
@itemize @minus
206
@item TrueType, Type1 and others via the FreeType2 library
207
@item Font kerning (better output)
208
@item Line Wrap (put the text that doesn't fit one line on the next line)
209
@item Background box (currently in development)
210
@item Outline
211
@end itemize
212
213
Options:
214
@multitable @columnfractions .2 .8
215
@item @option{-c <color>}          @tab Foreground color of the text ('internet' way) <#RRGGBB> [default #FFFFFF]
216
@item @option{-C <color>}          @tab Background color of the text ('internet' way) <#RRGGBB> [default #000000]
217
@item @option{-f <font-filename>}  @tab font file to use
218
@item @option{-t <text>}           @tab text to display
219
@item @option{-T <filename>}       @tab file to read text from
220
@item @option{-x <pos>}            @tab x coordinate of the start of the text
221
@item @option{-y <pos>}            @tab y coordinate of the start of the text
222
@end multitable
223
224
Text fonts are being looked for in a FONTPATH environment variable.
225
If the FONTPATH environment variable is not available, or is not checked by
226
your target (i.e. Cygwin), then specify the full path to the font file as in:
227
@example
228
-f /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf
229
@end example
230
231
Usage Example:
232
@example
233
   # Remember to set the path to your fonts
234
   FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
235
   FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
236
   FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
237
   export FONTPATH
238
239
   # Time and date display
240
   ffmpeg -f video4linux2 -i /dev/video0 \
241
   -vhook 'vhook/drawtext.so -f VeraBd.ttf -t %A-%D-%T' movie.mpg
242
243
     This example grabs video from the first capture card and outputs it to an
244
     MPEG video, and places "Weekday-dd/mm/yy-hh:mm:ss" at the top left of the
245
     frame, updated every second, using the Vera Bold TrueType Font, which
246
     should exist in: /usr/X11R6/lib/X11/fonts/TTF/
247
@end example
248
249
Check the man page for strftime() for all the various ways you can format
250
the date and time.
251
252
@section watermark.c
253
254
Command Line options:
255
@multitable @columnfractions .2 .8
256
@item @option{-m [0|1]}            @tab Mode (default: 0, see below)
257
@item @option{-t 000000 - FFFFFF}  @tab Threshold, six digit hex number
258
@item @option{-f <filename>}       @tab Watermark image filename, must be specified!
259
@end multitable
260
261
MODE 0:
262
 The watermark picture works like this (assuming color intensities 0..0xFF):
263
 Per color do this:
264
 If mask color is 0x80, no change to the original frame.
265
 If mask color is < 0x80 the absolute difference is subtracted from the
266
 frame. If result < 0, result = 0.
267
 If mask color is > 0x80 the absolute difference is added to the
268
 frame. If result > 0xFF, result = 0xFF.
269
270
 You can override the 0x80 level with the -t flag. E.g. if threshold is
271
 000000 the color value of watermark is added to the destination.
272
273
 This way a mask that is visible both in light and dark pictures can be made
274
 (e.g. by using a picture generated by the Gimp and the bump map tool).
275
276
 An example watermark file is at:
277
 @url{http://engene.se/ffmpeg_watermark.gif}
278
279
MODE 1:
280
 Per color do this:
281
 If mask color > threshold color then the watermark pixel is used.
282
283
Example usage:
284
@example
285
   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif' -an out.mov
286
   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif -m 1 -t 222222' -an out.mov
287
@end example
288
289 26b4bb70 Philip Gladstone
@bye