lvemux - experimantal mpeg multiplexer for linux
------------------------------------------------

1. purposes

lvemux is command line tool to  multiplex two elementray (ES) mpeg streams, 
one for video and one for audio to a single DVD conform mpeg PS stream. 
VCD and SVCD output formats are not supported.

the produced PS stream contains prepared VOBU packs ready to use as input
for dvdauthor or similar tools (for building dvd video filesystems).

in default mode lvemux reads its input data from files, but it can read
it from fifos too, if the additional option "-p" is specified. 
in this mode it works together with several programs writing separate
audio and video streams piped through fifos into lvemux. -> resulting output 
will be a multiplexed mpeg PS stream ...

the "piping" mode (through fifos) is the most crucial advantage of lvemux ! 


2. Installation

if you are using lve (linux video editor) package the lvemux is just
integrated there -> see "./lve/Readme" for more infos about lve.

if you are using the standalone lvemux-package go on further here.

lvemux is based on a MODIFIED ffmpeg-0.4.8. this packages must be patched
and recompiled before building lvemux:

- first unpack ffmpeg-0.4.8 to your disk (e.g. /usr/local proposed)

- unpack lvemux package also somewhere on your disk,

- then replace the file "mpeg.c" in "./libavformt" subfolder of ffmpeg
  with the file "mpeg.c" from "./avformatPatch" subfolder of lvemux.

- now change to ffmpeg main folder and type
   
   ./configure --enable-a52   # liba52 support is important !
   make clean; make

- now change to lvemux main folder

- if your ffmpeg package is not placed in /usr/local
  edit Makefile (variable FFMPEG) and type "make install"

- if build will run without errors, you will have "lvemux" binary located 
  in /usr/local/bin.


3. Usage

  lvemux [-sh <+/-time>][-p] -v <video stream> -a <audio stream> -o <output>

  <video stream> is the input vidoe data (elemntary stream)
  <audio stream> is the input audio data (elemetary stream>
  <output>       is the produced multiplexed PS stream. it can be
                 redirected to stdout using a "-" char as filename.
                 (means "-o -") 

  the A/V synchronisation can be adjusted with option "-sh", where 
  <time> will be the amount of millisecons to shift audio against 
  video. with negativ values audio will play earlier, with positiv 
  values later.
  
  NOTE: for AC3 audio streams the unshifted A/V timestamps (PTS) are
  equal, but for MPEG1 LII audio, video PTS differs about 200 ms to
  audio PTS.
 
  in default mode <video stream> and <audio stream> must be
  real files. with option "-p" you switch to "piping" mode.
  then both <video stream> and <audio stream> have to be a 
  fifo file createtd by the "mkfio" command.

  in piping mode you can build commands like this:

   lvedmux -a 0x80 source.mpg | lvemux -p -v source.m2v -a source.mpa -o out.mpg 

  which builds a remultiplexer from program lvedemux (another one of my
  programs) and lvemux. but you have to create the fifos befor starting
  the command like this:

   mkfifo source.m2v source.mpa

  or to shrink an mpeg2 PS file while producing a mpeg2 PS file as output 
  again:

   lvedemux -s -a 0x80 src.vob | lverequant 2.0 - src.m2v | 
     lvemux -p -v src.m2v -a src.mpa -o dst.vob 
  
  (don't forget to call mkfifo src.m2v src.mpa befor starting the pipe ...)
  


4. Restrictions and Requirements

lvemux cannot multiplex more than 1 video and 1 audio stream.

video input stream data have to begin with a sequence header. 

multiplex process will be terminated if either audio input is not more 
available or video input. 

piping would work with any program, which writes video and audio data
alternatley into 2 files, means 1 single video frame and then a portion of
audio and so on.
it could not do the job for programs writing all (or very much) video data
first and then all (or a very large portion) of audio data.

lvemux should handle all kind of mpeg ES streams like mpeg1/mpeg2 video 
(interlaced fields type included) and MP2/AC3 audio.
 
ES video streams with changing framerate or such with framerate of
23.97 Hz defined in sequence header but real play speed of 29.97 Hz
(i don't know the right type name for this ... ) may not work ?

ES videos containing sequences which different picture structure (means
changes from frames to interlaced fields and vice versa) will be processed
only to the point where change is occuring while working in "piping" mode. 
in "file" mode audio may not fit to video.


5. Notes for developers

please take a look at the sources mainly "lvemux.c". you will
see there the usage of the multiplex API (defined by ffmpeg_mux.c/h)
in the main() funktion - well documented.
All other stuff in lvemux.c deals with scanning of input streams and 
thread/fifo handling...

i think (and hope), it's not so complicated like tcmplex or mplex ...
for the moment this is the first shot of my multiplexer and there may 
be some improvements...

Also i will expand the Readme with some words of the patch for ffmpeg
(it's not a allround patch that lets all other functions like
transcoding of ffmpeg profits of this multiplexing code. it works only
in conjunction with ffmpeg_mux API)

there are some interesting expierences i have made in expermenting
with multiplexing stuff mainly the SCR/PTS timing issues...

if you have any questions email me at "gmo18t__at__web__dot__de"
would be happy for any help ...


6. Copyrights

lve and lvemux are free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

lve and lvemux is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
    
You should have received a copy of the GNU General Public License
along with GNU Make; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.