---------------------------------------------------------------------
                              VCR README
---------------------------------------------------------------------

Table of Contents
------------------------

1.  Introduction
2.  Prerequisites
3.  Installation
4.  Usage
5.  Examples (TODO)
6.  Configuration
7.  Availability
8.  Bugs
9.  Frequently Asked Questions
10. Developer Information
11. Links
12. Copyright


1.  Introduction
------------------------

VCR is a program which enables you to record a program using a video
grabber card that's supported by the video4linux drivers.  It does not
require a graphical environment, and you can use popupular windows
codecs (like DivX, Indeo Video 5, etc) because VCR is built around the
avifile library.  Now, you can finally record your favourite program
from a remote place, because Murphy's law dictates that you remember to
record it when you are as far away from your home as possible.


2.  Prerequisites
------------------------

    - a video4linux supported capture (tv) card.
        Popular supported models are the Hauppauge WinTV and Miro PCTV boards,
        using the bt848/878 chipset.
    - a fast CPU.
        A celeron-466 CPU copes well enough to record divx low-motion
        @ 25fps, just occasional frame drops). 
        If you want to compress audio to mp3 as well, you will probably
        need a P3-600 or better.
    - Diskspace.
        This depends on the codec chosed, and its attributes. Using default
        settings (DivX codec, BitRate 900, mono 44Khz 16 bits audio), expect
        500MB/hour. With mp3 compressed audio (mono, 64kps), expect 230MB/hour.
    - avifile library [0.53.5 or better] (http://divx.euro.ru/)
        If you want to use vcr with avifile-0.6, please download the avifile
        snapshot that accompanies the latest release of vcr from the
        vcr download page: http://www.stack.nl/~brama/vcr/?page=download
        Configure without --enable-release if vcr ends in a segmentation
        fault.
        This snapshot contains unmodified avifile source. Snapshots from other 
        dates might not work.
    - An OSS sound device.
        I've had several reports of ALSA users where sound recording doesn't
        work well, even with OSS emulation. If you want to help out here,
        please do. Most users have an OSS driver that's shipped with the
        linux kernel though.
    - (OPTIONAL) xawtv
        you can do without, but if you want to use tuner presets,
        you can copy them from the .xawtv config file.
    - (OPTIONAL) aumix
        From vcr-1.07 on, you can initialize your sound recording device with
        the config-file directive 'init-sound'. If you omit this keyword,
        you must set the correct recording device and volume with a program
        like aumix.


3.  Installation
------------------------

    If you want to use avifile-0.6, first read section 2 to know where to
    get a working snapshot. After installing it, configure vcr with
    --enable-avifile-0_6.

    Compilation should be straightforward:
        ./configure
        make
        make install

    Make sure 'avifile-config' is in your path before attempting to run
    the configure script.

    If you want to report a bug, please reconfigure vcr like this:

      ./configure --with-debug
      make clean
      make
      make install

    Next, run vcr with an extra command-line argument --debug <filename>.
    Attach the produced debug file, your config file, and all output from
    stderr (vcr -your_arguments 2>/tmp/vcr-errors.txt) in your bug report.


4.  Usage
------------------------

Read the VCR manpage (man vcr or man -lvcr.1) for information
about commandline parameters, config file, etc.  Read the next
section for some examples.


5.  Examples
------------------------

Case example #1:
    I would like to encode 10 minutes from my tvcard into divx format.
    How do I do this?

Short answer to example #1:
    vcr -c 'divx ;-) low-motion' -a 'BitRate=900' -t 10m test.avi

Long answer to example #1:
    vcr --codec "divx ;-) low-motion" -a 'BitRate=900' \
        --source "Television" --quality 100 --rectime 10m \
        test.avi

Case example #2:
    Same as in #1, only this time compress audio to mp3 format (64 kbps):

Short answer to example #2:
    vcr -c 'divx ;-) low-motion' -a 'BitRate=900' -b 64 -t 10m test.avi

Long answer to example #2:
    vcr --codec "divx ;-) low-motion" -a 'BitRate=900' \
        --source "Television" --quality 100 --audiobitrate 64 \
        --rectime 10m \
        test.avi

6.  Configuration
------------------------

For an example configuration file, see or copy doc/sample.vcrrc to
"~/.vcrrc" and modify to tastes.  The man page has information on all
available settings possible in the file.

For information on how to "preprogram" VCR more easily, read the files
in the doc/ subdir.


7.  Availability
------------------------

VCR can be downloaded from http://www.stack.nl/~brama/vcr/, or from
http://vcr.sourceforge.net/


8.  Bugs
------------------------

Read the "TODO" file for known bugs or features on the drawing
board.  If you find any bugs, please reread the 'Installation' chapter
and mail the produced debug files to the author.


9. Frequently Asked Questions
------------------------------------

Read the "FAQ" file for a list of frequently asked questions. If you have
internet connectivity, you might want to read the FAQ on the web for
better readability: 

    http://www.stack.nl/~brama/vcr/?page=faq


10. Developer Information
------------------------

All GPL coders who wrote GPL'd code so I could write this program. 
Especially the authors of avifile (used capture/v4l code from qtvidcap),
xawtv (used their code to parse their config file), and <shameless plug>
mp3blaster</shameless plug> (reused some code from it for this program, but I
guess that doesn't count since its author happens to be me :)


11. Links
------------------------

    aumix        http://jpj.net/~trevor/aumix.html
    avifile      http://divx.euro.ru/  
    mp3blaster   http://www.stack.nl/~brama/mp3blaster.html
    xawtv        http://www.strusel007.de/linux/xawtv/


12. Copyright
------------------------

VCR is released under the GPL license. Read the file COPYING that came with
the VCR source for more information.
