November 7, 2001

MP4LIVE 
=======

MP4LIVE is a Linux audio/video capture utility that can capture and encode 
audio and video in real-time. The results can be written to either an .mp4
file, transmitted onto the network via either unicast or multicast, or both 
simultaneously! The audio is encoded with MP3, and the video with MPEG-4 
Simple Profile which is OpenDivx compatible.

Please use the MPEG4IP SourceForge site to report problems, suggest 
enhancements, ask questions, etc. The URL is 
http://www.sourceforge.net/projects/mpeg4ip

Hardware Requirements
=====================
Pentium III class machine of at least 500 MHz 

Note systems vary quite a bit in their video capture abilities. For instance,
I have a name brand 750 MHz PIII that drops frames when pushed to CIF sizes
at greater than 15 fps, but I have a no-name clone with a 800 MHz PIII that 
can encode CIF @ 24 fps no problem.

RAM is not typically an issue. I develop on machines with 128 MB, but I believe much smaller configurations would work fine. The real issue is CPU speed.

A sound card with an OSS compatible driver and capture ability.

A video device with a video4linux (v4l) compatible driver and memory mapped 
capture ability.

Known to work are:
	Video capture cards based on the Brooktree 8x8 chip
	with an analog A/V source - VCR, DVD, Camcorder, Settop box, Tivo, etc.
		Typically a video capture card will support composite video inputs.
		Some will also have S-Video input.
		Others will also have a TV Tuner input.

	Logitech Quickcam Express Webcam

Software Requirements
=====================
Linux with a 2.4 or later kernel
	(My development was done on RedHat 7.1)

Drivers for sound and video devices

	bttv video capture driver
		Included with RedHat 7.1, I don't know about other Linux distributions
	qce webcam driver


WARNINGS!
=========

Please see the MPEG4IP README regarding legal issues, and the list of 
open source packages that are redistributed with this code.

This is a LINUX program! Do not even think about trying to get this to 
run on Windows! Even moving it to other UNIX systems would require some 
re-programming since the sound and video capture interfaces are Linux 
specific.

By far the easiest route is to use a Linux distribution that already has a
2.4 kernel, the bttv driver, and the associated i2c module built into it.
I've hacked kernels before, and I'm not sure I could sucessfully follow the 
instructions in the bttv driver as to how to configure a kernel so that it 
would work. Caveat emptor!

I've had many headaches with sound cards under Linux. Before you start using 
mp4live, please make sure you're able to playback and record with your sound 
card!

You should definitely increase the number of capture buffers for the bttv 
driver. This reduces the chance of dropping video frames due to transient
delays in the system. By default bttv uses 2 buffers. You can increase this 
by editting /etc/modules.conf and adding the line 
"add options bttv gbuffers=32"
at the end of the file. The value 32 is my recommendation but you can 
experiment with other values if you are so inclined.

Note there is currently no support for DV/mini-DV camcorders via FireWire. 
You can of course still use these via their composite or S-Video outputs.


Building and Installing
=======================

See the MPEG4IP README for general notes about the build environment. 

Assuming you've already done a build at the top level of mpeg4ip, and
you're on a Linux system then mp4live should be built and waiting for you
in this directory. If you've done a top level 'make install', the mp4live
will be installed into '/usr/local/bin'. Of course, you can also issue 
'make' and 'make install' from this directory as well.


Using mp4live
=============

Typically, there is no need for command line options to mp4live. You can
just type 'mp4live' and you'll be up and running.

If you change an mp4live configuration setting, then that change will be 
saved in your home directory in ~/.mp4live_rc. This file is read when 
mp4live is started, and the configuration settings adjusted accordingly.

The default settings for mp4live are to record 1 minute of audio and video
to an mp4 file, ./capture.mp4  The first time you use the program, it's
a good idea to just hit the Start button, and see what happens. If all
goes well, 1 minute later you have a playable/streamable mp4 file. If you
don't get this, then it's time to review this README, and it that doesn't
help, then fire off a message on the MPEG4IP SourceForge discussion group.

