This is LibDV, a GPL codec for DV video.

See http://libdv.sourceforge.net/

LibDV now uses the GNU "Autotools" for building.

BUILDING from CVS checkout
==========================

Starting with version 0.98, the libdv CVS repository does include the
configure script generated by the autotools.  Hopefully, this will
ease the pain for people who are not inclined to modify their machines
installation just to build libdv.

If you do have such desire, you can still bootstrap the build
with*:

  autoreconf -i

You should check for any fatal errors, noting that you can expect some
warnings which are harmless.


To build the libdv library and the example player:

  ./configure
  make

The makefile generated by the autotools is very large, so the more
useful targets don't jump out at you.  Here are a few.

Build a "tar.gz" distribution file:

  make dist

Build a rpm package file.  This requires you run as root, or you
setup your ~/.rpmmacros to allow building rpms without root:

  make rpm

Clean up objects and binaries:

  make clean

Clean up including files generated by autotools, which should return
the working directory state to be like it as after a CVS checkout:

  make maintainer-clean


* Since libdv 0.103, the boostrap file is considered obsolete.
  Autoconf now includes the program autoreconf that can serve the
  same role.



NTSC Setup/Pedestal
===================

This option has been disabled in libdv due to improper usage.
If you are still curious about this topic, see Adam Wilt's DV FAQ:
http://www.adamwilt.com/DV-FAQ-tech.html#Setup


Luma and Chroma Clamping
========================

ITU-R 601 specifies that the legal range for luma is 16-235 and
for chroma is 16-240 regardless of NTSC, PAL, or setup issues. However,
some users take advantage of the footroom or headroom below or above
these ranges to encode additional information for things such as
luma keying. The luma and chroma clamp options permit the range checking
to be disabled to preserve the superblack and superwhite.

For more information read Charles' Poyton's Color FAQ:
http://www.inforamp.net/~poynton/notes/colour_and_gamma/ColorFAQ.html#RTFToC30

and his white paper "Merging Computing with Studio Video:
Converting Between R'G'B' and 4:2:2":
http://home.inforamp.net/~poynton/papers/Discreet_Logic/index.html

dvconnect is a small utility to send / capture raw data from / to the
camcorder over an OHCI complient IEEE 1394 firewire adapter. It has to be
an OHCI adapter since we use the video1394 interface. (It could be done for
receiving without it, but for sending it's the only way to go!)

You should also install the latest Linux Kernel version (> 2.4.12 I think)
since otherwise the necessary patches for DV _sending_ are not included.

dvconnect was written to be simple and fast.
If it doesn't work for you, you might want to check out dvgrab from
Arne Schirmacher... (http://www.schirmacher.de)

Since the video1394 interface is not fully developed, you have to do some
parameter twiddling to make it work.

First, do

	modprobe ohci1394
	modprobe video1394

Then try to catch some test-video data using:

	dvconnect >test.dv

Verify, using playdv if you are in doubt.

If that worked, try

	dvconnect -s --syt-offset=OFFSET <test.dv

to send the data back to your camcorder. Where OFFSET is some number between
10000-26000. The default is 11000 (should work for everyone, but
in fact it doesn't...) You know, that you got it, when the picture in the view
finder stands still and no gray boxes are jumping around anymore.

If your harddisk is not fast enough or your system is under load then you
can control the user-space memory buffer using -b and the kernel buffer
using -k.

	The kernel buffer should be large enough to bring dvconnect over
one scheduler slice. (approx 1/10 second)
	The user-space memory buffer should be large enough to compensate
for varying disk transfer rates. (defaults to 10 seconds on PAL)

	dvconnect will always warn you, if you got broken frames but
only if it is in capture mode!

This is a small explanation of the statistics tables generated by encodedv:

CYCLE are the cycles in the quantization loop until a matching QNO is found
      (affects speed)

RUNS/CYCLE (for 3-pass VLC) : Tries to skip quantisation steps if it is
      clear that a _lot_ more bits are needed. Makes things faster but
      maybe quality drops a little bit. Smaller values mean better quality and
      larger values mean that you gained some speed.

QNO   is the quantization number. Larger values mean lesser quantization
      (15=no quantization at all!) and better quality. You will notice, that
      there are gaps between the values in the statistics. (Especially if
      you choose "--vlc-passes=3", where qnos are most likely 15 or 8.)
      This is normal behaviour since depending on the quantization CLASS
      some QNOs don't gain you anything and are therefore skipped. There are
      even codes, that _never_ gain you anything regardless of the chosen
      classes.

CLASS is the quantization class. (Greater values mean higher quantization.)
      This is used to quantizise larger AC coefficients more than smaller ones.
      For now, we use the following table

               max AC-value
               0 - 11  |  12 - 23  |  24 - 35  | >35
               -----------------------------------------
             Y   0     |     1     |     2     |   3
            CR   1     |     2     |     3     |   3
            CB   2     |     3     |     3     |   3

      from the IEC documentation (which is only given for reference.)
      If you want to improve this, keep the following in mind:
      * These classes are chosen with the vlc code lengths in mind.
        There is one code length for codes between 0..11, for 12..23 etc.
      * You _have_ to use class 3 for AC coeffs. larger than 255, since they
        can't get encoded otherwise.
      * It is sensible to quantizise CR and CB values more than Y values.
        (a) they don't matter that much and b) their bit budget is therefore
        smaller!)
      * Larger classes give you finer control over the QNO.
      * Smaller classes don't have necessarily better quality since you may
        be encoding quantization noise. That's from the IEC document. I don't
        know, why they consider picture details with extremely small
        coefficients as noise, but I agree that large coefficients don't
        really need all the lower bits.
VLC OVERF is the number of vlc_encoder overflows you encountered. That means
      that some AC coefficients simply aren't encoded!
      At best it means your picture is somewhat blurred and at worst it has
      a very psychedelic touch...
      This should only happen in two cases
      a) if you use "--vlc-passes==1,2" and QNO 0
      b) static_qno since the simple heuristic used can fail easily

DCT MODE is the DCT mode chosen. DCT248 is used for fast moving sequences,
      where the two fields encoded differ a lot. DCT88 has generally better
      quality. The decision is based on the accumulated differences between
      the two fields that are larger than a hard coded threshold divided
      by the same difference in x direction. This makes sure that spotlights
      are encoded with DCT 88 and not with DCT 248.
      Something like (sum_i abs(field1[i] - field2[i])) /
	              sum_i abs(block[i+1] - block[i])) > dct_248_limit
TODO:
     - finally go to the library and get the header block specifications ;-)
     - think of a better way to implement static_qno for 1,3 vlc passes
     - do correct synchronisation between audio and video (synchronise
       against system clock since we can't be sure, that the soundcard
       clock is 100% accurate)
     - skip frames correctly
     - find a way to detect NTSC / PAL for video or finally add a
       force-video-format option.