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>

AltiVec optimized library for MJPEG tools MPEG-1/2 Video Encoder
-----------------------------------------------------------------------------

Copyright (C) 2002  James Klicman <james@klicman.org>

Performance statistics for these optimizations are available at
http://klicman.org/altivec/.


Platform specific comments:

    Linux:

	AltiVec enabled compilers are now widely distributed.  However,
	the AltiVec support in the GNU GCC 3.1, 3.2 and even the latest
	3.3.1 release all have known bugs which cause invalid code or
	compile failures. It is likely that release GCC 3.3.2 will
	be a functional compiler for this AltiVec code. Until then,
	gcc 2.96.4 with the Motorola AltiVec patches works just fine
	and may even provide better AltiVec instruction scheduling.
	There are AltiVec enabled GCC compilers maintained by Kaoru
	Fukui at ftp://ppc.linux.or.jp/pub/users/fukui/.

        You will also need a recent binutils package. I've verified that
        binutils-2.12.90.0.7 works. It is also the recommended version
        for GCC 3.1. There may also be suitable binutils packages at
        Kaoru's FTP site.

    Mac OS X:

        If you have the developer tools, you're all set.


General comments:

    Additional performance can be gained by setting the -mcpu option. For
    GCC 2.95.* use -mcpu=750, for GCC 3.1 and higher try -mcpu=7400 or
    -mcpu=7450.

    This option can be added during configuration by setting the CFLAGS
    environment variable.  Since the encoder (mpeg2enc) and multiplexor
    (mplex) are now written in C++ the CXXFLAGS environment variable should
    also be set.  For example:

    env CFLAGS="-O2 -mcpu=750" CXXFLAGS="-O2 -mcpu=750" ./configure

    MJPEGtools v1.6.0 and onwards, when compiled with libdv, support DV video
    streams, stored as "Type 2 AVI" files.


Building and installation (if you want to compile from source):

    1. Download and install libdv from libdv.sourceforge.net.  (v0.9 and up
	are known to work.)

    2. Download and unpack the v1.6.0 source tarball, or get a clean CVS
        checkout of the development branch of mjpeg_play.

    3. configure && make && make install in mjpeg_play
        This should automatically detect libdv if it is installed.


Grabbing DV input:

    0. You should already have a DV camcorder and an IEEE-1394 board and
       everything set up for 1394 capture, otherwise have a look at:
           http://linux1394.sourceforge.net/
           http://www.schirmacher.de/arne/dvgrab/

       Two programs that I found very useful for resolving problems and
       controlling the camcorder through IEEE 1394 are:
            dvcont - http://www.spectsoft.com/idi/dvcont/
          gscanbus - http://www.ivistar.de/0500opensource.php3?lang=en

       If your camcorder allows you to record either 12bit or 16bit audio you
       should make sure to set it to 16bit recording since that is the sound
       format expected by the MJPEGtools.  Some camcorders have 12bit sound
       as the default factory setting, so check that *before* you start
       recording your videos.

    1. Start replay on the camcorder.

    2. Use dvgrab with the option "--format dv2" to capture the DV data in AVI
       'Type 2' format.  Only this format is supported by lav2yuv; capturing
       with the default '--format dv1' won't work.

    3. If you want to preview and edit (simple cut and paste editing) the raw
       DV files you can use kino from:
           http://www.schirmacher.de/arne/kino/
.
       Make sure to set dv2 format for saving in the preferences.


Using lav2yuv with DV:

    Simply follow all other documentation for "lav2yuv"; your Type 2 DV AVI
    file will be treated similarly to an MJPEG AVI file.

    For example:

          lav2yuv my-dv-file.avi | yuvplay

    * lav2yuv accepts DV AVI files directly or as parts of editlists.
    * Both PAL and NTSC streams are handled.
    * Sample aspect ratio is automatically detected.  Interlacing is always
      set to bottom-field-first (because DV is always bottom-field-first).
    * You can extract the sound from the DV files using either "lav2wav" or
      "lavtrans -f w".  Once extracted to a WAV file, you can encode it to
      MPEG Layer II audio with "mp2enc", which is capable of resampling the
      48kHz stream to 44.1kHz.  (Some hardware VCD and SVCD players will
      accept 48kHz audio, however this is non-standard.)




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

