Vstream0.3.1 Video+Audio streamer for v4l.
==========================================
(C) Justin Schoeman 1998
(Initially based on capture.c by Koji OKAMURA)

DISCLAIMER
==========
As usual, this software is distributed without any warranty. By using this
software, you acknowledge that I (Justin Schoeman) take no responsibility
for what happens!

ABOUT
=====
Vstream is a collection of utilities for capturing reasonably high quality
video from a v4l device (specifically configured for bttv).  A simultaneous
audio track is also captured.

The first utility - stream - captures an audio and (multiple) video
stream(s).  For highest performance, the video stream should be written to a 
raw partition(s).

The next utility - str2ppm - converts the captured video stream to ppm
files.  When the stream is being converted, it is restored to the ideal 
framerate, so dropped pictures will result in a slightly jerky picture, but
no loss of synchronisation.  (A patch against mpeg2encode/decode by the MPEG 
Software Simulation Group (MSSG) is also included to allow direct MPEG 
encoding from this stream).  A clip table utility is included to allow
simple editing of video streams.

The final utility - audioconv - synchronises the audio stream (44.1kHz 16
bit mono) to the captured video stream.

audioclip is also included to clip the audio to match the video.

New utilities: xsv, xfv, ppm2str (see below).

NEW FEATURES
============
V0.4:
1) Added xsv - a viewer for displaying captured streams real-time under X
windows.
2) Added xfv - a viewer for frame-by frame viewi of edited streams under X
windows (for testing/aligning edits).
3) Added ppm2str for converting ppm files to video streams for inclusion in
edited videos.
4) Added more video editing functions: overlay, fade-to-black, fade-from-black
and fade-to-stream.

V0.3:
1) Streaming to multiple video files in parallel to allow high bandwidth
capture across multiple storage devices.
2) Unlimited recording length (well, up to 256 files, each with a max of
1G).
3) Basic editing functions. currently only supports "block" mixing from any
number of streams.
4) Start end end times can be specified on the command line for automated
recording.

INSTALLATION
============
There is no installation script as such, but I'm sure you can figure out
where to put the binaries!

1) Edit Makefile - there are only 3 settings that are really useful:
CFLAGS - the current settings are only good for EGCS on a K6-2, so put your
own optimisations here.
DEFS - two useful DEFS are: NTSC (This should change the timings to work
properly for NTSC streams - Please give me some test reports on this - I
don't have any NTSC sources).
   FIX32 (Some X displays report depth=24 when it is actually 32... Don't
ask me why, but this DEF will tell "xsv" and "xfv" to use 32bpp even if X
reports 24bpp mode).

2) Type: make

3)To patch mpeg2encode go to {mpeg2 root directory}/src/mpeg2enc and type:
patch -p1 < {Vstream root directory}/mpeg2enc.patch
make

**NOTE** The patch adds a file type 3 which reads the stream format from
Vstream.

**Another Disclaimer** I am not sure what the license is on mpeg2encode. If
I have infringed on the license with this patch please inform me immediatly
so I may remove it.

This patch is against mpeg2vidcodec_v12.
(you can get mpeg2encode form www.mpeg.org under MSSG)

USE
===

stream [-half or -halfx Xxdim Xydim] [-start time] [-end time] <source> <xdim> <ydim>
 <audio stream> <video stream1> [<video stream2> ...]
 -half: only capture 1 of every 2 frames - reduces required bandwidth with
	little visible loss in quality (in my opinion).
 -halfx Xxdim Xydim: capture half the frames to disk and half to an X window
                     of width Xxdim and height Xydim (see BUGS).
 -start: the next argument, in the form hh:mm:ss:dd:mm:yyyy, is the time at
         which recording will start.  Only the first three arguments are
         required.  The remaining arguments will be taken from the current
         date/time.
 -end: time to stop recording. Same format as "-start".
 xdim: width
 ydim: height
 audio stream: filename to store audio.
 video stream: filename(s) (preferable an empty, raw partition(s)) to store 
               video (max 256 files).
