                         bttvgrab 0.15.0 [1999-01-18] 
            by Joerg Walter (http://moes.pmnet.uni-oldenburg.de/bttvgrab/)
===============================================================================



Introduction:
-------------

bttvgrab is a program to capture video sequences under linux using a
bt848-based frame grabber card (e.g. Hauppauge Win/TV, Miro PCTV and many
more).

Its functionality includes MPEG-1/-2 video and audio creation, Web-TV
applications and low-diskspace operations.

It should work with other cards supported by the video4linux interface, but this
is untested. It works reliably with the bttv-0.5.8 driver, but earlier versions
of this driver are not supported.

bttvgrab was originally written by Adam Kopacz <Adam.K@idnet.de> up to version
0.6b. Further development was done by me.



Legal Informations:
-------------------

see COPYING for details



Installation:
-------------

see INSTALL for instructions

Get mpeg2encode from ftp://ftp.mpeg.org/pub/mpeg/mssg/mpeg2vidcodec_v12.tar.gz
if you plan to use automatic mpeg creation.



News:
-----

see WHATSNEW for more information



************
Please Help:
************

If you have a libc5-based system, please tell me your success (or failure).
The code is written so that it compiles withou warnings on my machine, but I
would like to know how it works on other machines.

To improve performance, I would like to write the essential code in assembler,
but I am not experienced enough to do this. My primary platform is the Intel
chip (I don't even know if bttvgrab runs on other platforms, maybe Alphas?). If 
someone likes to help, ask me.


Short guide to the included programs:
-------------------------------------

bttvgrab:    the main grab program, it does all the grabbing and sound
             recording it supports several output formats with several levels
             of size, quality, speed and compatibility

bttvconvert: the conversion program, it reads the bttv-only pmm file format or
             raw files and creates useful output from it, including mpeg videos 
             with sound

WWW/*:       several scripts and source files for Web-TV

mpegaudio/*: a modified version of the musicin program to create mpeg audio
             files; this creates layer 2 files as layer 3 in mpeg sequences is
             not widely supported; it is called automatically by bttvconvert

system_encode/*: a modified version of system_encode, a program to mix mpeg
             audio and video streams into one file; it is called automatically
             by bttvconvert
kgrab/*:     a KDE GUI to bttvgrab
libgrab/*:   the core engine for grabbing and converting



Description of command line options:
------------------------------------

Use bttvgrab -h and bttvconvert -h to get an actual list, this is likely to be
more up-to-date. The next sections cover some of the more interesting uses.

Try bttvgrab -d t to get a Tcl/Tk interface, here you can set all available
options, and it allows you to run bttvconvert afterwards as well. Even better,
use kgrab, it will be kept more up-to-date.



High-Quality video grabbing:
----------------------------

Disk Space: about 60GB per hour full-resolution video (w/o sound)
Disk Speed: as high as possible
Computing Performance: low (25 fps at all resolutions if disk is fast enough)
Summary: bttvgrab -o pmm-best [-Q] -w <width> -t -y [-l <length>]
	 bttvconvert -i pmm [-Q] -o <mpeg-1|mpeg-2> -l <length>

Capture with '-o pmm-best' (preferred) or '-o rawyuv'. Use '-Q' if you don't
want sound. Default size is 640x480, use '-w <width>' to change the width
(height is fixed at 4:3 aspect ratio).
You will almost always need to use '-y', or if you have root permissions,
run "update -s 1 -f 1" before grabbing. Use '-t' to record lost frames so they
ca be filled. Finally, tell the length of the sequence with '-l <n>', where n
is the number of frames to be recorded, or leave it out and end the sequence
by pressing 'q' while recording.
You may use '-g <name>' to create a grab log, it will be read by some future
version of bttvconvert for parameters.
If you experience speed problems, try leaving out -y (but run update), and
set up a grab partition, which you specify as output filename.

After that, use bttvconvert for conversion. Specify '-i pmm' for pmm input, or
'-i rawyuv' for raw input. In the latter case, you must specify '-w <width>' as 
well. Select the output format with '-o <format>', you may want to use 'mpeg-1'
or 'mpeg-2'. Set '-Q' if you didn't record sound. Use '-t' to fill out missing
frames. Tell the length of the sequence with '-l <n>'. If you created a
grablog, use '-g <name>' to evaluate it. In this case, no switches except for
'-o' are needed.
You can cut out a part of the sequence by setting '-x <n>' to skip this number
of frames at the beginning, and '-l <n>' to set the remaining length to be
converted. This is valid only for mpeg output.
If you are low on disk space, try '-r'. Then, bttvconvert will delete any files 
already processed. (Even a pmm file of which not all frames were used.)
DO NOT USE -r if reading from a partition!

If you are using a 30fps NTSC video signal, add -N NTSC to both command lines,
then the resulting mpeg will run at 30fps.


Web-TV:
-------

Disk Space: negligible
Disk Speed: unimportant
Computing Performance: unimportant, except for network resources
Summary: bttvgrab -o <jpg|gif> -f webcam:<dirname> -Q -w <width> -s <sleep time>

Capture with '-o jpg' or '-o gif', depending on what you want. Then, set a
refresh value with '-s <seconds>'. You should specify a directory name with
'-f webcam:<name>' (the 'webcam:' is important). Use '-Q' to disable sound.
Use '-w <width>' if you want another resolution. Finally, use the scripts
in WWW/ as a template to create your web page containing the image.
Maybe you want to use '-d q' to disable output.



Low space video recording:
--------------------------

Disk Space: down to 600MB per hour at low resolutions/low quality (w/o sound)
Disk Speed: should be fast
Computing Performance: very high (25 fps at max. 320*240 (24bit) or 550*412
                                 (8bit) on a 300MHz P-II)
Summary: bttvgrab -o pmm-good [-Q] -w <width> -t [-l <length>]
	 bttvconvert -i pmm [-Q] -o <mpeg-1|mpeg-2> -l <length> -r

Capture with '-o pmm-good' (24bit) or '-o pmm-fast' (8bit). Maybe experiment
with the other pmm formats as well. If you are grabbing 24bit, you can set the
quality with '-q <n>', n is 0-200, >= 100 selects slower but better DCT
algorithm. Use '-Q' if you don't want sound. Use '-w <width>' to change the
width, 384 is a very good value, down to 320 is quite acceptable. Use '-t' to
record lost frames so they ca be filled. Finally, tell the length ofthe
sequence with '-l <n>' or leave it out and end the sequence by pressing 'q'
while recording.
You may use '-g <name>' to create a grab log, it is read by bttvconvert for
parameters. (log evaluation is currently missing)

After that, use bttvconvert for conversion. Specify '-i pmm' for pmm
input. Select the output format with '-o <format>', you may want to use
'mpeg-1' or 'mpeg-2'. Set '-Q' if you didn't record sound. Use '-t' to fill out
missing frames. Tell the length of the sequence with '-l <n>'. If you created a 
grablog, use '-g <name>' to evaluate it. In this case, no switches except for
'-o' are needed.
You can cut out a part of the sequence by setting '-x <n>' to skip this number
of frames at the beginning, and '-l <n>' to set the remaining length to be
converted. This is valid only for mpeg output.
If you are low on disk space, try '-r'. Then, bttvconvert will delete any files 
already processed. (Even a pmm file of which not all frames were used.)

If you are using a 30fps NTSC video signal, add -N NTSC to both command lines,
then the resulting mpeg will run at 30fps.


Networking:
-----------

New since bttvgrab 0.15.0 is some networking code. bttvgrab (and bttvconvert
as well) can act as a grab server, bttvconvert can connect to it and get its
images from it. For the server, specify net:<serveraddr>:<port>/<client-addr>
as output filename, it will listen on the specified port for a client
connection from the specified client. reasonable defaults are provided (listen
on all adresses, port 31337, allow any client to connect), so you can leave out
any part of the specs. The client uses net:<server-addr>:<port> as source name,
the default port is 31337 as well, so you can leave it out.
Currently, the server isn't able to handle more than one connection and will
quit if the connection closes. The same is true for the client. This will
change in future releases.


X Windows:
----------

Also new since bttvgrab 0.15.0 is an X Display as output. Use -o X8, X16 or
X24, whichever matches your display depth (no 32 bit yet, sorry). To slow down
output when reading from a file, use -m <msecs> as sleep timer, 40 is a
reasonable value for a 25fps input stream.
This is valid for bttvconvert and bttvgrab, so you can just watch TV, or
view your pmm streams, or (using the networking code) do all this on the net.


Performance considerations:
---------------------------

There are several things you can do to optimize grabbing performance.
If you grab from a video tape, you can try to grab without sound and do a
seperate sound recording session. You must edit the sound file to get in sync
with the first frame you grabbed.
Disk writes are an imortant issue, too. If you grab short sequences you don't
have to worry about that, the disk cache should work properly. But if you plan
to do longer grab sessions, you will experience interrupts of 10 to 100 frames 
just because of cache flushing by the operating system. To minimize the impact
of it, run (as superuser) "update -f 1", this will tell the update daemon to
flush buffers each second so that less time is spent on writing. (Remember:
Using the driver patch, bttvgrab catches delays of up to 3 frames)
For large amounts of data (like, high resolutions and low compression) this
will not work. Then you must use the '-y' flag to prevent long delays, but this 
will almost immediately write your data to the hard disk, so a fast disk is a
must.
Finally, a thing that is true for every program: Don't run other cpu or hard
disk intensive applications.



Ideas for the future
--------------------

 - faster/smaller output formats (if anyone has a clue, please tell me)
 - better low-space behaviour (delete source frames as soon as possible)
 - real-time mpeg coding... just a joke ;-)
 - better performance with synchronous output
 - recording preview with KDE



The pmm format:
---------------

The pmm file format was developed to contain some non-standard image
formats optimized for speed or size (or both).

All values are stored as 32-bit integers with low-to-high order.

Offset    Meaning

          Header:

 0 -  3   "PMM" + major version, currently "PMM1"
 4 -  7   420000 + minor version, currently 420003
 8 - 11   image width
12 - 15   image height
16 - 19   subformat, one of:
		1	raw 8-bit data (pmm-fastest)
		2	lzo-compressed 8-bit data (pmm-fast)
		3	RTjpeg-compressed 8-bit greyscale data (pmm-grey)
		4	RTjpeg-compressed 24-bit data (pmm-good)
		5	raw yuv data (YUV422) (pmm-best)
		6	raw 8-bit greyscale data (pmm-bestgrey)

          Frames:

20 - 23   frame number of next image
24 - 27   byte length of next image
28 - 28+n image data
...

Raw 8-bit data uses the color palette of the bt848 chip. It is just a 9x5x5
GRB color cube starting at index 16.

Lzo-compressed data uses the minilzo library (included) to compress the raw
data.

RTjpeg compressed data uses the RTjpeg library (included) to compress the raw
data, including basic interframe coding - experiment with the quality values.

Raw yuv data is yuv 4:2:2 interleaved data.



Support:
--------

Email me with any questions or suggestions.

-- 
CU

   Joerg Walter 
   trouble@moes.pmnet.uni-oldenburg.de