Additional Notes (of purely HISTORICAL value)
    1. The recent version of lav2yuv can also read raw YUV data from
       quicktime files that were written in planar YUV 4:2:0 format. This is
       one of the output file formats offered by bcast2000 for rendering
       scenes.
    2. This is a short description of the de-interlacing algorithm taken from
       the source file DI_TwoFrame.c from deinterlace.sourceforge.net.  This
       algorithm is a combination of simpler algorithms found in Windows
       programs like flaskMPEG or AVIsynth.

///////////////////////////////////////////////////////////////////////////////
// Deinterlace the latest field, attempting to weave wherever it won'tcause
// visible artifacts.
//
// The data from the most recently captured field is always copied to theoverlay
// verbatim.  For the data from the previous field, the following algorithm is
// applied to each pixel.
//
// We use the following notation for the top, middle, and bottom pixels
// of concern:
//
// Field 1 | Field 2 | Field 3 | Field 4 |
//         |   T0    |         |   T1    | scanline we copied in lastiteration
//   M0    |         |    M1   |         | intermediate scanline fromalternate field
//         |   B0    |         |   B1    | scanline we just copied
//
// We will weave M1 into the image if any of the following is true:
//   - M1 is similar to either B1 or T1.  This indicates that no weave
//     artifacts would be visible.  The SpatialTolerance setting controls
//     how far apart the luminances can be before pixels are considered
//     non-similar.
//   - T1 and B1 and M1 are old.  In that case any weave artifact that
//     appears isn't due to fast motion, since it was there in the previous
//     frame too.  By "old" I mean similar to their counterparts in the
//     previous frame; TemporalTolerance controls the maximum squared
//     luminance difference above which a pixel is considered "new".
//
///////////////////////////////////////////////////////////////////////////////

avilib: Reading and writing avi files
=====================================

Copyright (C) 1999 Rainer Johanni <Rainer@Johanni.de>

avilib is a open source library for dealing with AVI
files under Linux or other UNIX operating systems.

It provides a framework for extracting or adding raw
audio and single raw (=compressed) frames from/to AVI Files.

It does not deal with any compression issues which have to be
handled on a higher level by the user of avilib.

AVI files may have several video and audiotracks.

avilib writes only one video track and (optionally) one
audio track and also extracts only the first video and audio
track (but input files may contain more than one track, the others
just being ingored).

The interface to avilib is kept similar to the quicktime4linux interface
(by Adam Williams) with the following important differences:

- since only the first track of video and audio is considered,
  there is no track argument in any of the routines.

- audio is generally considered as a byte stream and therefore
  all size arguments used in reading/writing audio are in bytes
  and not in samples.

- as mentioned above, there are no routines dealing with compression issues.


Compiling:
==========

Since the library consists only of one c source file, I have not provided
a Makefile or similar, just compile with

cc -c <your favorite options> avilib.c


Portability:
============

AVI-Files use little endian numbers throughout the file, I have tried
to read/write these numbers in a way which doesn't depent on endianness.
This library should therefore also be useable on big endian machines.
This feature is not so heavily tested, however.


Usage:
======

Basics, opening, closing
------------------------

Include "avilib.h" in your source and declare a pointer:

   avi_t *avifile;

Open the AVI file with:

   avifile = AVI_open_input_file("xxx.avi",1);

or

   avifile = AVI_open_output_file("xxx.avi");

You may either only read from the input file (leaving it unchanged)
or create a completly new AVI file. There is no editing or append
mode available.

Both routines will either return a pointer to avi_t or a zero pointer
in the case of an error.

For closing the file, use:

   int  AVI_close(avi_t *AVI);

Files you have written MUST be closed (the header is written at close time),
else they will not be readable by any other software.

Files opened for reading should be closed to free the file descriptor
and some data (unless your program is finishing anyway).


Error handling:
---------------

Most routines (besides open/close) will return 0 or a useful number if successfull
and a -1 in the case of an error. If an error occured, the external variable
AVI_errno is set. See avilib.h for the meaning of the error codes in AVI_errno.

There is also a routine (which acts like strerror) to retrieve a string
description of the last error (which can then be logged or printed):

AVI_strerror(char *str)


Reading from an AVI file:
-------------------------

After opening the file, you can obtain the parameters of the AVI
with the following routines:

long AVI_video_frames(avi_t *AVI);
   number of video frames in the file

int  AVI_video_width(avi_t *AVI);
int  AVI_video_height(avi_t *AVI);
   width and height of the video in pixels

double AVI_frame_rate(avi_t *AVI);
   frame rate in frames per second, notice that this is a double value!

