Brought documentation up to date.
[videolink.git] / 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 By default, webdvd generates PAL/SECAM video.  If you wish to produce
70 NTSC DVDs you can override this by adding the option "--video-std ntsc"
71 to the following commands.
72
73 Preview
74
75 To get a rough preview of the menus, run "webdvd --preview menu-url"
76 where menu-url is the URL or filename of the first page to show.
77 Currently videos cannot be displayed in this preview mode.
78
79 Processing
80
81 To create a DVD filesystem, run "webdvd menu-url output-dir" where
82 menu-url is the URL or filename of the top menu page and output-dir is
83 the directory in which to create the filesystem (which should be
84 either nonexistent or empty).  WebDVD will automatically follow links
85 to the other pages and to the video files.
86
87 By default, WebDVD now calls ffmpeg to generate MPEG-2 streams for
88 menus.  If you want it to use mjpegtools as it previously did, you
89 must add the option "--encoder mjpegtools".  If you use mjpegtools
90 1.6.2 or earlier you must instead use "--encoder mjpegtools-old".
91 This is due to an incompatible change in the syntax of the ppmtoy4m
92 command between versions 1.6.2 and 1.8.
93
94 If this is successful you can then use mkisofs to create a DVD image
95 from the output directory.  Alternately you can write this directory
96 directly to a writable DVD with growisofs or with mkisofs piped to a
97 suitable version of cdrecord.
98
99 Example
100 -------
101
102 A live example set of menus can currently be found at
103 <http://womble.decadent.org.uk/software/debconf5-dvd/menus/main.html>.
104 Note that this has large background images that will take some time to
105 load.
106
107 Limitations
108 -----------
109
110 Each page must fit within the frame - DVD players do not support
111 scrolling menus and WebDVD currently is not able to split them into
112 multiple menus.  The standard frame size for PAL and SECAM is 720x576
113 pixels; for NTSC it is 720x480 pixels.  The exact visible area varies
114 between TVs so the background should cover all or very nearly all the
115 frame whereas the important content such as text must not be placed
116 near the edge.  For this reason WebDVD applies a stylesheet to all
117 pages that adds 60 pixels of padding on all sides of the body; this
118 doesn't apply to the background.
119
120 Prior to Mozilla version 1.8, which I have not yet tested, Mozilla may
121 signal that a page is completely loaded before any background images
122 are loaded and displayed.  This results in snapshots that do not
123 include background images.  You can work around this by using
124 absolutely-positioned "inline" images, or attempt to build WebDVD
125 against Mozilla 1.8.
126
127 DVD players do not have "back" buttons, so you should generally
128 provide links to "higher" menu pages.  However, they do have a button
129 for returning to the top menu.
130
131 WebDVD sends a "mouseover" event for each link and sets it into its
132 "hover" state, then records how this changes its appearance.  This
133 change is then shown when the corresponding button on the DVD menu is
134 highlighted.  WebDVD applies a stylesheet which changes the colour of
135 text links in the "hover" state, but this has no effect on image
136 links.  You must ensure that image links are highlighted in an obvious
137 way when the mouse pointer is over them.
138
139 The DVD specifications limit each menu to having no more than 36
140 buttons.  In any case, it is poor design to have very large numbers of
141 buttons on a single menu.  WebDVD will warn you if you use more than
142 this number of a links on a page, and will ignore any additional ones.
143
144 The DVD specification also limits the overlays that are used for
145 highlighting of buttons to using no more than 4 colours.  WebDVD will
146 reduce link highlighting to 1 transparent and 3 opaque colours using
147 Floyd-Steinberg dithering, which is certainly good enough for
148 anti-aliased text but may not be so good for complex highlighting.
149
150 There is a limit of 99 "titles" on a DVD.  If you need to include more
151 than this number of video sequences, you could arrange them as
152 chapters of a title, so long as they use the same codecs, resolution,
153 aspect ratio and sample rate.  However, each chapter will run into the
154 next.  If this is a real problem, let me know, and I may be able to
155 provide a better solution in a later version of WebDVD.
156
157 Author and copyright
158 --------------------
159
160 WebDVD was written by Ben Hutchings <ben@decadent.org.uk>.
161 Copyright 2005-2006 Ben Hutchings.
162
163 This software is based in part on the work of the Independent JPEG Group.
164 Copyright 1991-1998 Thomas G. Lane.  (This applies to the file jquant2.c.)