NOTE: It is best to run "stream" in a clean directory, as it creates a
number of files in the current directory:
 str2ppm.par - A parameter file for mpeg2encode for encoding directly from
               the video stream.  Also used by "str2ppm".
 video:cliptab - Basic clipping table to produce an "uneditted" output.
NOTE2: Use your favourite TV program to set the channel, mode, etc. before
       executing "stream".
NOTE3: If you do not use -end, press CTRL-C to end capture.

--------------------------

str2ppm [-str <output stream 1> [-str <...>]] <parameter file>
 -str: write to output stream(s) <output stream x> instead of ppm files.
 parameter file: name of parameter file (normally "str2ppm.par").
NOTE: creates video:<frame number>.ppm files in the current directory!
The filename can be changed by changing the root-name in "str2ppm.par". The
file <root-name>:cliptab must exist.
NOTE 2: when outputting to another stream, make sure you have enough disk
space - no space checking is done! Also, no default cliptabs/parameter files
are created, so you'll have to make your own.

--------------------------

audioconv <audio stream> <first video stream>
 audio stream: name of the audio stream file
 video stream: name of the first video stream file (audio is synchronised to
               this file.
NOTE: creates <audio stream>.out in the current directory.

--------------------------

audioclip <cliptab>
 cliptab: clipping table used for editting audio/video (normally
          "video:cliptab").
NOTE: Output is to stdout, so make sure you redirect it somewhere! (Probably
to a pipeable mpeg encoder.

--------------------------

ppm2str <filename> <maxframe>
 <filename>: input filename in fprintf format eg: ovl:%03d (NOTE: no .ppm at
the end, this gets appended automatically, the : must be ther - this denotes
root filename).
 <maxframe>: the maximum frame number.
NOTE: from the above example: ovl:000.ppm and ovl:<maxframe>.ppm must exist,
others are not necessary, the highest existing frame number is fetched for
editing. eg: if only frame 0 and frame <maxframe> exist, then frame 0 to
frame <maxframe-1> will be frame 0, anf frame <maxframe> will be
frame<maxframe>...
OK - Thats mot that clear, but I'm sure you can figure it out ;->

--------------------------

xsv [-double] [-raw] <audio stream> <video stream 1> [<video stream 2> ...]
 -double: display images twice normal size.
 -raw: The audio stream is "raw" ie. processed by "audioconv"/"audioclip" to
       remove frame marks.
 Remaining parameters the same as "stream".
NOTE: Sometimes this bombs out the first time - just run it again - it
(almost) always runs the second time! (see BUGS below)

--------------------------

xfv [-double] <parameter file>
 -double: display images twice normal size.
 <parameter file>: parameter file.

FILE FORMATS
============

"video:cliptab"
<group 0>
[group 1]
[  ...  ]
[group n]
*
<command 0>
[   ...   ]
[command n]

IE: all lines before "*" are "groups" and all lines after "*" are commands. 
At least one group, and one command must be defined.  A maximum of 256
groups and 1024 commands are allowed (can be changed in getframe.c). Groups
are referenced acording to the order they appear in the cliptab, starting at
0 and incrementing by 1.

A group is as follows:
<audio stream> <video stream 1> [ ... <video stream n>]
NOTE: This is the same as the end of the "stream" command line used to
capture the stream.

A command is as follows (currently only block command is supported):
B <group> <start> <length>
B = block
<group> = group to insert block from.
<start> = frame number (zero referenced) of the start of the block within
stream "group".
<length> = number of frames to insert from "group"

f <group> <start> <length>
f = fade-from-black
same parameters as "B"

F <group> <start> <length>
F = fade-to-black
same parameters as "B"

O <group1> <start1> <length> <group2> <start2>
Overlay <group2> starting at <start2> onto <group1> atarting at <start1>
An overlay is transparent wherever r=g=b=0 (absolute black) If you really
need black, use r=g=b=1 - this will be quantitised to black in the final
image anyway. The overlay streams are usually made by "ppm2str"

X <group1> <start1> <length> <group2> <start2>
Mix from <group1> starting at <start1> to <group2> starting at <start2>
(linear fade from <group1> to <group2>).

"str2ppm.par"
This is the standard parameter file used by mpeg2encode (except that file
type 3 has been added).  The only thing you will want to change here is the
number of frames, which is in line 8.
NBNBNB: Make sure the number of frames in "str2ppm.par" agress with the
total number of frames in "cliptab" (ie. the sum of all the block lengths in
the command section).

EXAMPLE (with mpeg2encode patch)
================================

*** WARNING *** Don't try this example unless you are willing to lose
EVERYTHING on /dev/hdb /dev/hdc /dev/hdd! It is a lot safer to use
conventional files, but the lack of filesystem overhead dramatically
improves capture bandwidth.

> stream -half 160 120 a /dev/hdb /dev/hdc /dev/hdd
(CTRL-C when done).
Captures 160x120 video frames from TV to audio a and video group "/dev/hdb
/dev/hdc /dev/hdd".
audioconv -swap a /dev/hdb
Synchronises audio a to video v. Also swaps byteorder.
> encode -m m -b 32 a.out a.mpg
Encode audio to mpeg layer 2.
> mpeg2encode str2ppm.par v.mpg
Produce v.mpg from video data.
> mplex v.mpg a.mpg out.mpg
Produce a mpeg system stream from the mpeg video and audio data.

Without the mpeg2encode patch, add:
> str2ppm v 24
before mpeg2encode to produce ppm files. WARNING the ppm files require an
aditional 1.5 times the space of the video stream file!

EDITTING
========

When you have captured all the streams, and synchronised their audio with
audio conv, create new cliptab and parameter files for the desired output. 
Run mpeg2encode/str2ppm to produce editted video and audioclip to produce
editted audio.

Frame sets can be previewed by converting each stream to mpeg, and viewing
with mpeg_play, using the "-start" and "-end" options.

Example video:cliptab:
v1/a /dev/hdb /dev/hdc /dev/hdd
v2/a v2/v1 v2/v2 v2/v3 
*
B 0 0 25
B 0 475 25
B 1 0 25
B 0 0 500
B 1 0 500

NB: for this cliptab, the associated str2ppm.par file must have 1075 in line
8!

This cliptab would produce a video as follows:
group 0 is v1/a /dev/hdb /dev/hdc /dev/hd
group 1 is v2/a v2/v1 v2/v2 v2/v3
Output:
Frames:		Contents:
0..24		group 0 frames 0..24
25..49		group 0 frames 475..499
50..74		group 1 frames 0..24
75..574		group 0 frames 0..499
575..1074	group 1 frames 0..499

NB: Make sure the frames you request from a group exist!  The maximum frame
for each group can be determined from line 8 of the str2ppm file produced
when the group was captured. Frames are zero based, so the maximum frame is
"number of frames"-1!

BUGS
====
Lots... Very little error checking - make sure you give it the right
arguments, or I cannot guarantee any results!

xsv sometimes bombs out every second time! I don't know why - if someone can
figure it out, please tell me!

8 bit mode doesn't work properly on any of the X programs.  Does anybody use
8 bit mode?

stream with the -halfx option can sometimes capture corrupted frames. If
this happens, use smaller Xwindows and/or a faster computer.

FINAL NOTES
===========
This program works for the limited applications for which I use it (sending
video email, or recording TV programs). It does this reasonably well (some
of the time).  This is not part of my work, and I do not have time to
maintain it, so if there are any bugs you would like fixed/additions made,
you will probably have to do them yourself.

If you like the program, go ahead and use it.  If you don't like it, send
all flames to /dev/null.

TODO (what I will likely do)
============================
 - I won't be adding very much more to this package. Maybe some extra
editing commands, or bug fixes, but it now does everything that I want from
it, and I don't really have the time to carry on with it.

Justin Schoeman
31 August 1998
justin@suntiger.ee.up.ac.za
http://www.ee.up.ac.za/~justin/bttv