README

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