Assuming things are working you can now use the Settings buttons to adjust
things like the video size and frame rate, the audio sampling rate, the 
encoded bitrates, etc. The UI is hopefully self-explanatory. If not, let us
know what's confusing and we'll look at fixing that. (I'm a big believer that
if you need to read a document to use a UI, then the UI is broken and should
be fixed. Of course, as I've re-learned many times, what is obvious and natural
to me, isn't always to other people.)

If you're capturing video that uses "widescreen" or "letterbox" format, 
it's a big win to change the "Aspect Ratio" in the Video Settings. This 
will cause the video to be automatically cropped so you don't waste precious 
CPU time encoding the empty black bars at the top and bottom of the screen. 

Network Transmission
====================

To use mp4live to transmit live audio/video to the network, follow these
directions: 

Select 'Enabled' in the Transmission section of the main window.

By default, mp4live will multicast the media to IP address 224.1.2.3

If you wish to change this, select the 'Settings...' button in the
Transmission section of the main window. A dialog will appear that allows
selection of the destination IP address (either unicast or multicast),
the UDP port numbers used, the TTL used if multicasting, and the name of
the .sdp file to generate (more about that in a minute). When you're done
making changes, select 'OK'.

When you press mp4live's 'Start' button, media transmission to the network 
will begin. Also a small text file with extension .sdp will be created that 
describes the media transmission for the player. The player needs the .sdp 
file to be able to tune into the media streams. (Note the .sdp file can also
be generated from the Transmission Settings dialog)

The most convenient way to distribute the .sdp file is to have mp4live write
it to a directory that is accessible from a web server (httpd) that is running
on the same machine as mp4live. This allows the client to be started with
the HTTP URL of the sdp file, and it will download the .sdp file via http
and then use the information in the .sdp file to tune into the network
transmission. E.g. 'gmp4player http://myserver/myprogram.sdp'

You can of course distribute the .sdp file in a number of other ways, say
ftp, or email. You would then start the player with the local file name 
of the sdp file, e.g. 'gmp4player myprogram.sdp'


Use with Darwin Streaming Server
================================

If you would like to use mp4live in conjunction with the Darwin Streaming
Server, that is very easy to do. You can have mp4live both record and 
transmit live media streams. When you record the .mp4 files, just ensure 
that they are written to a directory that is accessible via the Darwin 
Streaming Server. Once the recording is complete, it will be available 
for on-demand playback.


Advanced Usage
==============

There are currently three command line options to mp4live:
--file <config-file>
--automatic
--headless

--file <config-file> allows specification of the mp4live configuration file
to something other than ~/.mp4live_rc. Perhaps you have a several frequently
used configurations. You can save the configuration settings to different
files, and then use this option to choose among them.

--automatic causes mp4live to act as if the Start button was pressed
immediately upon startup. The program will do whatever the current 
configuration instructs it to do. This option can be used in conjunction
with the 'cron' utlity to do scheduled recording and/or transmission.

--headless causes mp4live to behave in the --automatic mode AND not display
any user interface.


Known Issues
============

Using a system with a PCI instead of an AGP video display card can cause 
video "tearing" with CIF or larger size images. I.e. the PCI bus quickly
gets swamped moving raw video from the video capture card to the CPU, and 
then from the CPU to the video display card. Having the AGP bus for the
CPU to video display card transfer alleviates this problem. If someone is
interested one could experiment with the video overlay capabilities of the
Bt8x8 to bypass this problem, but it would require some rework of our code
with respect to the video preview function.

It took me awhile to figure this out so perhaps I can save some of you some
time. If you use the Hauppage WinTV Go card you need to connect the mini-jack
on the card to the line-in input on your sound card in order to get the
audio signal from the TV tuner.

There is no exploitation of the Pentium IV MMX/SSE instructions, yet!


Unknowns
========

I've only used mp4live with two video capture cards the Viewcast Osprey 100
and the Hauppage WinTV Go. There are many other Bt8x8 based capture cards 
listed in the bttv driver documentation. Odds are you're using one of these ;-)
If you have problems with mp4live, my first suggestion is that you download 
the latest version of the xawtv package, and try it with your capture card. 
If it works and mp4live doesn't then I'd be glad to hear from you. If xawtv 
doesn't work with your capture card, then I can't help you. Something is 
wrong with your capture card/system/bttv driver/kernel combination. I don't
have the capability or inclination to debug that for you! 

We haven't tried this code on an SMP machine. The code is multi-threaded so
an interesting experiment would be to assign the video encoding thread to 
one CPU and let the other threads run on another CPU. If you have lots of 
low-powered CPUs then one could modify the code to run the video encoder 
on multiple CPUs and round-robin assign raw frames to be encoded. 


Links
=====
MPEG4IP			http://www.mpeg4ip.net/
bttv driver		http://bytesex.org/bttv/
qce driver		http://www.sourceforge.net/projects/qce-ga
xawtv			http://bytesex.org/xawtv/
ffmpeg			http://www.sourceforge.net/projects/ffmpeg
OpenDivX		http://www.projectmayo.com/
LAME			http://www.sourceforge.net/projects/lame


Dave Mackie
Cisco Systems, Inc.
