CMIF video tools
================

This directory contains Python and C programs to manipulate files
containing digitized video in the "CMIF video format".


History
-------

We started this in October 1991, when we had a large framegrabber
board on loan from SGI for a few weeks: we developed a movie recording
program (camcorder.py) and added numerous features, including still
frame capture and synchronous sound recording using a second machine
(the machine holding the framegrabber board didn't have audio).

During the following months, when we started using and processing the
recorded film fragments, the "CMIF video format" was revised several
times, and we eventually created an object-oriented interface for
reading and writing various incarnations of these files, called VFile.
(This module is also used by our flagship application, the CMIF
editor, not in this directory but in /ufs/guido/mm/.)

When we got our own Indigo entry-level video board (in June 1992) and
a version of the Irix video library that supported capturing PAL
format (in August 1992), Sjoerd added an interface to the video
library to Python (sv) and Guido wrote Vrec.py (based upon a still
frame grabber by Sjoerd, in turn based upon SGI demo code in C) to
record a movie using it.  Vrec was soon followed by modernized
versions of the other programs (Vinfo, Vplay, Vtime) and an
interactive editor (Vedit).  Finally, VFile was rewritten for more
modularity, functionality and robustness, and various other tools were
added as needed.

	Guido van Rossum
	Jack Jansen
	Sjoerd Mullender


Overview of files
-----------------

cmif-film.ms	description of the CMIF video file format (a little
		out of date)


These are programs with a command line interface:

Vrec.py		record video movies using the Indigo video library and
		board

Vplay.py	play video movies

Vinfo.py	show statistics on movies

Vtime.py	(unrelated to vtime!!!) Copy a video file,
		manipulating the time codes (e.g. faster/slower, or
		regenerate time codes, or drop frames too close apart)

Vmkjpeg.py	compress an rgb or grey video file to jpeg[grey] format

Vunjpeg.py	expand a jpeg[grey] video file to rgb or grey format

Vfix.py		truncate the scan line width of a video file to
		a multiple of 4 ('grey' images only)

Vedit.py	interactive video editing program

Vsend.py	unicast or multicast live video as UDP packets

Vreceive.py	receive transmissions from Vsend


These modules are used by the above programs:

VFile.py	classes that read and write CMIF video files

Viewer.py	two viewer classes used by Vedit

LiveVideoIn.py	live video input class, used by Vsend

LiveVideoOut.py	live video output class, used by Vsend and Vreceive


The following are C programs, either for efficiency or because they
need to link with a C library.  (These probably don't work any more
since the video file format has changed several times since they were
written.  Also, they can now be recoded in Python using the 'imageop'
and 'imgfile' modules.)

squash.c	make a movie smaller by averaging pixels
		usage: squash factor [bits] <moviefile >newmoviefile
		factor		x and y compression factor
		bits		#bits left per sample in result (default 8)

squash2.c	make a movie smaller by dropping pixels
		usage: squash2 factor <moviefile >newmoviefile
		factor		x and y compression factor

tomono.c	like squash2 but outputs a monochrome movie

v2i.c		convert the first frame of a movie file to SGI .rgb format
		link with -limage

i2v.c		convert an rgb file to "lrectwrite" format (this was
		used one time by the CMIF editor)


These programs are obsolete, but kept around for sentimental reasons.
Most either don't work any more because they don't use VFile and hence
haven't followed the frequent changes in the CMIF video file format;
or they are dependent upon hardware we don't have (SGI's previous
generation framegrabber).  Anyway, their functionality is present in
the suite of programs whose name begins with 'V' listed above.

cam.py		network real-time tv broadcast; see tv.py
		usage: cam [packfactor [host]]
		specifying 'all' for host broadcasts

camcorder.py	record video movies or make snapshots (in movie format)
		usage: camcorder [-c] [-a audiohost [-s]] [-p pf] [moviefile]
		-c		color (equivalent to -p 0)
		-a audiohost	syncaudio is running on audiohost
		-s		start syncaudio (on audiohost)
		-p packfactor	packfactor (default 2; 0 records color)
		moviefile	(default film.video)
		keyboard commands:
		s	stop grabbing (single step if already stopped)
		c	continuous grabbing
		r	start recording
		p	pause recording (record single frame if paused)
		ESC	quit

statit.py	various statistics operations on movie files

syncaudio.py	record audio synchronized with camcorder -a
		usage: syncaudio videohost soundfile
		soundfile format: 16 bits/sample, 16000 samples/sec, 1 channel
		(actually, you'd better set the sampling rate to 16000
		with the audio panel)

tv.py		receiver for transmissions from cam.py

vcopy.py	selectively write frames from one movie file to another
		usage: vcopy infile outfile
		commands: 'n' gets next frame; 'w' writes current frame

video.py	player for movies recorded by camcorder.py
		usage: video [-l] [-p pf] [-m mag] [-F]
					[moviefile [soundfile [skipbytes]]]
		-p pf		override packfactor (to zoom)
		-l		looping -- restart movie when done
		-m mag		magnification
		-F		run at max speed
		moviefile	default is film.video
		soundfile	default is none (no sound)
		skipbytes	byte offset in soundfile where sound starts

vinfo.py	print summary of movie file(s)
		usage: vinfo [-d] moviefile ...
		-d		print delta times (default: print abs times)

vpregs.py	definition of VP registers

vtime.py	virtual time module imported by syncaudio.py and camcorder.py