char* AVI_video_compressor(avi_t *AVI);
   string describing the compressor

int  AVI_audio_channels(avi_t *AVI);
   number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present

int  AVI_audio_bits(avi_t *AVI);
   audio bits, usually 8 or 16

int  AVI_audio_format(avi_t *AVI);
   audio format, most common is 1 for raw PCM, look into avilib.h for others

long AVI_audio_rate(avi_t *AVI);
   audio rate in samples/second

long AVI_audio_bytes(avi_t *AVI);
   total number of audio bytes in the file


In order to read the video frame by frame, use
(frame numbers are starting from 0 !!!!!)

long AVI_frame_size(avi_t *AVI, long frame);
   to get the size of frame with number "frame"

long AVI_read_frame(avi_t *AVI, char *vidbuf);
   to read the next  frame (frame posittion is advanced by 1 after the read)

int  AVI_seek_start(avi_t *AVI);
int  AVI_set_video_position(avi_t *AVI, long frame);
   to position in the AVI file
   (for reading the frames out of order)


Read audio with

int  AVI_set_audio_position(avi_t *AVI, long byte);
   to position to an arbitrary byte position within the audio stream

long AVI_read_audio(avi_t *AVI, char *audbuf, long bytes);
   to actually read "bytes" number of audio bytes.
   the audio position is advanced by "bytes", so there is no
   need to reposition before every call when reading in order.


Avoiding lengthy index searches:
--------------------------------

When opening the AVI file, avilib looks if the file has an index attached
and if this is not the case, it creates one by reading through the whole file.

If you want to read through the file only once, creation of an index is
not necessary in that case. You may use AVI_open_input_file with the second
argument set to 0 and then use AVI_read_data for readin through the file.

Look to the source for the arguments of AVI_read_data.


Writing to an AVI file:
-----------------------

After you have opened the file, use the following routines to set
the properties of the AVI file:

void AVI_set_video(avi_t *AVI, int width, int height, double fps, char *compressor);
void AVI_set_audio(avi_t *AVI, int channels, long rate, int bits, int format);

with:

width, height   width and height of the video in pixels

fps             frame rate in frames per second, notice that this is a double value!

compressor      string describing the compressor

channels        number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present

rate            audio rate in samples/second

bits            audio bits, usually 8 or 16, 0 if no audio present

format          audio format, most common is 1 for raw PCM, look into avilib.h for others


to write video frames or audio, use:

int  AVI_write_frame(avi_t *AVI, char *data, long bytes);
int  AVI_write_audio(avi_t *AVI, char *data, long bytes);

there is also a feature to duplicate the index entry of the last
frame without writing the data again to the file, this should
used with care since I don't know if all AVI players can handle
the resulting file (xanim can do it!):

int  AVI_dup_frame(avi_t *AVI);

AVI files have a 2 GB limit (as has the Linux ext2 file system),
avilib will return an error if you try to add more data to the file
(and it cares that the file still can be correctly closed).
If you want to check yourself how far you are away from that limit
(for example to synchronize the amount of audio and video data) use:

long AVI_bytes_remain(avi_t *AVI);

You should be able to just "make"

there are some hacks so I didn't have to include anything from the mjpeg utils
directory.  I hope to get it into the build tree sometime (soon...).

seconds are NTSC seconds (30 frames)
Key Bindings:  (loosely based on vi key bindings)
   (            set Selection Start
   Home         "
   )            set Selection End
   End          "
   0            go to beginning
   h,<- + CTRL  "
   9            go to end
   l,-> + CTRL  "
   l,->         forward single frame
   l,-> + SHIFT forward 10 frames
   l,-> + ALT   forward 50 frames
   w            forward 1/2 second (15 frames)
   W            forward 1 second (30 frames)
   h,<-         reverse single frame
   h,<- + SHIFT reverse 10 frames
   h,<- + ALT   reverse 50 frames
   1            forward 5 seconds
   2            forward 10 seconds
   3            forward 15 seconds
   4            forward 20 seconds
   5            forward 25 seconds
   6            forward 30 seconds
   b            reverse 1/2 second (15 frames)
   B            reverse 1 second (30 frames)
   !            reverse 5 seconds
   @            reverse 10 seconds
   #            reverse 15 seconds
   $            forward 20 seconds
   %            forward 25 seconds
   ^            forward 30 seconds
   x,del        cut selection
   y            yank (copy) selection
   p,ins        paste selection
   s,S          stop, pause
   f            play (forward)
   F            fast forward
   r            reverse
   R            fast reverse

