video.doc

reduced python source for embedded apps

	CMIF video tools

This document gives a quick introduction to some of the tools useful
for recording, editing and playing back video data in CMIF video
format. All the tools mentioned currently live in /ufs/guido/bin/sgi.
A description of the CMIF video file format can be found in
/ufs/jack/cmif-film.ms. 

	Recording video

There are two tools to record video, Vrec and and Vrecb. Vrec does
continuous capture, but can capture at most 15 frames per second.
Vrecb uses burst capture, enabling it to capture all frames. It
captures to main memory, however, so it cannot handle long video
fragments. The following options are common to both programs:

 -r rate	Capture one out of 'rate' frames. Default (and
		minimum) is 1 for Vrecb, 2 for Vrec. There are some
		caveats for recording PAL, see below.
 -w width	Set initial window width (and height, implicitly).
 -g bits	Create greyscale film in stead of 8-bit dithered color
		film. Allowable values for 'bits' are 2, 4 or 8.
 -m		Create monochrome dithered film. These look horrible.
 -M threshold	Create monochrome thresholded film with specified
		threshold (in range 0..255).
 -G		Create 2-bit dithered greyscale film.
 -f		Capture fields in stead of frames. The film is created
		in such a way that the picture will be suitably
		enlarged on playback, so aspect ratio, etc. are
		maintained.
 -d		Drop fields if they would cause data from two video
		fields to be combined. See the section on PAL for more
		details. 

Options for Vrec:
 -a		Record audio as well. You will have to twiddle audio
		and video later if you want lipsync playback.
 -q queuesize	Set size of the video board circular buffer. A little
		experimentation with this may lead to more video being
		captured, but not always.
 -P frames	Preallocate diskspace for 'frames' images. This may
		enable you to capture more frames.

Options for Vrecb:
 -n number	Capture 'number' frames. Default is 60 (2 seconds).

Both programs accept a filename to store the video on (default
film.video) and Vrec also accepts an audio file name (default
film.aiff). When you want to record you press the left mouse button.
Vrec stops recording when you release the mouse button and Vrecb stops
after the predetermined number of frames have been recorded. During
recording the picture may look funny, but do not let this worry you,
the film will be ok.

After recording and saving, Vrec will print the deltas of the field
numbers recorded. A list of '4 4 4 4'... means that all possible
frames (one out of two) have been recorded. Vrecb will tell you how
many duplicate fields have been skipped. See below on PAL useage
again.

	PAL caveats

The IndigoVideo board converts the incoming video signal to the 60Hz
(59.something, actually) display rate. All further operations,
including capture, are done with respect to display rate. This is
especially bothersome in the case of PAL video, since it means one out
of 5 frames will be duplicated. Together with the fact that, in
continuous capture, you can only capture every second frame this leads
to strange and wondrous effects. The frame numbers returned by the
video board (and displayed by Vrec) are display frame numbers, and so
bear only a very complicated (and probably non-deterministic) relation
to PAL frame numbers. For recording simple videos this is probably no
problem. You can use Vrec and try using -d to see which gives the best
result. On the other hand, if you need every frame and no duplicates
either you have to use Vrecb and supply the -d and -f option. This
will give you exactly the fields as they appeared on the PAL tape.

	Video playback

The easiest way to play back a video is to use Vplay. Calling it with
an argument of -? will make it list all its options. A few options may
need a bit of explanation:
 -M magnify	Magnify the images by the given factor. This still
		takes any magnification specified in the film (if it
		is a field film, for instance) in account.
 -w width and
 -h height	Normally the window will be the correct size for the
		film. You can set height and width, though, if you
		want the window to be bigger. This is especially
		useful if you want to record the film back to
		videotape, since you can playback in a window that is
		bigger than PAL size with a black background and you
		will have no distracting window-manager thingies on
		your videotape.

	Video Editing

Vedit is a (very simple) video editor that allows you to select images
from the input movie and copy them to an output movie. Both input and
output films have a modest buffer that you can move around in.

Vaddcache takes a movie and adds a frame location cache to it. This
will make some other programs run faster.

rgb2video converts a set of SGI .rgb files to a movie.

There are a few programs that can do image format conversion on movies
(i.e. convert an 8-bit dithered RGB movie to a greyscale movie), but
nothing very complete yet. Look at Vcopy.py for more information.