small updates taken from a patch by Piero Bugoni, crboca32 yahoo com
[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
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 Three modules are provided and are described below. They are all intended to
21 be used as a base for your own modules.
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 Text fonts are being looked for in a FONTPATH environment variable.
63
64 Options:
65 @multitable @columnfractions .2 .8
66 @item @option{-c <color>}     @tab The color of the text
67 @item @option{-F <fontname>}  @tab The font face and size
68 @item @option{-t <text>}      @tab The text
69 @item @option{-f <filename>}  @tab The filename to read text from
70 @item @option{-x <expresion>} @tab X coordinate of text or image
71 @item @option{-y <expresion>} @tab Y coordinate of text or image
72 @item @option{-i <filename>}  @tab The filename to read a image from
73 @end multitable
74
75 Expresions are functions of these variables:
76 @multitable @columnfractions .2 .8
77 @item @var{N} @tab frame number (starting at zero)
78 @item @var{H} @tab frame height
79 @item @var{W} @tab frame width
80 @item @var{h} @tab image height
81 @item @var{w} @tab image width
82 @item @var{X} @tab previous x coordinate of text or image
83 @item @var{Y} @tab previous y coordinate of text or image
84 @end multitable
85
86 You may also use the constants @var{PI}, @var{E}, and the math functions available at the
87 FFmpeg formula evaluator at (@url{ffmpeg-doc.html#SEC13}), except @var{bits2qp(bits)}
88 and @var{qp2bits(qp)}.
89
90 Usage examples:
91
92 @example
93    # Remember to set the path to your fonts
94    FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
95    FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
96    FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
97    export FONTPATH
98
99    # Bulb dancing in a Lissajous pattern
100    ffmpeg -i input.avi -vhook \
101      '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' \
102      -acodec copy -sameq output.avi
103
104    # Text scrolling
105    ffmpeg -i input.avi -vhook \
106      'vhook/imlib2.dll -c red -F Vera.ttf/20 -x 150+0.5*N -y 70+0.25*N -t Hello' \
107      -acodec copy -sameq output.avi
108 @end example
109
110 @section ppm.c
111
112 It's basically a launch point for a PPM pipe, so you can use any
113 executable (or script) which consumes a PPM on stdin and produces a PPM
114 on stdout (and flushes each frame).
115
116 Usage example:
117
118 @example
119 ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
120 @end example
121
122 @bye