VideoLink
=========

VideoLink is intended to provide a simple way of producing DVDs with
attractive and usable menus.  It converts HTML pages into DVD menus by
rendering them in Mozilla and reproducing their link structure.  This
allows you to design DVDs using familiar HTML editing tools or your
favourite text editor.

Prior to version 0.8, VideoLink was called WebDVD, but that name is
also used for an extended DVD format.

Requirements
------------

VideoLink depends on the following software:

- dvdauthor
- expat 1.x
- Gtkmm 2.0
- ffmpeg or mjpegtools
- Mozilla 1.7.8 or later, or XULRunner
- netpbm
- Xvfb (from XFree86 or X.org)

To build a complete DVD image you will also need:

- mkisofs

You will also need a program for producing DVD-suitable MPEG-1 or
MPEG-2 video files.

Usage
-----

Design your DVD menus as a series of HTML pages linking to each other
and to MPEG-1/2 videos that are suitable for use on a DVD.  You must
be careful not to link to pages that you do not want to appear on the
disc, such as normal web sites.  Also note the limitations listed
below.

Linking to video

You can link directly to local MPEG video files whose names end in
".vob".  If you wish to combine multiple files into a single video
sequence ("title" in DVD terminology) or to add chapter marks to a
video sequence, create and link to a VOB-list file (explained below)
whose name ends in ".voblist".

VOB-lists

A VOB-list file is an XML file with the document element <vob-list>
and containing <vob> elements as described in the dvdauthor manual
page.  The file names in a VOB-list file are resolved relative to the
directory containing the list file.  For example:

    <vob-list>
        <vob file="main.vob" chapters="0:00,4:55,12:13,17:45"/>
        <vob file="credits.vob"/>
    </vob-list>

This will result in a title with the following chapters:

    1: main.vob  0:00- 4:55
    2: main.vob  4:55-12:13
    3: main.vob 12:13-17:45
    4: main.vob 17:45-  end
    5: credits.vob

Video standards

The encoding of analogue TV and video signals varies in many different
ways between countries.  Happily there are only two parameters that
matter for standard-definition digital video, and two different pairs
of values.  You can choose between these with the --video-std option:

Analogue parameters   | Region of world              | --video-std | Frame
                      |                              | argument    | size
----------------------+------------------------------+-------------+--------
59.94 fields/second,  | Americas except Argentina,   | 525         | 720x576
interlaced;           | Paraguay, Uruguay;           | or 525/60   |
525 lines/frame       | Japan; Laos; Myanmar;        | or NTSC     |
(commonly called      | Philippines; South Korea;    | or ntsc     |
 NTSC)                | Taiwan; some Pacific islands |             |
----------------------+------------------------------+-------------+--------
50 fields/second,     | Rest of world                | 625         | 720x480
interlaced;           |                              | or 625/50   |
625 lines/frame       |                              | or PAL      |
(commonly called PAL) |                              | or pal      |

The default is to use "PAL" parameters.

Currently 

Preview

To get a rough preview of the menus, run "videolink --preview menu-url"
where menu-url is the URL or filename of the first page to show.
Currently videos cannot be displayed in this preview mode.

Processing

To create a DVD filesystem, run "videolink menu-url output-dir" where
menu-url is the URL or filename of the top menu page and output-dir is
the directory in which to create the filesystem (which should be
either nonexistent or empty).  VideoLink will automatically follow links
to the other pages and to the video files.

By default, VideoLink now calls ffmpeg to generate MPEG-2 streams for
menus.  If you want it to use mjpegtools as it previously did, you
must add the option "--encoder mjpegtools".  If you use mjpegtools
1.6.2 or earlier you must instead use "--encoder mjpegtools-old".
This is due to an incompatible change in the syntax of the ppmtoy4m
command between versions 1.6.2 and 1.8.

If this is successful you can then use mkisofs to create a DVD image
from the output directory.  Alternately you can write this directory
directly to a writable DVD with growisofs or with mkisofs piped to a
suitable version of cdrecord.

Example
-------

A live example set of menus can currently be found at
<http://womble.decadent.org.uk/software/debconf5-dvd/menus/main.html>.
Note that this has large background images that will take some time to
load.

Limitations
-----------

Each page must fit within the frame - DVD players do not support
scrolling menus and VideoLink currently is not able to split them into
multiple menus.  The frame size is dictated by the video standard; see
above.  The exact visible area varies between TVs so the background
should cover all or very nearly all the frame whereas the important
content such as text must not be placed near the edge.  For this
reason VideoLink applies a stylesheet to all pages that adds 60 pixels of
padding on all sides of the body; this doesn't apply to the
background.

Prior to version 1.8, Mozilla may signal that a page is completely
loaded before any background images are loaded and displayed.  This
can result in VideoLink converting the page without the background
images.  If VideoLink is built with an older version of Mozilla you
can work around this by using absolutely-positioned "inline" images,
since Mozilla will always wait for these to load.

DVD players do not have "back" buttons, so you should generally
provide links to "higher" menu pages.  However, they do have a button
for returning to the top menu.

VideoLink sends a "mouseover" event for each link and sets it into its
"hover" state, then records how this changes its appearance.  This
change is then shown when the corresponding button on the DVD menu is
highlighted.  VideoLink applies a stylesheet which changes the colour of
text links in the "hover" state, but this has no effect on image
links.  You must ensure that image links are highlighted in an obvious
way when the mouse pointer is over them.

The DVD specifications limit each menu to having no more than 36
buttons.  In any case, it is poor design to have very large numbers of
buttons on a single menu.  VideoLink will warn you if you use more than
this number of a links on a page, and will ignore any additional ones.

The DVD specification also limits the overlays that are used for
highlighting of buttons to using no more than 4 colours.  VideoLink will
reduce link highlighting to 1 transparent and 3 opaque colours using
Floyd-Steinberg dithering, which is certainly good enough for
anti-aliased text but may not be so good for complex highlighting.

There is a limit of 99 "titles" on a DVD.  If you need to include more
than this number of video sequences, you could arrange them as
chapters of a title, so long as they use the same codecs, resolution,
aspect ratio and sample rate.  However, each chapter will run into the
next.  If this is a real problem, let me know, and I may be able to
provide a better solution in a later version of VideoLink.

Author and copyright
--------------------

VideoLink was written by Ben Hutchings <ben@decadent.org.uk>.
Copyright 2005-2006 Ben Hutchings.

This software is based in part on the work of the Independent JPEG Group.
Copyright 1991-1998 Thomas G. Lane.  (This applies to the file jquant2.c.)
