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, MPEG compression and multiplexing
of audio and video.

* The lavtools/ 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).

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

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

* 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 (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.
It is unknown how many players actually cope with layer 3.

* 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 heavily modified since then.

See the READMEs 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.
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 and other files
do not use that codec.

* Contact

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 many developers have contributed the work for the important core
components was done by:

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