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