
*  mplex - MPEG1/SYSTEMS multiplexer
*
*  Copyright (C) 1994 1995 Christoph Moar 
*  Additional portions and modifications 
*  Copyright (C) 2000 Andrew Stevens
*  Research at Siemens ZFE ST SN 11 / T SN 6
*
*  TECHNICAL UNIVERSITY OF MUNICH, GERMANY
*
*  moar@informatik.tu-muenchen.de
*       (Christoph Moar)
*  as@comlab.ox.ac.uk
		(Andrew Stevens)
*  This program is 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 of the License, or
*  (at your option) any later version.
*
*  This program 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 in the file COPYING for more details.
*
*  You should have received a copy of the GNU General Public License
*  along with this program; if not, write to the Free Software
*  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



MODIFICATIONS TO ORIGINAL

July 2000 Andrew Stevens
	 Trivial modifications to support catenated audio stremas and
	  non-intractive use.
August 2000 Andrew Stevens
	Modifed to support multiplexing of variable bit-rate
	video streams. Seems to work well.
August 2000 Andrew Stevens
	Removed use of temporary files for storing stream data.
	Increased performance through the use of a more efficient bitstream 
	library.
	Eliminated arithmetic overflow errors for large streams.
	Initial support for multiplexing variable bit-rate streams.

Novermber 2000 Andrew Stevens
	Clean up code to suit modern compilers with 64-bit int support.
	Cleaned up packet size calculations to make the code more flexible.
	Initial MPEG-2 support
	Support for splitting output streams (not yet completely implemented)
	Support for multiplexing for VCD.

MANUAL PAGE DRAFT

mplex [params] <input file1> [<input file2>] <output filename pattern>

Mplex multiplexes a MPEG video stream and an MPEG layer 1, 2 or
3 audio stream into a combined, synchronised, time-stamped, systems
(MPEG-1) / program (MPEG-2) stream.

To understand what it is doing and the available flags it is necessary
to understand the structure of MPEG systems streams.  Such a stream
comprises as sequence of *packs* each of which contains 1 or more
*packets* of data.  The header for a pack contains a time-stamp
telling the decoder what time the first byte after the timestamp
should have arrived.  The headers of the packets in the packs tell the
decoder what kind of data the packet holds (audio, video, padding,
"private" etc), how long the packet is, and at what time the contents
should be decoded.

A complicating factor is that for MPEG systems streams intended for
block-structured storage media (DVD's, VCD's etc) the pack's always
start at the beginning of a sector and the packets always end at the
end of a sector.  mplex currently *always* a sectorised stream
suitable for block-structured media.  Its needed to burn proper
VCD/DVD's and its no serious penalty otherwise. Another complicating
factor is the possible presence of system headers carrying information
about the systems stream that may precede the pack header in a pack.

In theory a compliant decoder ought to be able to handle almost any
"sensible" stream.  I.e. packs that are not absurdly long (< 30 odd
packets) so that it gets reasonable clock updates, contain a system
header at the beginning, and perhaps interspersed here and there,
specifiy a stream bit-rate fast enough to allow the data for audio and
video arrive in time for decoding and so on.  Decoders also have
limits on how much data they can buffer which restrict the video
streams they can handle.

In practice this actually only holds true for software decoders and
the better sort of hardware decoder.  Dedicated VCD and DVD player hardware,
unsurprisingly, tends to be able to handle stuff that conforms closely
to the (very restrictive) VCD and DVD spec.'s.

VCD's, in particular, are very bizarre with some quite arbitrary
restrictions and out-and-out inconsistencys.  To save hassle mplex has
built-in options to set exactly the right settings for multiplexing
VCD and (in the future) SVCD and DVD streams.  There are also "auto"
settings that produce a reasonable stream intended for software players.

Finally, some comments are in order about padding and stream
bit-rates.  In the normal "constant bit-rate" MPEG model of decoding
it is assumed that the decoder is like a TV set: it gets a constant
stream of video information sent to it down a one-way pipe.  If it
doesn't actually *need* any data at a particular point in time then
special padding data that is discarded on arrival is inserted into the
stream so that needed data doesn't come too soon and overflow its
buffers.