This README describes the lavpipe tools: how to use them,
and how they work (partially).
The current implementation still is not tested very well, so be
warned (and please report any errors you encounter).

At the moment, there are only two filters for lavpipe,
transist.flt and matteblend.flt, which means that you can
use it only to make simple blending transistions between two
movies or to blend one video over another using a predefined
matte (yuv image or lav movie). But it is very easy to code
new filters or extend existing ones. Read on.

Contents:
1. What are the tools?
2. What can we do with it?
3. What else can we do with it?
4. That's all?! How can we make them do more?
_____________________________________________________________________________
                                                                             \
1. What are the tools?                                                       /
____________________________________________________________________________/

The tools that are involved so far are:
 - lav2yuv, which decompresses the given input files (or any portions
            of them) and gives us raw yuv frame streams that can be
            piped through the several tools.
 - lavpipe, which reads out a "LAV Pipe List" (e.g. *.pli) file, a
            "recipe" which tells it how to combine several input
            movies using several yuv stream filters.
 - transist.flt and matteblend.flt, all the filters that already exist.
 - yuv2lav or mpeg2enc, which compress the resulting yuv stream
                        into an mjpeg or mpeg file.

_____________________________________________________________________________
                                                                             \
2. So hat can we do with it?                                                 /
____________________________________________________________________________/

Example one: Make a transistion from one movie to another one.

Let's assume that we have got two 352x288 PAL files:
intro.avi (1040 frames) and epilogue.qt (3920 frames). Now we want
to make a transistion between them that lasts for two seconds
(2 sec = 50 frames, as they are PAL movies).
We also have to take care that both share the same dimensions - if
they are of different sizes, we can use lavscale once it is finished.

Our task now is to write a "recipe" for lavpipe and thus tell it how
to do the work. If we store our work as trans.pli, the final call will
simply be: "lavpipe trans.pli | yuv2lav -o result.avi" (lavpipe
writes a yuv stream to stdout as lav2yuv does).

The first line of trans.pli must be "LAV Pipe List".

The second line contains one single number, the number of input
streams that we will use. (In our case: "2")

Now for each of the two input streams a line containing the
command that produces the stream is added. First for intro.avi:
"lav2yuv -o $o -f $n -n 1 intro.avi"
The -o $o and -f $n parameters are necessary as lavpipe somehow
has to inform lav2yuv which frames it should output. $o will
be replaced by the offset and $n will be replaced by the number
of frames that lavpipe wants lav2yuv to output. The -n 1
parameter is of course optional, and any other parameters to
lav2yuv could be added. The second line for epilogue.qt might
look like this: "lav2yuv -o $o -f $n epilogue.qt"

Now follow all the sequences of the Pipe List, each of which
consists of a listing of the input streams used and a command
line to the filter program.

The first sequence will simply reproduce all but the last 50
frames of intro.avi (that are 1040 - 50 = 990 frames). Its
first line only contains "990", the number of frames. The
second line is "1", the number of streams used.
The next line contains the index of the stream to use and the
offset (how many frames to skip in the beginning).
In our case both index and offset are 0, so the line would be:
"0 0"
Now we would add the command line of the filter program, but
as we don't want to invoke any filter here, this line only
contains "-", which causes lavpipe to simply output the contents
of the stream.

The second sequence is the actual transistion. So the first
line is "50" (two seconds), the second one "2" (we use both streams).
The following line will be "0 990" (intro.avi will be continued
at frame 990) and then "1 0" follows (epilogue.qt starts with
frame 0).
The next line is the filter command, in our case
"transist.flt -s $o -n $n -o 0 -O 255 -d 50"
The -s $o -n $n parameters equal to the -o $o -f $n parameters
of lav2yuv, -o 0 means that at the beginning of the transistion,
only intro.avi is visible (opacity of epilogue.qt = 0).
As you would have expected, -O 255 means that at the end of
the transistion, only epilogue.qt is visible (opacity of
epilogue.qt = 255 = 100%) - the opacity will be linearly
interpolated inbetween. And finally -d 50 is the duration
of the transistion in frames and should be equal to the
first line (duration in frames) of the sequence in most cases.

The last sequence continues with only epilogue.qt (the last
3870 frames), thus the first line is "3870". The second line
is "1" (only one stream), then "1 50" follows (epilogue.qt,
beginning with frame 50). The filter command line is "-" again.

