Documentation Files
===================

INSTALL - How to install this package

lavtools: Linux Audio and Video TOOLS for Motion JPEG and MPEG
==============================================================

Programs for MJPEG recording and playback and simple cut-and-paste
editting and MPEG compression of audio and video under Linux.

N.b. Only the "lav" programs have been written whooly from scratch.
The rest are from diverse open source originals, modified to work with
the lav tools edit lists and AVI and quicktime files.  Some
(especially the MPEG tools) have had also more major perfomance and
functionality enhancements.  

* The lavtools, xlav and utils directories

The latest and greatest versions of Rainer Johanni's original
lavtools.  Plus some extra goodies to link them to the MPEG
compression tools.

- "lavrec" is a program to record AVI and Quicktime MJPEG files with
   the Iomega BUZ etc including sound recording from the soundcard.

- "lavplay" plays back AVI and Quicktime MJPEG files or "xlav" produced
  edit files with the Iomega BUZ etc  (including sound).

- "xlav" in the directory xlav is a GUI for lavplay which permits
  fast forward/reverse, single frame stepping and simple non-destructive 
  editing.  Instead of writing new AVI or Quicktime files xlav creates an
  "edit list" file with pointers to the relevant bits of the original files.
  The lav tools and MPEG encoding tools can all work directly with these files
  as well as Quicktime and AVI files.  Since these files have simple plain-text
  format they can easily be manually editted or use for other tools.
	
- "lavtrans" (in directory utils) converts a mixture of AVI files,
  Quicktime files or Edit Lists into a single AVI or Quicktime file
  into single images or into WAV files.

- "lavaddwav" (in directory utils) lets you add another soundtrack
  (a WAV file) to an AVI/Quicktime file

- "lavvideo" is a small test application for the video overlay
   capabilities of your V4L hardware device.

- "lav2yuv" decodes AVI and Quicktime MJPEG and edit lists video and
  outputs it to standard out the simple raw YUV video format expected
  by the MPEG compressor "mpeg2enc" (see below).

- "lav2wav" decodes AVI and Quicktime MJPEG and edit lists video and
  outputs it to standard out the WAV format expected by the MPEG layer
  2 audio compressor "mp2enc" (see below.  If you output to a pipe it
  simply sticks a maxium length in the header.  Most programs processing
  streams will  work fine with this, ending cleanly when they reach the
  actual end.

- "lav2dfilter".  A median filter for noise reduction.  Useful when MPEG
  encoding TV material.

- "v4l-conf" is used in X to set up your video framebuffer address

- "yuv2lav", "ypipe" and "transist.flt" for (first decode an mjpeg 
  input file into raw yuv data (lav2yuv)) putting the data of more than 
  one yuv stream together (ypipe), making a transition between the two
  input streams (transist.flt) and for making an mjpeg file out of the 
  resulting yuv data (yuv2lav). Read README.transist for more info on
  how to use this.

* The scripts directory

Turning a video stream captured as MJPEG AVI's or Quicktime files
using a capture card into MPEG or transcoding a MPEG-2 file
involves several steps and multiple programs. This directory
contains several useful shell scripts that automagically
do the right thing for common encoding tasks. They're also
intended as examples of typical uses.


* The mpeg2enc directory

- "mpeg2enc" for encoding the output of lav2yuv or suitable
  output plugins in mpeg2dec to MPEG-1/2 video streams.

See the README for further details.
In the current beta release MPEG-2 is untested and variable
bit-rate probably won't work.  HOWEVER: speed and quality for
MPEG-1 are really rather good. Encoding 352x288 PAL at 18
fps on a 700Mhz Duron or 11ps on a 450Mhz P-III.

* The aenc directory - 

Contains the source files for "mp2enc" the MPEG-1 layer 2 audio
compressor. It is not particularly good as encoders go, but is
included for simplicity and completeness.  It also has the virtue
that for transcoding applications (e.g. AC3 to mp2) it can do
sampling rate conversions.  You need this to compress audio.

	
In general, however, you'd be better off with the faster and more
capable "toolame" encoder.  For transcoding applications the good old
stand-by "sox" will convert sampling rates very nicely (albeit it'll 
print a few warnings about incorrect headers if you use it in a
pipeline).

You may wish to try  using your favourite MPEG 1 layer 3 "MP3" 
encoder for better quality results.  However, make sure you 
use constant bit-rate  and turn of any extensions to the format.  
I have no idea how many players actually cope with layer 3.  Drop
andrew.stevens@nexgo.de an email if you get it to work!

* The mplex directory

Contains for the source files the "mplex" multiplexer.
This multiplexes (interleaves) MPEG-1/2 video and audio streams
into a combined "system stream" that can be played back smoothly.
This is *not* quite as trivial a task as it might seem (see the
original authors paper on the subject - copy is in the
documentation). Note that the program has been pretty heavily
modified since then.
MPEG-2 multiplexing is implemented but is currently untested.
DVD VOB multiplexing (AC3 audio in addition to MPEG) is not implemented.


See the README's of the various programs for further details
of authorship, usage, and implementation/compilation details.


Attention: lavplay is mainly intended to play back files created by
lavrec and should also be able to play back MJPEG AVI files created
from the Iomega BUZ under Win98 or the xawtv capture tool under linux.
The vast majority of AVI/Quicktime files will not be played by
lavplay!!!  (see http://dix.euro.ru for such codecs) The reason is
that lavplay only handles AVI that use an MJPG codec, all other files
don't use that codec and can therefore not be played back by the BUZ.

* Contact

You reach us by email.

If you have questions, remarks, problems or you just want to contact 
the developers, the main mailing list for the MJPEG-tools is:
  mjpeg-users@lists.sourceforge.net

Although little bits have been done by everyone the main work was
roughly as follows:

lav* : Rainer Johanni and Gernot Ziegler <gz@lysator.liu.se>
mpeg2enc mplex : Andrew.Stevens@nexgo.de
libmjpeg: Gernot Ziegler <gz@lysator.liu.se>
