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.

Three 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.

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.

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.

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.

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:

-c <color>       The color of the text
-F <fontname>    The font face and size
-t <text>        The text
-f <filename>    The filename to read text from
-x <expresion>   X coordinate of text or image
-y <expresion>   Y coordinate of text or image
-i <filename>    The filename to read a image from

Expresions are functions of these variables:

N   frame number (starting at zero)
H   frame height
W   frame width
H   image height
W   image width
X   previous x coordinate of text or image
Y   previous y coordinate of text or image

You may also use the constants PI, E, and the math functions available at the FFmpeg formula evaluator at (ffmpeg-doc.html#SEC13), except BITS2QP(BITS) and QP2BITS(QP).

Usage examples:

        # 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

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:

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