1 files changed, 260 insertions, 0 deletions
diff --git a/contrib/ffmpeg/doc/hooks.texi b/contrib/ffmpeg/doc/hooks.texi
new file mode 100644
index 000000000..49504509f
--- /dev/null
+++ b/contrib/ffmpeg/doc/hooks.texi
@@ -0,0 +1,260 @@
+\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.
+
+The video hook modules are provided for use as a base for your own modules,
+and are described below.
+
+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.
+
+The font file used is looked for in a FONTPATH environment variable, and
+prepended to the point size as a command line option and can be specified
+with the full path to the font file, as in:
+@example
+-F /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf/20
+@end example
+where 20 is the point size.
+
+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
+
+   # Date and time stamp, security-camera style:
+   ffmpeg -r 29.97 -s 320x256 -f video4linux -i /dev/video0 \
+     -vhook 'vhook/imlib2.so -x 0 -y 0 -i black-260x20.png' \
+     -vhook 'vhook/imlib2.so -c white -F VeraBd.ttf/12 -x 0 -y 0 -t %A-%D-%T' \
+     output.avi
+
+     In this example the video is captured from the first video capture card as a
+     320x256 AVI, and a black 260 by 20 pixel PNG image is placed in the upper
+     left corner, with the day, date and time overlaid on it in Vera Bold 12
+     point font. A simple black PNG file 260 pixels wide and 20 pixels tall
+     was created in the GIMP for this purpose.
+
+   # Scrolling credits from a text file
+   ffmpeg -i input.avi -vhook \
+     'vhook/imlib2.so -c white -F VeraBd.ttf/16 -x 100 -y -1.0*N -f credits.txt' \
+     -sameq output.avi
+
+     In this example, the text is stored in a file, and is positioned 100
+     pixels from the left hand edge of the video. The text is scrolled from the
+     bottom up. Making the y factor positive will scroll from the top down.
+     Increasing the magnitude of the y factor makes the text scroll faster,
+     decreasing it makes it scroll slower. Hint: Blank lines containing only
+     a newline are treated as end-of-file. To create blank lines, use lines
+     that consist of space characters only.
+
+   # scrolling credits from a graphics file
+   ffmpeg -sameq -i input.avi \
+     -vhook 'vhook/imlib2.so -x 0 -y -1.0*N -i credits.png' output.avi
+
+     In this example, a transparent PNG file the same width as the video
+     (e.g. 320 pixels), but very long, (e.g. 3000 pixels), was created, and
+     text, graphics, brushstrokes, etc, were added to the image. The image
+     is then scrolled up, from the bottom of the frame.
+
+@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). The Netpbm utilities are a series of
+such programs.
+
+A list of them is here:
+
+@url{http://netpbm.sourceforge.net/doc/directory.html}
+
+Usage example:
+
+@example
+ffmpeg -i input -vhook "/path/to/ppm.so some-ppm-filter args" output
+@end example
+
+@section drawtext.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.
+
+Features:
+@itemize @minus
+@item TrueType, Type1 and others via the FreeType2 library
+@item Font kerning (better output)
+@item Line Wrap (put the text that doesn't fit one line on the next line)
+@item Background box (currently in development)
+@item Outline
+@end itemize
+
+Options:
+@multitable @columnfractions .2 .8
+@item @option{-c <color>}          @tab Foreground color of the text ('internet' way) <#RRGGBB> [default #FFFFFF]
+@item @option{-C <color>}          @tab Background color of the text ('internet' way) <#RRGGBB> [default #000000]
+@item @option{-f <font-filename>}  @tab font file to use
+@item @option{-t <text>}           @tab text to display
+@item @option{-T <filename>}       @tab file to read text from
+@item @option{-x <pos>}            @tab x coordinate of the start of the text
+@item @option{-y <pos>}            @tab y coordinate of the start of the text
+@end multitable
+
+Text fonts are being looked for in a FONTPATH environment variable.
+If the FONTPATH environment variable is not available, or is not checked by
+your target (i.e. Cygwin), then specify the full path to the font file as in:
+@example
+-f /usr/X11R6/lib/X11/fonts/TTF/VeraBd.ttf
+@end example
+
+Usage Example:
+@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
+
+   # Time and date display
+   ffmpeg -f video4linux2 -i /dev/video0 \
+   -vhook 'vhook/drawtext.so -f VeraBd.ttf -t %A-%D-%T' movie.mpg
+
+     This example grabs video from the first capture card and outputs it to an
+     MPEG video, and places "Weekday-dd/mm/yy-hh:mm:ss" at the top left of the
+     frame, updated every second, using the Vera Bold TrueType Font, which
+     should exist in: /usr/X11R6/lib/X11/fonts/TTF/
+@end example
+
+Check the man page for strftime() for all the various ways you can format
+the date and time.
+
+@section watermark.c
+
+Command Line options:
+@multitable @columnfractions .2 .8
+@item @option{-m [0|1]}            @tab Mode (default: 0, see below)
+@item @option{-t 000000 - FFFFFF}  @tab Threshold, six digit hex number
+@item @option{-f <filename>}       @tab Watermark image filename, must be specified!
+@end multitable
+
+MODE 0:
+ The watermark picture works like this (assuming color intensities 0..0xFF):
+ Per color do this:
+ If mask color is 0x80, no change to the original frame.
+ If mask color is < 0x80 the absolute difference is subtracted from the
+ frame. If result < 0, result = 0.
+ If mask color is > 0x80 the absolute difference is added to the
+ frame. If result > 0xFF, result = 0xFF.
+
+ You can override the 0x80 level with the -t flag. E.g. if threshold is
+ 000000 the color value of watermark is added to the destination.
+
+ This way a mask that is visible both in light and dark pictures can be made
+ (e.g. by using a picture generated by the Gimp and the bump map tool).
+
+ An example watermark file is at:
+ @url{http://engene.se/ffmpeg_watermark.gif}
+
+MODE 1:
+ Per color do this:
+ If mask color > threshold color then the watermark pixel is used.
+
+Example usage:
+@example
+   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif' -an out.mov
+   ffmpeg -i infile -vhook '/path/watermark.so -f wm.gif -m 1 -t 222222' -an out.mov
+@end example
+
+@bye