README

   1 VideoLink
   2 =========
   3
   4 VideoLink is intended to provide a simple way of producing DVDs with
   5 attractive and usable menus.  It converts HTML pages into DVD menus by
   6 rendering them in Mozilla and reproducing their link structure.  This
   7 allows you to design DVDs using familiar HTML editing tools or your
   8 favourite text editor.
   9
  10 Prior to version 0.8, VideoLink was called WebDVD, but that name is
  11 also used for an extended DVD format.
  12
  13 Requirements
  14 ------------
  15
  16 VideoLink depends on the following software:
  17
  18 - dvdauthor
  19 - expat 1.x
  20 - Gtkmm 2.0
  21 - ffmpeg or mjpegtools
  22 - Mozilla 1.7.8 or later, or XULRunner
  23 - netpbm
  24 - Xvfb (from XFree86 or X.org)
  25
  26 To build a complete DVD image you will also need:
  27
  28 - mkisofs
  29
  30 You will also need a program for producing DVD-suitable MPEG-1 or
  31 MPEG-2 video files.
  32
  33 Usage
  34 -----
  35
  36 Design your DVD menus as a series of HTML pages linking to each other
  37 and to MPEG-1/2 videos that are suitable for use on a DVD.  You must
  38 be careful not to link to pages that you do not want to appear on the
  39 disc, such as normal web sites.  Also note the limitations listed
  40 below.
  41
  42 Linking to video
  43
  44 You can link directly to local MPEG video files whose names end in
  45 ".mpeg", ".mpeg2" or ".vob".  If you wish to combine multiple files
  46 into a single video sequence ("title" in DVD terminology) or to add
  47 chapter marks to a video sequence, create and link to a VOB-list file
  48 (explained below) whose name ends in ".voblist".
  49
  50 VOB-lists
  51
  52 A VOB-list file is an XML file with the document element <vob-list>
  53 and containing <vob> elements as described in the dvdauthor manual
  54 page.  The file names in a VOB-list file are resolved relative to the
  55 directory containing the list file.  For example:
  56
  57     <vob-list>
  58         <vob file="main.vob" chapters="0:00,4:55,12:13,17:45"/>
  59         <vob file="credits.vob"/>
  60     </vob-list>
  61
  62 This will result in a title with the following chapters:
  63
  64     1: main.vob  0:00- 4:55
  65     2: main.vob  4:55-12:13
  66     3: main.vob 12:13-17:45
  67     4: main.vob 17:45-  end
  68     5: credits.vob
  69
  70 Video standards
  71
  72 The encoding of analogue TV and video signals varies in many different
  73 ways between countries.  Happily there are only two parameters that
  74 matter for standard-definition digital video, and two different pairs
  75 of values.  You can choose between these with the --video-std option:
  76
  77 Analogue parameters   | Region of world              | --video-std | Frame
  78                       |                              | argument    | size
  79 ----------------------+------------------------------+-------------+--------
  80 59.94 fields/second,  | Americas except Argentina,   | 525         | 720x576
  81 interlaced;           | Paraguay, Uruguay;           | or 525/60   |
  82 525 lines/frame       | Japan; Laos; Myanmar;        | or NTSC     |
  83 (commonly called      | Philippines; South Korea;    | or ntsc     |
  84  NTSC)                | Taiwan; some Pacific islands |             |
  85 ----------------------+------------------------------+-------------+--------
  86 50 fields/second,     | Rest of world                | 625         | 720x480
  87 interlaced;           |                              | or 625/50   |
  88 625 lines/frame       |                              | or PAL      |
  89 (commonly called PAL) |                              | or pal      |
  90
  91 The default is to use "PAL" parameters.
  92
  93 Currently
  94
  95 Preview
  96
  97 To get a rough preview of the menus, run "videolink --preview menu-url"
  98 where menu-url is the URL or filename of the first page to show.
  99 Currently videos cannot be displayed in this preview mode.
 100
 101 Processing
 102
 103 To create a DVD filesystem, run "videolink menu-url output-dir" where
 104 menu-url is the URL or filename of the top menu page and output-dir is
 105 the directory in which to create the filesystem (which should be
 106 either nonexistent or empty).  VideoLink will automatically follow links
 107 to the other pages and to the video files.
 108
 109 By default, VideoLink now calls ffmpeg to generate MPEG-2 streams for
 110 menus.  If you want it to use mjpegtools as it previously did, you
 111 must add the option "--encoder mjpegtools".  If you use mjpegtools
 112 1.6.2 or earlier you must instead use "--encoder mjpegtools-old".
 113 This is due to an incompatible change in the syntax of the ppmtoy4m
 114 command between versions 1.6.2 and 1.8.
 115
 116 If this is successful you can then use mkisofs to create a DVD image
 117 from the output directory.  Alternately you can write this directory
 118 directly to a writable DVD with growisofs or with mkisofs piped to a
 119 suitable version of cdrecord.
 120
 121 Example
 122 -------
 123
 124 A live example set of menus can currently be found at
 125 <http://womble.decadent.org.uk/software/debconf5-dvd/menus/main.html>.
 126 Note that this has large background images that will take some time to
 127 load.
 128
 129 Limitations
 130 -----------
 131
 132 Each page must fit within the frame - DVD players do not support
 133 scrolling menus and VideoLink currently is not able to split them into
 134 multiple menus.  The frame size is dictated by the video standard; see
 135 above.  The exact visible area varies between TVs so the background
 136 should cover all or very nearly all the frame whereas the important
 137 content such as text must not be placed near the edge.  For this
 138 reason VideoLink applies a stylesheet to all pages that adds padding
 139 equal to 10% of the frame dimension on each side of the body; this
 140 doesn't apply to the background.
 141
 142 Prior to version 1.8, Mozilla may signal that a page is completely
 143 loaded before any background images are loaded and displayed.  This
 144 can result in VideoLink converting the page without the background
 145 images.  If VideoLink is built with an older version of Mozilla you
 146 can work around this by using absolutely-positioned "inline" images,
 147 since Mozilla will always wait for these to load.
 148
 149 DVD players do not have "back" buttons, so you should generally
 150 provide links to "higher" menu pages.  However, they do have a button
 151 for returning to the top menu.
 152
 153 VideoLink sends a "mouseover" event for each link and sets it into its
 154 "hover" state, then records how this changes its appearance.  This
 155 change is then shown when the corresponding button on the DVD menu is
 156 highlighted.  VideoLink applies a stylesheet which changes the colour of
 157 text links in the "hover" state, but this has no effect on image
 158 links.  You must ensure that image links are highlighted in an obvious
 159 way when the mouse pointer is over them.
 160
 161 The DVD specifications limit each menu to having no more than 36
 162 buttons.  In any case, it is poor design to have very large numbers of
 163 buttons on a single menu.  VideoLink will warn you if you use more than
 164 this number of a links on a page, and will ignore any additional ones.
 165
 166 The DVD specification also limits the overlays that are used for
 167 highlighting of buttons to using no more than 4 colours.  VideoLink will
 168 reduce link highlighting to 1 transparent and 3 opaque colours using
 169 Floyd-Steinberg dithering, which is certainly good enough for
 170 anti-aliased text but may not be so good for complex highlighting.
 171
 172 There is a limit of 99 "titles" on a DVD.  If you need to include more
 173 than this number of video sequences, you could arrange them as
 174 chapters of a title, so long as they use the same codecs, resolution,
 175 aspect ratio and sample rate.  However, each chapter will run into the
 176 next.  If this is a real problem, let me know, and I may be able to
 177 provide a better solution in a later version of VideoLink.
 178
 179 Currently VideoLink code can generate up to 999 menus but it may be
 180 possible for me to raise this internal limit if you want more.  There
 181 appears to be an absolute limit of 12800 menus on a DVD.
 182
 183 Bugs
 184 ----
 185
 186 Under Mozilla 1.7, VideoLink sets the assumed screen resolution to
 187 40 dpi, which I reckon to be the average resolution of a standard
 188 definition TV display.  This should mean that text with a font size
 189 expressed in millimetres or points will appear around the specified
 190 size.  Unfortunately this setting has a different effect under
 191 Mozilla/XULRunner 1.8:
 192
 193 Mozilla   Assumed    Requested     Actual size
 194 version  resolution    size     (pixels) (inches)
 195            (dpi)
 196
 197   1.7    default:96    20 px       20      0.5
 198   1.7    default:96    36 pt       48      1.2
 199   1.7        40        20 px       20      0.5
 200   1.7        40        36 pt       20      0.5
 201   1.8    default:96    20 px       20      0.5
 202   1.8    default:96    36 pt       48      1.2
 203   1.8        40        20 px       48      1.2
 204   1.8        40        36 pt       48      1.2
 205
 206 From version 0.10, until I have a proper solution, VideoLink will not
 207 set the assumed screen resolution under Mozilla 1.8.  I must advise
 208 against using font sizes in millimetres or points since they will vary
 209 between browser versions.
 210
 211 Author and copyright
 212 --------------------
 213
 214 VideoLink was written by Ben Hutchings <ben@decadent.org.uk>.
 215 Copyright 2005-2006 Ben Hutchings.
 216
 217 This software is based in part on the work of the Independent JPEG Group.
 218 Copyright 1991-1998 Thomas G. Lane.  (This applies to the file jquant2.c.)