1DVDAUTHOR(1) DVDAuthor Man Pages DVDAUTHOR(1)
2
6 dvdauthor - assembles multiple mpeg program streams into a suitable DVD
7 filesystem
8
10 dvdauthor [ -o output-dir ] -x xml-config-file
11 dvdauthor [ -o output-dir ] [ -j | --jumppad | -g | --allgprm ] [ -T |
14 --toc ] [ menu or title options ]
15
18 At a high level, a DVD is a collection of menus and titles. Conceptu‐
19 ally, a menu contains buttons which can be assigned actions and pro‐
20 vides a list of choices to the end user, while a title contains the
21 main content of the DVD. However, in reality many of the features
22 available in menus (including buttons, pausing, and looping) are also
23 available in titles.
24 The menus and titles are divided into titlesets and the VMGM menu set.
26 A titleset can contain a number of menus and titles which are meant to
27 act together. The "menu", "audio", "subtitle", and "angle" buttons on
28 the DVD player's remote control will all access menus in the same
29 titleset as the title which is being played. All the titles and menus
30 of a given titleset have the same video, audio, and subtitle settings
31 (the definitions for the menus are independent from the definitions for
32 the titles), so if you want to have different settings (for example
33 widescreen vs standard aspect ratios), then you need separate title‐
34 sets. Titlesets are not meant to jump to one another, so the VMGM menu
35 domain is used. It is a collection of menus (no titles) that can
36 access the menus and titles of all the titlesets.
37 One of the most frusterating things when deciding how to author a DVD
39 is that there are often many ways to accomplish the same task. For
40 example, you must decide whether to locate menus at the VMGM level or
41 the titleset level. A typical setup is to locate the high level menus
42 at the VMGM level, and the low level configuration menus (scene / audio
43 / subtitle selection) at the titleset. If there are DVD extras, per‐
44 haps with a lower quality audio track and a 4:3 aspect ratio, then they
45 would be in a separate titleset with a menu to select among the extras
46 located at the titleset level.
47
49 dvdauthor works in discrete operations. It authors each titleset one
50 at a time, and then finally authors the VMGM to complete the disc. At
51 that point the contents can be written out to a DVD. If you are con‐
52 trolling dvdauthor with command line arguments, then each step will
53 occur independently; however if you are using the XML configuration
54 file, then you have the option of combining some or all the steps into
55 one.
56 The VOBs passed to dvdauthor must have DVD NAV (VOBU) packets multi‐
58 plexed in at the correct locations. Many tools can do this, including
59 mplex from mjpegtools 1.6.0 or later. dvdauthor will then fill these
60 packets in with the correct data. Special care has been taken to
61 ensure dvdauthor is fifo compliant; that is every source VOB can be the
62 output of another program (such as mplex). This can make execution
63 faster on many systems by avoiding extra filesystem accesses.
64
66 -o output-dir
67 The destination directory to store the DVD-Video file structure
68 in.
69 -j
71 --jumppad
73 foo
74 -g
76 --allgprm
78 Enable the use of all 16 general purpose registers. Prohibits
79 the use of jumppad and some complex expressions that require
80 temporary registers.
81 -T Creates the table of contents file instead of a titleset. If
83 this option is used, it should be listed first, and you may not
84 specify any titles.
85 -m Creates a menu.
87 -t Creates a title.
89 -v video-opts
91 --video=video-opts
93 A plus (+) separated list of video options. Dvdauthor will try
94 to infer any unspecified options. pal, ntsc, 4:3, 16:9,
95 720xfull, 720x576, 720x480, 704xfull, 704x576, 704x480,
96 352xfull, 352x576, 352x480, 352xhalf, 352x288, 352x240, nopan‐
97 scan, noletterbox, crop. Default is ntsc, 4:3, 720xfull
98 -a audio-opts
100 --audio=audio-opts
102 A plus (+) separated list of options for an audio track, with
103 each track separated by a comma (,). For example -a
104 ac3+en,mp2+de specifies two audio tracks: the first is an Eng‐
105 lish track encoded in AC3, the second is a German track encoded
106 using MPEG-1 layer 2 compression. ac3, mp2, pcm, dts, 16bps,
107 20bps, 24bps, drc, surround, nolang, 1ch, 2ch, 3ch, 4ch, 5ch,
108 6ch, 7ch, 8ch, and any two letter ISO 639 language abbreviation.
109 Default is 1 track, mp2, 20bps, nolang, 2ch. 'ac3' implies drc,
110 6ch.
111 -s subpicture-opts
113 --subpictures=subpicture-opts
115 A plus (+) separated list of options for a subpicture track,
116 with each track separated by a comma (,). nolang and any two
117 letter language abbreviation (see -a) Default is no subpicture
118 tracks.
119 -e entry(s)
121 --entry=entry(s)
123 Makes the current menu the default for certain circumstances. It
124 is a comma separated list of any of:
125 for TOC menus: title
127 for VTS menus: root, ptt, audio, subtitle, angle
129 -p palette-file
131 --palette=palette-file
133 Specifies where to get the subpicture palette. Settable per
134 title and per menu. If the filename ends in .rgb (case insensi‐
135 tive) then it is assumed to be RGB, otherwise it is YUV. Entries
136 should be 6 hexadecimal digits. FILE defaults to xste-pal‐
137 ette.dat
138 -c chapterpts
140 --chapters=chapterpts
142 Specifies a comma (,) separated list of chapter markers. Each
143 marker is of the form [[h:]mm:]ss[.frac] and is relative to the
144 SCR of the next file listed (independent of any timestamp trans‐
145 posing that occurs within dvdauthor). The chapter markers ONLY
146 apply to the next file listed. Defaults to 0.
147 -f mpeg-file
149 --file=mpeg-file
151 mpeg-file
153 Specifies either a file, a pipe, or a shell command ending in |
154 which supplies an MPEG-2 system stream with VOB sectors inserted
155 in the appropriate places (using mplex -f 8 to generate)
156 -b buttondef
158 --button=X1xY1-X2xY2,commandlist
160 creates a button of the specified size. See LANGUAGE DESCRIPTION
161 for a description of commandlist.
162 -i [pre|post]=commandlist
164 --instructions=[pre|post]=commandlist
166 Executes the commandlist instructions either before or at the
167 end of the menu/title. See LANGUAGE DESCRIPTION for the format
168 of commandlist.
169
171 Here is the basic structure of the configuration file:
172 <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"]>
174 <vmgm>
175 [<fpc>commands;</fpc>]
176 <menus [lang="language-code"] >
177 <video [format="ntsc|pal"] [aspect="4:3|16:9"]
178 [resolution="XxY"] [caption="field1|field2"]
179 [widescreen="nopanscan|noletterbox|crop"] />
180 <audio [format="mp2|ac3|dts|pcm"] [channels="numchannels"]
181 [quant="16bps|20bps|24bps|drc"] [dolby="surround"]
182 [samplerate="48khz|96khz"] [lang="language"] />
183 [<audio ... />]
184 <subpicture lang="language" />
185 <pgc [entry="title"] [palette="yuvfile|rgbfile"]
186 [pause="seconds|inf"]>
187 <pre> commands; </pre>
188 <vob file="file.mpg" [chapters="chapter-list"]
189 [pause="seconds|inf"] />
190 [<vob ... />]
191 <button [name="buttonname"]> commands; </button>
192 [<button ... />]
193 <post> commands; </post>
194 </pgc>
195 [<pgc ... />]
196 </menus>
197 </vmgm>
198 <titleset>
199 <menus>
200 [<video ... />]
201 [<audio ... />]
202 <pgc [entry="entries"]
203 [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
204 [...]
205 </pgc>
206 [<pgc ... />]
207 </menus>
208 <titles>
209 [<video ... />]
210 [<audio ... />]
211 <pgc [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
212 [...]
213 </pgc>
214 [<pgc ... />]
215 </titles>
216 </titleset>
217 [<titleset ... />]
218 </dvdauthor>
219 A breakdown of the config file:
221 <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | all‐
223 gprm="1|on|yes"]>
224 Initiates dvdauthor. dest denotes the directory where dvdauthor
225 will write the files. It overrides the -o option. Contains up
226 to one <vmgm> tag and any number of <titleset>'s.
227 <vmgm>
229 <titleset>
231 Constructs of a VMGM level menu set or a title set. Contains up
232 to one <menus> tag and if a titleset, up to one <titles> tag.
233 <menus [lang="language-code"] >
235 <titles>
237 Marks the list of menus or titles for this VMGM menu set or
238 titleset, called in dvdauthor terminology a "pgcgroup." Con‐
239 tains up to one <video> tag, up to eight <audio> tags, up to 32
240 <subpicture> tags, and any number of <pgc> tags.
241 <video [format="ntsc|pal"] [aspect="4:3|16:9"] [resolution="XxY"] [cap‐
243 tion="field1|field2"] [widescreen="nopanscan|noletterbox|crop"] />
244 Manually configures the video parameters for this pgcgroup. If
245 any of these are not set, then they will be inferred from the
246 source stream. Note that the DVD format only specifically sup‐
247 ports 720x480, 704x480, 352x480, and 352x240 resolutions for
248 NTSC, and 720x576, 704x576, 352x576, and 352x288 resolutions for
249 PAL, but DVD author will accept a wider range of inputs and
250 round up to the nearest size.
251 <audio [format="mp2|ac3|dts|pcm"] [channels="numchannels"] [dolby="sur‐
253 round"] [quant="16bps|20bps|24bps|drc"] [samplerate="48khz|96khz"]
254 [lang="language"] />
255 Manually configures an audio channel for this pgcgroup. List
256 once for each channel. Most parameters are inferred automati‐
257 cally from the source VOBs except for PCM parameters. However,
258 language must be manually specified. Note that it is possible
259 to just list the language attribute and let dvdauthor fill in
260 the rest.
261 <subpicture lang="language" />
263 foo
264 <pgc [entry="entries"] [palette="yuvfile|rgbfile"] [pause="sec‐
266 onds|inf"]>
267 A PGC is just a fancy term for either a menu or a title. It has
268 a special meaning in the DVD spec so I have retained its use
269 here. PGC's can have commands that get executed before they
270 start playing or after they finish; see pre and post tags below.
271 If the PGC is a menu, you can specify one or more entries for
273 it. This means that if you press the corresponding button on
274 your DVD remote, then it will go to this menu. For a VMGM level
275 menu, the only choice is title, which on my remote corresponds
276 to the top menu button. For a titleset level menu, you can use
277 root, subtitle, audio, angle, and ptt. If you want more than
278 one, separate them by a space or a comma. Note that root entry
279 is meant for commands that jump from a VMGM level menu to a
280 titleset menu.
281 All button and menu masks and all subtitles within a PGC must
283 share the same 16 color palette. If you use spumux to generate
284 the subtitle/subpicture packets, then the color information will
285 be automatically passed to dvdauthor; however, if you use
286 another subtitler or want to have more control over the palette,
287 you can manually specify it with the palette attribute. The
288 first 16 entries of the file should be the 16 colors of the pal‐
289 ette, listed as 6 digit hexadecimal numbers representing either
290 the RGB breakdown (if the filename ends in .rgb or the YUV
291 breakdown (if the filename does not end in .rgb. After that,
292 the button group information can be listed as pairs of 8 digit
293 hexadecimal numbers; up to three button groups may be specified.
294 If you have a short video sequence or just want the video to
296 pause at the end, you can use the pause attribute to set the
297 number of seconds (as an integer) from 1 to 254. If you want
298 the video to pause indefinitely, use inf.
299 <pre> commands; </pre>
301 <post> commands; </post>
303 Sets the commands to execute before or after a PGC plays. It
304 can be used to loop the current video (by having a <post> jump
305 ... </post> sequence), or to conditionally skip certain chapters
306 if a flag has been set.
307 <fpc> commands; </fpc>
309 Sets the commands to execute when the disk is first put in the
310 player (FPC = First Program Chain). It can be used to jump to a
311 particular menu or initialize registers on startup. If not
312 specified, an implicit one will be created that jumps to the
313 first menu found, or if there is no menu it will jump to the
314 first title..
315 <vob file="file.mpg" [chapters="chapter-list"] [pause="seconds|inf"] />
317 foo
318 <cell [start="timestamp"] [end="timestamp"] [chapter="1|on|yes" | pro‐
320 gram="1|on|yes"] [pause="seconds|inf"] />
321 foo
322 <button [name="buttonname"]> commands; </button>
324 foo
325
327 The language is quite simple and roughly looks like C.
328 · Statements are terminated with a semicolon.
330 · Statements can span multiple lines.
332 · Multiple statements can appear on one line.
334 · Whitespace (space, tab, newlines) are not important, except to sepa‐
336 rate keywords and identifiers.
337 VARIABLES
339 The DVD virtual machine processes 16 bit values. It supports up to 16
340 general purpose registers; however dvdauthor reserves 3 for internal
341 use. Thus register 0-12 are avaialable for use and are referred to as
342 g0 through g12.
343 There are also 24 system registers, which can be referred to as s0
345 through s23. Not all of these can be set. Many of these have
346 pseodonyms.
347 audio (s1, rw)
349 Denotes the audio channel, ranging from 0-7.
350 subtitle (s2, rw)
352 The subtitle track, ranging from 0-31. If you want the subtitle
353 to always be displayed, then you should add 64 (i.e. choose
354 64-95). Simply selecting the track (0-31) means that only the
355 forced subtitles will be displayed, whereas enabling the track
356 (64-95) means that all the subtitles will be displayed. This
357 allows you to have forced subtitles only for the parts of the
358 movie where the actors are speaking a foreign (to the viewer)
359 language, but still have normal subtitles for the hearing
360 impaired. The hearing impaired viewers would enable the track
361 (64-95) while the other viewers would just select the track
362 (0-31) they would be able to share the track.
363 angle (s3, rw)
365 Selects the angle (currently untested).
366 button (s8, rw)
368 Denotes the currently highlighted button. Note that the value
369 is multiplied by 1024, so the first button is 1024, the second
370 is 2048, etc.
371 EXPRESSIONS
373 Expressions follow typical C syntax except that booleans are not con‐
374 vertible to integers and vice versa. Operators and comparisons are:
375 ==, !=, >=, >, <=, <, &&, ||, !, eq, ne, ge, gt, le, lt, and, or, xor,
377 not, +, -, *, /, %, &, |, ^
378 Since the code is encapsulated in XML, the parser will catch any
380 unescaped < characters, thus alphabetic mnemonics have been provided
381 for all comparison operators for consistency.
382 There is also a numerical function:
384 random(EXPRESSION)
386 Computes a psuedo-random number, between 1 and the supplied num‐
387 ber, inclusively.
388 BLOCKS
390 Blocks are either a single statement (terminated by a semicolon), or a
391 group of statements wrapped in curly braces. For example:
392 ·
394 g3=s7;
395 ·
397 {
398 audio=1;
399 subtitle=65;
400 jump vmgm menu 3;
401 }
402 STATEMENTS
404 The statements supported are fairly simple at the moment.
405 VARIABLE=EXPRESSION;
407 Sets a variable equal to the result of an equation.
408 if (EXPRESSION) BLOCK;
410 if (EXPRESSION) BLOCK; else BLOCK;
412 Calculates the expression; if true, then it executes the block
413 of code.
414 jump TARGET;
416 call TARGET [resume CELL];
418 resume;
420 Jumps to a particular title or menu, or calls a particular menu,
421 or returns to the calling title. You can only execute a call
422 from a title to a menu; all other forms are illegal. The pur‐
423 pose of using call instead of jump (besides the fact that they
424 support a mutually exclusive list of targets) is to allow the
425 menu to return to the point in the title where the call origi‐
426 nated using resume. You can manually specify the return cell by
427 using the resume keyword, however if you do not specify one and
428 you use the command in a post instruction block, then it will
429 presume cell 1.
430 The following are possible targets:
432 [vmgm | titleset X] menu
434 [vmgm | titleset X] menu Y
436 [vmgm | titleset X] menu entry Z
438 Targets either the default menu, a menu number Y, or the
439 menu denoted as the entry for Z. The menu is in either
440 the VMGM or titleset domain. If you wish to target a
441 menu in the current domain then you can omit the domain
442 moniker.
443 [vmgm | titleset X] title Y [chapter Z]
445 Targets a title, or a chapter in a title. Numbering
446 starts at 1. All of the titles on the disc are accessi‐
447 ble in the VMGM domain, or you can access them by title‐
448 set instead.
449 chapter Z
451 program Z
453 cell Z Targets a chapter, program, or cell in the current title
455 or menu (note that menus do not have chapters). You can
456 use this to create looping menus: jump cell 1;
457 13 January 2007 DVDAUTHOR(1)