Finally, our Pipe List file should look like this:

--------------------< trans.pli >--------------------------
LAV Pipe List
2
lav2yuv -o $o -f $n -n 1 intro.avi
lav2yuv -o $o -f $n epilogue.qt
990
1
0 0
-
50
2
0 990
1 0
transist.flt -s $o -n $n -o 0 -O 255 -d 25
3870
1
1 50
-
--------------------< end of file >------------------------

Remember the call? "lavpipe trans.pli | yuv2lav -o result.avi"
should now produce a nice avi file with a nice transistion.

_____________________________________________________________________________
                                                                             \
3. And what else can we do with it?                                          /
____________________________________________________________________________/

Example two: Blend one movie over another one, using a third one's luminance
             channel as a matte (alpha channel) for the second one.

matteblend.flt has no parameters until now, as its output is independent of
the actual position in the stream (only depends on the input frames it is fed).

If you read the first example and have understood the pipe list format, it
will be easy to write a pipe list for this task. As there still is no
bluescreen.flt filter, and it is very time consuming to build an animated
matte channel for a given input movie by hand, I will only describe how to
blend a static picture (a title or static logo) over a movie.

For this you need your input.avi, a picture with an alpha channel. Use for
example the GIMP to save the image as plain yuv (pic.yuv) and save its
alpha channel as a grayscale plain yuv (matte.yuv - its chrominance channels
will be ignored). Of course the must be of the right size.
Now create this simple shell script that will output an infinite yuv stream
that only contains the given plain yuv picture:

--------------------< foreveryuv >-------------------------
#!/bin/sh
echo "YUV4MPEG 352 288 3"
while true
do
       echo "FRAME"
       cat $1
done
--------------------< end of file >------------------------

And write the pipe list:

--------------------< title.pli >--------------------------
LAV Pipe List
3
lav2yuv -o $o -f $n input.avi
foreveryuv pic.yuv
foreveryuv matte.yuv
75
3
0 0
1 0
2 0
1000000
1
0 75
matteblend.flt
--------------------< end of file >------------------------

As long as your input.avi is shorter than 1000076 frames,
"lavpipe title.pli | yuv2lav -o result.avi" will output
the whole movie with the given picture blended over it
for the first three seconds.

_____________________________________________________________________________
                                                                             \
4. That's all?! How can we make them do more?                                /
____________________________________________________________________________/

The solution is of course to code new filter programs. And of course this
is very easy. I want to annote here, that the whole system is not very
fool proof at the moment. So if you feed matteblend.flt the wrong number
of input streams via lavpipe, you will get funny results, if you get
any results at all (without any hint from the programs). Perhaps this
could be improved by adding additional (optional) parameters to the
YUV4MPEG header line.

A filter program consists only of 4 parts:

1. Read input parameters (especially -o and -n, if the output is not only
   dependent on the input frames but also on some variable parameters that
   change over time) - optional.

2. Read in and write out the YUV headers, could look like this:

   int fd_in = 0, fd_out = 1; /* stdin, stdout */
   y4m_stream_info_t istream, ostream;
   int res, width, height, frame_rate_code;

   y4m_init_stream_info(&istream);
   y4m_init_frame_info(&iframe);

   if (y4m_read_stream_header (fd_in, &istream) != Y4M_OK)
      exit (1);

   y4m_init_stream_info(&ostream);
   y4m_copy_stream_info(&ostream,&istream);
   y4m_write_stream_header (fd_out, width, heigth, frame_rate_code);

3. Allocate the YUV buffer(s) - one for each input stream and perhaps one
   for the output or an arbitrary number of temporary buffers (no bloated
   code, please ;-) )

   char *yuv_buffer[3]; /* this is one yuv buffer */
   yuv_buffer[0] = (char *) malloc(y4m_si_get_plane_length(&istream, 0)); /* Y' */
   yuv_buffer[1] = (char *) malloc(y4m_si_get_plane_length(&istream, 1)); /* Cr */
   yuv_buffer[2] = (char *) malloc(y4m_si_get_plane_length(&istream, 2)); /* Cb */

4. The loop - while (number of frames processed) < (-n parameter)

4.1. Read the input frames, one of those for each input stream (e.g. yuv_buffer[123])

   while (y4m_read_frame (fd_in, &istream, &iframe, yuv_buffer) == Y4M_OK)
         {
4.2. Process the input buffers in any way you want.

5. Write out the result:

         y4m_write_frame(fd_out, &ostream, &iframe, yuv_buffer);
         }

