git.sesse.net Git - ffmpeg/blob - 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 A few 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