*************** FFMPEG soft VCR documentation *****************

1) Video input
--------------

* ffmpeg can use a video4linux compatible video source : 

  ffmpeg /tmp/out.mpg 

  Note that you must activate the right video source and channel
  before launching ffmpeg. You can use any TV viewer such as xawtv by
  Gerd Knorr which I find very good.

* ffmpeg can use YUV files as input : 

  ffmpeg /tmp/out.mpg /tmp/test

If will use the files: 
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V, 
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...

The Y files use twice the resolution of the U and V files. They are
raw files, without header. They can be generated by all decent video
decoders. You must specify the size of the image with the '-s' option.

* ffmpeg can use YUV PGM files generated by the excellent MPlayer
  (http://thot.banki.hu/esp-team/MPlayer.html). They contain the Y
  component in their upper part, and the U and V component in their
  lower part.

2) Invocation
-------------

* There are some importants options to know:

-L           print the LICENSE
-s size      set frame size                       [160x128]
-f format    set encoding format                  [guessed]
-r fps       set frame rate                       [25]
-b bitrate   set the total bitrate in kbit/s      [200]
-t time      set recording time in seconds        [10.0]
-ar freq     set the audio sampling freq          [44100]
-ab bitrate  set the audio bitrate in kbit/s      [64]
-ac channels set the number of audio channels     [1]
-an          disable audio recording              [no]
-vn          disable video recording              [no]
-hq          high quality mode (non real time)    [no]

The frame size can also be: cif, qcif, sqcif and 4cif.
The encoding format can be mp2 ac3 mpeg1video h263 mpeg1 ra rm asf avi mpjpeg swf.

Advanced options are:

-d device    set video4linux device name          [/dev/video]
-ad device   set audio device name                [/dev/dsp]
-g gop_size  set the group of picture size        [12]
-i           use only intra frames                [no]
-c comment   set the comment string

Comment strings are only used for Real Video(tm) encoding. Tags are
used in the comment string. A typical comment string is:

"+title=Test Video +author=FFMpeg +copyright=Free +comment=Generated by FFMpeg 1.0"

The output file can be "-" to output to a pipe. This is only possible
with mpeg1 and h263 formats. 


3) Tips
-------

- For streaming at very low bit rate application, use a low frame rate
  and a small gop size. This is especially true for real video where
  the Linux player does not seem to be very fast, so it can miss
  frames. An example is:

  ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm

- The parameter 'q' which is displayed while encoding is the current
  quantizer. The value of 1 indicates that a very good quality could
  be achieved. The value of 31 indicates the worst quality. If q=31
  too often, it means that the encoder cannot compress enough to meet
  your bit rate. You must either increase the bit rate, decrease the
  frame rate or decrease the frame size.

- To have the best compression, use the '-hq' option. It can run in
  real time only on the fastest computer (160x128 at 25 fps on a K6
  500). You can also use a large gop size (for example 250, which
  means one key frame every 250 frames).