6. Clean up:
     y4m_fini_frame(&iframe);
     y4m_fini_stream_info(&istream);
     y4m_fini_stream_info(&ostream);

That's all. You should in any case have a look at the existing filters,
transist.flt.c and matteblend.flt.c.

- pHilipp Zabel <pzabel@gmx.de>

This file describes how to make a transistion from one video file
to another using the current sample implementations.
Especially ypipe will be replaced (hopefully) soon by a more
capable program.

The programs involved in this process are:

 - lav2yuv, which decompresses the given input files (or any portions
            of them) and gives us raw yuv frame streams that can be
            piped through the several tools.
 - ypipe, which starts two instances of lav2yuv and combines the two
          input streams into one, in which every even frame is from
          the first and every odd frame from the second input.
 - transist.flt, which takes the frame-interlaced stream from
                 ypipe and writes out the final transistion.
 - yuv2lav or mpeg2enc, which compress the resulting yuv stream
                        into an mjpeg or mpeg file.

Let's assume simple this scenery: We have two input videos, intro.avi
and epilogue.qt and want make intro.avi transist into epilogue.qt
with a duration of one second (that is 25 frames for PAL or 30 frames
for NTSC).

intro.avi and epiloque.qt have to be of the same format regarding
frame rate and image resolution, at the moment.
In this example they are both 352x288 PAL files. intro.avi contains
250 frames and epilogue.qt is 1000 frames long.

Therefor our output file will contain:
 - the first 225 frames of intro.avi
 - a 25 frame transistion containing the last 25 frames of intro.avi
   and the first 25 frames of epilogue.qt
 - the last 975 frames of epilogue.qt

We could get the last 25 frames of intro.avi by calling:
  lav2yuv -o 225 -f 25 intro.avi
(-o 225, the offset, tells lav2yuv to begin with frame # 225
 and -f 25 makes it output 25 frames from there on)
Another possibility is:
  lav2yuv -o -25 intro.avi
(negative offsets are counted from the end)

And the first 25 frames of epilogue.qt:
  lav2yuv -f 25 epilogue.qt
(-o defaults to an offset of zero)

But we need to combine the two streams with ypipe. So the call would be:
  ypipe "lav2yuv -o 255 -f 25 intro.avi" "lav2yuv -f 25 epilogue.qt"
The output of this is a raw yuv stream that can be fed into
transist.flt.

transist.flt needs to be informed about the duration of the transistion
and the opacity of the second stream at the beginning and at the end
of the transistion:
 -o num   opacity of second input at the beginning [0-255]
 -O num   opacity of second input at the end [0-255]
 -d num   duration of transistion in frames
An opacity of 0 means that the second stream is fully transparent
(only stream one visible), at 255 stream two is fully opaque.
In our case the correct call (transistion from stream 1 to stream 2)
would be:
  transist.flt -o 0 -O 255 -d 25
The -s and -n parameters equal to the -o and -f parameters of lav2yuv
and are only needed if anybody wants to render only a portion of the
transistion for whatever reason. Please note that this only affects
the weighting calculations - none of the input is really skipped, so
that if you pass the skip parameter (-s 30, for example), you also
need to skip the first 30 frames in lav2yuv (-o 30) in order to get
the expected result. If you didn't understand this, send an email to
the authors or simply ignore -s and -n.
The whole procedure will be automated later, anyway.

Now we want to compress the yuv stream with yuv2lav.
  yuv2lav -f a -q 80 -o transistion.avi
Reads the yuv stream from stdin and outputs an avi file (-f a)
with compressed jpeg frames of quality 80.

Now we have the whole command for creating a transistion:

ypipe "lav2yuv -o 255 -f 25 intro.avi" "lav2yuv -f 25 epilogue.qt" | \
transist.flt -o 0 -O 255 -d 25 | yuv2lav -f a -q 80 -o transistion.avi

(This is one line.) The resulting video can be written as a LAV Edit List,
a plain text file containing the following lines:

LAV Edit List
PAL
3
intro.avi
transistion.avi
epilogue.qt
0 0 224
1 0 24
2 25 999

This file can be fed into xlav or lavplay, or you
can pipe it into mpeg2enc with lav2yuv or combine
the whole stuff into one single mjpeg file with
lavtrans or lav2yuv|yuv2lav.