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