ffmpeg/doc/hooks.texi

\input texinfo @c -*- texinfo -*-

@settitle Video Hook Documentation
@titlepage
@sp 7
@center @titlefont{Video Hook Documentation}
@sp 3
@end titlepage


@chapter Introduction


The video hook functionality is designed (mostly) for live video. It allows
the video to be modified or examined between the decoder and the encoder.

Any number of hook modules can be placed inline, and they are run in the
order that they were specified on the ffmpeg command line.

A few modules are provided and are described below. They are all intended to
be used as a base for your own modules.

Modules are loaded using the -vhook option to ffmpeg. The value of this parameter
is a space separated list of arguments. The first is the module name, and the rest
are passed as arguments to the Configure function of the module.

The modules are dynamic libraries: They have different suffixes (.so, .dll, .dylib)
depending on your platform. And your platform dictates if they need to be
somewhere in your PATH, or in your LD_LIBRARY_PATH. Otherwise you will need to
specify the full path of the vhook file that you are using.

@section null.c

This does nothing. Actually it converts the input image to RGB24 and then converts
it back again. This is meant as a sample that you can use to test your setup.

@section fish.c

This implements a 'fish detector'. Essentially it converts the image into HSV
space and tests whether more than a certain percentage of the pixels fall into
a specific HSV cuboid. If so, then the image is saved into a file for processing
by other bits of code.

Why use HSV? It turns out that HSV cuboids represent a more compact range of
colors than would an RGB cuboid.

@section imlib2.c

This module implements a text overlay for a video image. Currently it
supports a fixed overlay or reading the text from a file. The string
is passed through strftime so that it is easy to imprint the date and
time onto the image.

This module depends on the external library imlib2, available on
Sourceforge, among other places, if it is not already installed on
your system.

You may also overlay an image (even semi-transparent) like TV stations do.
You may move either the text or the image around your video to create
scrolling credits, for example.

Text fonts are being looked for in a FONTPATH environment variable.

Options:
@multitable @columnfractions .2 .8
@item @option{-c <color>}     @tab The color of the text
@item @option{-F <fontname>}  @tab The font face and size
@item @option{-t <text>}      @tab The text
@item @option{-f <filename>}  @tab The filename to read text from
@item @option{-x <expresion>} @tab X coordinate of text or image
@item @option{-y <expresion>} @tab Y coordinate of text or image
@item @option{-i <filename>}  @tab The filename to read a image from
@end multitable

Expresions are functions of these variables:
@multitable @columnfractions .2 .8
@item @var{N} @tab frame number (starting at zero)
@item @var{H} @tab frame height
@item @var{W} @tab frame width
@item @var{h} @tab image height
@item @var{w} @tab image width
@item @var{X} @tab previous x coordinate of text or image
@item @var{Y} @tab previous y coordinate of text or image
@end multitable

You may also use the constants @var{PI}, @var{E}, and the math functions available at the
FFmpeg formula evaluator at (@url{ffmpeg-doc.html#SEC13}), except @var{bits2qp(bits)}
and @var{qp2bits(qp)}.

Usage examples:

@example
   # Remember to set the path to your fonts
   FONTPATH="/cygdrive/c/WINDOWS/Fonts/"
   FONTPATH="$FONTPATH:/usr/share/imlib2/data/fonts/"
   FONTPATH="$FONTPATH:/usr/X11R6/lib/X11/fonts/TTF/"
   export FONTPATH

   # Bulb dancing in a Lissajous pattern
   ffmpeg -i input.avi -vhook \
     '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' \
     -acodec copy -sameq output.avi

   # Text scrolling
   ffmpeg -i input.avi -vhook \
     'vhook/imlib2.dll -c red -F Vera.ttf/20 -x 150+0.5*N -y 70+0.25*N -t Hello' \
     -acodec copy -sameq output.avi
@end example

@section ppm.c

It's basically a launch point for a PPM pipe, so you can use any
executable (or script) which consumes a PPM on stdin and produces a PPM
on stdout (and flushes each frame).

Usage example:

@example
ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
@end example

@bye