** For latest status/FAQ on modules, please read STATUS **

NewVideoRecorder (nvrec - yes, I know it is lame, but it was late at night)
---------------------------------------------------------------------------

(If you just want to use nvrec, skip to the  usage section at the end ;-) )
(If you get errors about "libquicktime" not found, get quicktime4linux, and
run the install script as directed at the end of this file.)
(To build ffmpeg support, download and build ffmpeg, then make a symlink to
the built ffmpeg tree in ../ffmpeg .)
(NOTE: for ffmpegrec, timing only works correctly for AVI files.)

Introduction
============

This is an attempt at a high performance audio/video capture engine.  It
currently only supports v4l1, v4l2 and OSS drivers.

Technical
=========

This engine makes use of deep buffers (2 seconds+) for audio and video.  The 
video is buffered in the driver to avoid too many costly userspace copies. 
The audio is buffered in a userspace ring buffer.  This is expensive, but 
neccessary, as OSS drivers are often limited to very short buffers.

All buffers are accurately timestamped as they are received: video buffers by
the kernel, and audio buffers by gettimeofday() (offset by the current depth 
of the kernel buffer).  At the start, audio or video is dropped until both
are in sync, and from then on, only audio and video timestamped for the same
period is processed.

Since there will be clock drift between the audio capture and video capture
cards, the audio stream is dynamically warped so that exactly the right
amount of audio is placed in the output file for each video frame written to
the file (NOTE: At the moment the warping is done by a simple line algorithm
- could do a lot better here).  A simple P-I controller adjusts the warping
factor to keep sync.

The code tries to keep the internal buffers between 10% (to make sure we
never run out of data) and 40% (to make sure we don;t have uncontrolled
dropping) full.  When the buffer is less than 10% full, it simply sleeps 1
frame period.  When the buffer is more than 40% full, it gradually drops
more frames per sencond, until a stable point is reached.

The code is designed to be very modular, so there should be no problem
adding an alsa core.

There are currently four output cores: qtfile_core, which produces RTjpeg,
YUV2 or RAW encoded quicktime files; divxfile_core, which produces DivX 
encoded avi files; nuvfile_core, which produces NuppelVideo0.4 files; and
rtefile_core, which produces mpeg-1 program streams.

USING nvrec:
============

First set up your capture device using xawtv (or whatever your favourite TV
app is), then fire up qtrec (to record quicktime movies, or divxrec to
record DivX encoded AVIs.

Using the defaults, qtrec should work on just about any MMX capable
computer, and DivX on anything 600MHz+.  The only required command line
parameter is the output filename, the rest are listed below...

BEWARE: the v4l bttv driver will give a default of 2 buffers.  You can
change this with the "gbuffers=32" modprobe option.  If you do this, use
the "-N 32" command line option, or the core will fall back to using copy
buffers.

Programs:
	qtrec: Records quicktime movies
	divxrec: Records DivX encoded avi files
	nuvrec: Records NupelVideo files
	rterec: Records MPEG-1 program streams
	divx4rec: Records DivX encoded avi files (using divx4linux codec)
	ffmpegrec: Record in multiple formats using ffmpeg backend

Usage:
 [qt|divx|nuv|rte|divx4|ffmpeg]rec < no options >
(gives a complete list of the most current options)
 
Note, for -S settings, if value is less than 0, then use synchronous writes.
If it is equal to 0, do nothing, if it is greater than 0 then sync every "x"
seconds (floating pont number).

Tools
=====

Tools (a number of tools are located in the "tools" subdirectory:
	qt2divx:	convert QT files to DivX encoded AVIs
	timer:		a simple timer for starting/stopping recoding at
			specific times.

 *qtplay has been removed - instead I have added a RTjpeg plugin for xmovie. 
Install xmovie, and type "make install" in tools to install the plugin. Note
that keyframe support doesn't work, so the output might look ugly
occasionally... bcast works just fine though.  If you really want to view it
with xmovie, record with "-k 0" to stop interframe coding.  If you still get
errors, about unknown codec, try:
	export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib/

install.sh is a script that can be run from the quicktime4linux source tree
to install the shared library and header files.

Streaming
=========

divx4rec now has the following additions:

1) -half option: only capture every second frame.
2) -wav option: record audio in raw PCM format.
3) Output filename starting with <udp|tcp>://<ip>:<port> multicasts the data to
<ip>:<port>.
4) Output filename of "-" streams data to stdout.

The streaming standard is proprietry, but very simple, see divx4/mcs.c for
details.

Various tools and utilities are supplied in tools/stream:

mcplay:
An SDL based player (REQUIRES SDL 1.2+). Usage:
	mcplay - (play from stdin), or
	mcplay udp://<ip>:<port> (play form multicast group)
	mcplay tcp://<ip>:<port> (play form tcp connection)

NB: For tcp ip, use 0.0.0.0 to send to all local interfaces!

mccatch:
A utility to receive a multicats stream, and output it on stdout.

mcthrow:
A utility to receive a stream on stdin, or a tcp socket, and multicast it.

mccatch takes udp://<ip>:<port> as an argumet, and can be used for streaming 
the data over a pipe to a remote network.

mcthrow take the optional argument <port>:<ip> for a source tcp connection,
followed by udp://<port>:<ip> for the destination multicast group.  If the
first argument is not used, the stream is cast from stdin.

EG:
High quality stream.
	divx4rec -o udp://227.0.0.35:12345
and
	mcplay udp://227.0.0.35:12345

Low quality stream
	divx4rec -o udp://227.0.0.35:12345 -half -db 256 -mb 64
and
	mcplay udp://227.0.0.35:12345

Remote casting:
	divx4rec -o tcp://0.0.0.0:54321			(record to TCP stream)
and (on the same machine)
	mcthrow 127.0.0.1:54321 udp://227.0.0.35:12345	(cast stream locally)
and (on remote network)
	mcthrow w.x.y.z:54321 udp://227.0.0.35:12345
	(cast stream on remote net, w.x.y.z is the IP of the recording box)
	mcplay udp://227.0.0.35:12345

You can use the multicast group of your choice.

Config files
============

nvrec programs parse (in this sequence):
1) built in default options
2) /etc/nvrec.conf
3) ${HOME}/.nvrec.conf
4) command line
5) any "-C <config file>" config files, in the position they occur within
    the command line.

The config file simply consists of the desired command line options.  See
etc/nvrec.conf for an example.
