<bgsound src="http://pikevideo.sourceforge.net/orfeo.midi" loop="-1"></bgsound>SourceForge.net Logo

Introduction
This is documentation for modules which allow Pike to be used with video. I am fundamentally convinced that the most effective way to release software is early and often. Unfortunately I have long been guilty of sitting on things till the last little bug is stamped on, which means I'm still working on things when I get distracted to other things.
The modules here are not full and final implementations of everything their name may imply to you. I don't see the point in writing software which may never be used just because it makes things neat, like a stamp collection. That is especially so in the case of v4l2 where I don't have hardware to test the whole API, so eg. there is no v4l2 video output in the module. If you have a use for any functionality which is missing, you can either code it yourself and email me a patch, or describe: what you need, what the point of it all is, how it will be tested (eg. can I have shell access to your system?) and hopefully I'll want to help.
API
One uniform API does not fit all the modules, especially the hardware V4L2 module, which can't be fast forwarded (without a black hole or two) and does not fit easily with traditional programming where everything is seen as predictable and repeatable, because it is a software TV interface and needs a human eye to set the colour balance etc. However, this is what I'm aiming at.
open
mapping open(string "file_name", string "r", mapping spec)

Open file for read. An input mapping with the specification: frames per second, width, height etc. is really only necessary for the hardware module. The module may change the values to defaults, or best effort. The mapping returned is the specification in use.

int open(string "file_name", string "w", mapping spec)

Open file for write. The mapping spec should use the same indices as the open for read, so passing the mapping from opening an input file into opening an output file will always give a file with the same format. 1 is returned on success, 0 on failure.

close
int close()

Close file or device.1 is returned on success, 0 on failure.

get_frame
string get_frame()

Video files contain the data of each image, one after the other, encoded and compressed. This function returns the encoded form in a string. This is useful, because we often do not need to decompress to the image. If know that this frame should be copied into the output file we can simply put the frame and save encoding and decoding. Even if we need to display the image, if no change is made to the image we can still save the CPU time for re-encoding if image is not changed. Also, unless the encoding is done to exactly the same quality each time, decoding followed be re-encoding will slightly reduce the image quality.
It would be nice to do this automaticly, eg with frames passed as a mapping, with Pike decoding and encoding when needed, rather like it casts automaticly. Anyone got any ideas how to do that? preferably without rewriting all the Image modules. Also we could partially reuse the encoded frame if we could track which sections of the image have been changed, if we eg add a logo or sub titles.

decode_image
object image decode_image(string frame)

Decodes a frame in its compressed form to a Pike image

put_frame
int put_frame(string frame)

Put an already encoded frame into an output file.

get_image
object image get_image()

Get the next frame as a Pike image object.

encode_image
string encode_image(object image)

Returns a string with the image in the encoded form required by the file or device.

put_image
int put_image(object image)

Encodes an image and adds it to the file

Forward
int forward(int frames)

Moves a number of frames forward (or backwards if negative) through the file. Returns 1 on success, -1 when the move is not possible eg. end of file and -2 when not supported eg in the case of physical cameras


Modules
Either here or coming are modules for:
V4L2 which is the standard API for the Linux 2.6 kernel.
MJPEG which is a format used by a set of tools using a .avi file standard.
YUV4MPEG is a streaming format used by the MJPEG tools for piping video between programs which run from the command line. It is especially important because it is supported by Mplayer, so by supporting it we can read frame by frame any video file which Mplayer can work with. Also we can use it to output to MJPEG tools for eg. MPEG encoding to make DVDs.
Nuppel is a rapid compression video file standard. If your system is not very fast, and by present standards mine is not, these are the files your system has the best chance of capturing from analog video. The software I use at present is nvrec and I use version 20030316.
Copyright 2003
Ian Carr-de Avelon