Imported version 0.1
[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.  This very early version produces a set of
9 files suitable for passing to the "dvdauthor" and "spumux" programs,
10 but in future it is intended to run the necessary external programs
11 automatically.
12
13 Requirements
14 ------------
15
16 WebDVD depends on the following software:
17
18 - Gtkmm 2.0
19 - Mozilla 1.7.x (later versions may work but are untested)
20 - Xvfb (from XFree86 or X.org)
21
22 To build a complete DVD image you will also need:
23
24 - dvdauthor
25 - mjpegtools
26 - mkisofs
27 - netpbm
28
29 You will also need a program such as ffmpeg or mencoder for producing
30 DVD-suitable MPEG-1 or MPEG-2 video files.
31
32 Usage
33 -----
34
35 Run "webdvd URL" where URL is the URL for the page that is to be the
36 top menu of the DVD.  It will automatically follow links to other
37 pages and to video files, rendering each page.  You must be careful
38 not to link to pages that you do not want to appear on the disc, such
39 as normal web sites.
40
41 By default, webdvd uses a frame size of 720x576, which is suitable for
42 PAL DVDs.  If you wish to produce NTSC DVDs you must override this
43 by adding the option "-geometry 720x480".
44
45 This will create the following files (with NNNNNN replaced with each
46 successive page number):
47
48 - webdvd.dvdauthor: This is an XML file to be passed to dvdauthor.
49 - page_NNNNNN.spumux: These are XML files to be passed to spumux.
50 - page_NNNNNN_back.png: This is a static image of the page, which
51   becomes the menu background.
52 - page_NNNNNN_links.png: This is an image of the change in appearance
53   of each link when the pointer is over it.
54
55 Currently, you must run commands along the following lines to produce
56 a complete DVD image:
57
58 for spumux in page_??????.spumux; do
59     page=$(basename $spumux .spumux)
60     pngtopnm ${page}_back.png                              \
61     | ppmtoy4m -v0 -n 1 -F 25:1 -A 59:54 -I p -S 420_mpeg2 \
62     | mpeg2enc -v0 -f 8 -a 2 -o /dev/stdout                \
63     | mplex -v0 -f 8 -o /dev/stdout /dev/stdin             \
64     | spumux -v0 -m dvd $spumux > ${page}.vob
65 done
66 rm -rf dvd-temp
67 dvdauthor -o dvd-temp -x webdvd.dvdauthor
68 mkisofs -dvd-video dvd-temp >dvd.iso
69 rm -rf dvd-temp
70
71 Adjust the name of the temporary directory (here "dvd-temp") and the
72 output file ("dvd.iso") as you please.
73
74 If you are using NTSC video, you will need to change the ppmtoy4m
75 parameters.  Use "-F 30000:1001 -A 10:11" instead of "-F 25:1 -A 59:54".
76
77 Limitations
78 -----------
79
80 Each page must fit within the frame - DVD players do not support
81 scrolling menus and WebDVD currently is not able to split them into
82 multiple menus.  Note also that the video frame is somewhat larger
83 than the visible area of a normal TV.  For this reason WebDVD applies
84 a stylesheet to all pages that adds 50-60 pixels of padding on all
85 sides of the body.
86
87 WebDVD sends a "mouseover" event for each link and sets it into its
88 "hover" state, then records how this changes its appearance.  This
89 change is then shown when the corresponding button on the DVD menu is
90 highlighted.  WebDVD applies a stylesheet which changes the colour of
91 text links in the "hover" state, but this has no effect on image
92 links.  You must ensure that image links are highlighted in an obvious
93 way when the mouse pointer is over them.
94
95 The DVD specifications limit each menu to having no more than 36
96 buttons.  In any case, it is poor design to have very large numbers of
97 buttons on a single menu.  WebDVD will warn you if you use more than
98 this number of a links on a page, and will ignore any additional ones.
99
100 The DVD specification also limits the overlays that are used for
101 highlighting of buttons to using no more than 4 colours.  WebDVD will
102 reduce link highlighting to 1 transparent and 3 opaque colours using
103 Floyd-Steinberg dithering, which is certainly good enough for
104 anti-alised text but may not be so good for complex highlighting.
105
106 Author and copyright
107 --------------------
108
109 WebDVD was written by Ben Hutchings <ben@decadentplace.org.uk>.
110 Copyright 2005 Ben Hutchings.
111
112 This software is based in part on the work of the Independent JPEG Group.
113 Copyright 1991-1998 Thomas G. Lane.  (This applies to the file jquant2.c.)