The alternative is "variable bit-rate".  This reflects a situation
more like that on a PC with a software decoder.  The assumption is
that data is sent read/sent exacttly fast enough to keep up with
whatever needs to be sent.  If no data is needed for a while *nothing*
is sent.  In practice mplex generates such streams by figuring out the
peak bit-rate needed for the video/audio, and then generating a
constant bit-rate stream for that rate but simply neglecting to
including padding.  Obviously, variable bit-rate is the sensible way
to go because allows bits to be allocated exactly as they're needed
(action sequences get lots, "talking heads" very few) and averaged out
over a stream.  One of the main deficiencies of the VCD and DVD
standards is that assume constant bit-rate.  The standards were
foolishly set on the assumption that players wouldn't have fast enough
drives / large enough buffers to make the variable bit-rate approach
viable.  Anyone who saw the evolution of the CD drives and the price
of RAM in the last 20 years can see why this was a damn-fool move.


FLAGS
-q      Quiet mode for unattended batch usage

-n      Noisy (verbose) mode for debugging streams

-m      Mpeg version (default: 1) [1..2]

-V      Multiplex variable bit-rate (experimental - see above).

-b num  Specify decoder video buffer size in kB. (default: 46) [ 20...1000]

-r num  Specify data rate of output stream in kbit/sec (default 0=Compute from source streams

-l num  Multiplex only up to video frame num (default 0=multiplex all)

-v num  Specify a video timestamp offset in mSec
-a num  Specify an audio timestamp offset in mSec

		These are useful for correcting streams where audio and video
		were recorded out of step.  

-s num  Specify sector size in bytes (default: 2324) [256..16384]

-p num  Number of packets per pack (default: 20) [1..100]
		
		This number is terribly critical.  The pack overhead is only around
		1% even if every pack has only one packet.

-h      System header in every pack rather than just in the first.

		One header is enough for most applications.
-S size Maximum size of output file(s) in M bytes (default: 680)\n" );
		
		For archiving it is often necessary to split a long MPEG stream
		into chunks that fit inside file-system size limits (e.g. 2G bytes)
		or removable storage media (CD's etc).  This flag allows to specifying
		the maximum. The names of the files produced are generated from the 
		the output filename pattern by replacing the first %d in it with
		1,2,3,... etc.

		Eventually there will be an option for cause MPEG to generate
		a "proper" video stream in each file - prepending system headers
		and the video streams sequence header at the start of each.

		Currently all mplex does it ensure the break happens cleanly at
		"Group of picture" boundaries.  That is, the files, when
		catenated are precisely the sequence that would be generated
		if just a single very long file were produced.
		
-f fmt  Set pre-defined multiplex format.

	0 = Auto MPEG1, 1 = VCD, 2 = Auto MPEG2, 3 = SVCD, 4 = DVD

	Only 0 .. 2 currently implemented!  
	
	Warning: to produce correct VCD streams you *must* use -f 1 as
	a bunch of exotic VCD-only internal stream generating options have
	to be set-up that don't have their own seperated flags.


EXAMPLES
	
	mplex -f 1 tvprog.m1v tvprog.mp2 tvprog.mpg

	Create a VCD stream suitable for burning to disk with vcdimager or
	mkvcdfs.

	mplex -b 90 -r 1800 -S 780 movie.m1v movie.mp2 movie.%d.mpg

	Create a MPEG-1 stream suitable for software players or hardware MPEG
	cards from a high data-rate stream needed a larger video data
	buffer where the guess multiplexing	data-rate turns out to be incorrect.
	The stream is chunk into pieces of the right size for archiving as a
	XA mode 2 stream on an 80 minute CD blank.

DIAGNOSTICS
	If mplex notices that the specified buffer size and data-rate are too
	low to allow a particular bit of video or audio data to arrive in
	time for decoding it prints a warning "time-out" message.

BUGS
	MPEG-2 multiplexing is untested and, without provision for
	multiplexing AC-3 audio as a private1 stream not terribly useful.

	In quiet mode there should be a suitable exit error message and status
	if any time-outs occurred. 

	The current two-pass scanning method should be used *only* for
	variable bit-rate.

	The current formula used to guesstimate the appropriate multiplexing
	data-rate tends to be over-generous.  

	mplex should be able to guesstimate buffer-size / data-rate needed for 
	streams where peak data-rate significantly exceeds the specified
	and/or average video data-rate.
	

SEE ALSO
	mkvcdfs(1), vcdimager(1), mpeg2enc(1), toolame(1), mp2enc(1)



