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 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
  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 The video hook modules are provided for use as a base for your own modules,
  26 and are described below.
  27
  28 Modules are loaded using the -vhook option to ffmpeg. The value of this parameter
  29 is a space separated list of arguments. The first is the module name, and the rest
  30 are passed as arguments to the Configure function of the module.
  31
  32 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 @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 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 is passed through strftime() so that it is easy to imprint the date and
  57 time onto the image.
  58
  59 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 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 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
  75 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 Options:
  80 @multitable @columnfractions .2 .8
  81 @item @option{-C <rgb.txt>}   @tab The filename to read RGB color names from
  82 @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 @item @option{-x <expression>}@tab x coordinate of text or image
  87 @item @option{-y <expression>}@tab y coordinate of text or image
  88 @item @option{-i <filename>}  @tab The filename to read a image from
  89 @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 @end multitable
  94
  95 Expressions are functions of these variables:
  96 @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
 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    # 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    # 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    # 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    # 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 @end example
 188
 189 @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 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
 200 Usage example:
 201
 202 @example
 203 ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
 204 @end example
 205
 206 @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 @bye