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-control-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 frustrating things when deciding how to author a DVD is
39 that there are often many ways to accomplish the same task. For exam‐
40 ple, you must decide whether to locate menus at the VMGM level or the
41 titleset level. A typical setup is to locate the high level menus at
42 the VMGM level, and the low level configuration menus (scene / audio /
43 subtitle selection) at the titleset. If there are DVD extras, perhaps
44 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 control file,
54 then you have the option of combining some or all the steps into one.
55 The VOBs passed to dvdauthor must have DVD NAV (VOBU) packets multi‐
57 plexed in at the correct locations. Many tools can do this, including
58 mplex from mjpegtools 1.6.0 or later. dvdauthor will then fill these
59 packets in with the correct data. Special care has been taken to
60 ensure dvdauthor is fifo compliant; that is every source VOB can be the
61 output of another program (such as mplex). This can make execution
62 faster on many systems by avoiding extra filesystem accesses.
63
65 -o output-dir
66 -O output-dir
68 The destination directory to store the DVD-Video file structure
69 in. If -O is specified, then any existing directory is deleted.
70 -j
72 --jumppad
74 Enables the creation of jumppads, which allow greater flexibil‐
75 ity in choosing jump/call desinations.
76 -g
78 --allgprm
80 Enable the use of all 16 general purpose registers. Prohibits
81 the use of jumppad and some complex expressions that require
82 temporary registers.
83 -T Creates the table of contents file instead of a titleset. If
85 this option is used, it should be listed first, and you may not
86 specify any titles.
87 -m Creates a menu.
89 -t Creates a title.
91 -v video-opts
93 --video=video-opts
95 A plus (+) separated list of video options. Dvdauthor will try
96 to infer any unspecified options. pal, ntsc, 4:3, 16:9,
97 720xfull, 720x576, 720x480, 704xfull, 704x576, 704x480,
98 352xfull, 352x576, 352x480, 352xhalf, 352x288, 352x240, nopan‐
99 scan, noletterbox, crop. Default is 4:3, 720xfull
100 -a audio-opts
102 --audio=audio-opts
104 A plus (+) separated list of options for an audio track, with
105 each track separated by a comma (,). For example -a
106 ac3+en,mp2+de specifies two audio tracks: the first is an Eng‐
107 lish track encoded in AC3, the second is a German track encoded
108 using MPEG-1 layer 2 compression. ac3, mp2, pcm, dts, 16bps,
109 20bps, 24bps, drc, surround, nolang, 1ch, 2ch, 3ch, 4ch, 5ch,
110 6ch, 7ch, 8ch, and any two letter ISO 639 language abbreviation.
111 Default is 1 track, mp2, 20bps, nolang, 2ch. 'ac3' implies drc,
112 6ch.
113 -s subpicture-opts
115 --subpictures=subpicture-opts
117 A plus (+) separated list of options for a subpicture track,
118 with each track separated by a comma (,). nolang and any two
119 letter language abbreviation (see -a) Default is no subpicture
120 tracks.
121 -e entry(s)
123 --entry=entry(s)
125 Makes the current menu the default for certain circumstances. It
126 is a comma separated list of any of:
127 for TOC menus: title
129 for VTS menus: root, ptt, audio, subtitle, angle
131 -p palette-file
133 --palette=palette-file
135 Specifies where to get the subpicture palette. Settable per
136 title and per menu. If the filename ends in .rgb (case insensi‐
137 tive) then it is assumed to be RGB, otherwise it is YUV. Entries
138 should be 6 hexadecimal digits. FILE defaults to xste-pal‐
139 ette.dat
140 -c chapterpts
142 --chapters=chapterpts
144 Specifies a comma (,) separated list of chapter markers. Each
145 marker is of the form [[h:]mm:]ss[.frac] and is relative to the
146 SCR of the next file listed (independent of any timestamp trans‐
147 posing that occurs within dvdauthor). The chapter markers ONLY
148 apply to the next file listed. Defaults to 0.
149 -f mpeg-file
151 --file=mpeg-file
153 mpeg-file
155 Specifies either a file, a pipe, or a shell command ending in |
156 which supplies an MPEG-2 system stream with VOB sectors inserted
157 in the appropriate places (using mplex -f 8 to generate)
158 -b buttondef
160 --button=X1xY1-X2xY2,commandlist
162 creates a button of the specified size. See LANGUAGE DESCRIPTION
163 for a description of commandlist.
164 -i [pre|post]=commandlist
166 --instructions=[pre|post]=commandlist
168 Executes the commandlist instructions either before or at the
169 end of the menu/title. See LANGUAGE DESCRIPTION for the format
170 of commandlist.
171
173 Here is the basic structure of the control file:
174 <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"]>
176 <vmgm>
177 [<fpc>commands;</fpc>]
178 <menus [lang="language-code"]>
179 <video [format="ntsc|pal"] [aspect="4:3|16:9"]
180 [resolution="XxY"] [caption="field1|field2"]
181 [widescreen="nopanscan|noletterbox|crop"] />
182 <audio [format="mp2|ac3|dts|pcm"] [channels="numchannels"]
183 [quant="16bps|20bps|24bps|drc"] [dolby="surround"]
184 [samplerate="48khz|96khz"] [lang="language"]
185 [content="normal|impaired|comments1|comments2"] />
186 [<audio ... />]
187 <subpicture [lang="language-code"]>
188 <stream mode="normal|widescreen|letterbox|panscan"
189 [content="normal|large|children|normal_cc|large_cc|children_cc|forced|director|large_director|children_director"]
190 id="streamid" />
191 [<stream ... />]
192 </subpicture>
193 [<subpicture ... />]
194 <pgc [entry="title"] [palette="yuvfile|rgbfile"]
195 [pause="seconds|inf"]>
196 <subpicture>
197 [<stream ... />]
198 </subpicture>
199 <pre> commands; </pre>
200 <vob file="file.mpg" [chapters="chapter-list"]
201 [pause="seconds|inf"]>
202 <cell [start="timestamp"] [end="timestamp"]
203 [chapter="1|on|yes" | program="1|on|yes"] [pause="seconds|inf"]>
204 commands;
205 </cell>
206 </vob>
207 [<vob ... />]
208 <button [name="buttonname"]> commands; </button>
209 [<button ... />]
210 <post> commands; </post>
211 </pgc>
212 [<pgc ... />]
213 </menus>
214 [<menus ... />]
215 </vmgm>
216 <titleset>
217 <menus [lang="language-code"]>
218 [<video ... />]
219 [<audio ... />]
220 <pgc [entry="entries"]
221 [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
222 [...]
223 </pgc>
224 [<pgc ... />]
225 </menus>
226 [<menus ... />]
227 <titles>
228 [<video ... />]
229 [<audio ... />]
230 <pgc [entry="notitle"] [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
231 [...]
232 </pgc>
233 [<pgc ... />]
234 </titles>
235 </titleset>
236 [<titleset ... />]
237 </dvdauthor>
238 A breakdown of the control file:
240 <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | all‐
242 gprm="1|on|yes"]>
243 Initiates dvdauthor. dest denotes the directory where dvdauthor
244 will write the files. This is overridden by the -o option. Con‐
245 tains up to one <vmgm> tag and any number of <titleset>'s.
246 <vmgm>
248 <titleset>
250 Constructs of a VMGM level menu set or a title set. Contains
251 zero or more <menus> tags and if a titleset, up to one <titles>
252 tag.
253 <menus [lang="language-code"]>
255 Marks a list of menus with a common language for this VMGM menu
256 set or titleset, called in dvdauthor terminology a "pgcgroup."
257 Contains up to one <video> tag, up to one <audio> tag, up to one
258 <subpicture> tag, and any number of <pgc> tags.
259 <titles>
261 Marks the list of titles for this titleset, called in dvdauthor
262 terminology a "pgcgroup." Contains up to one <video> tag, up to
263 eight <audio> tags, up to 32 <subpicture> tags, and any number
264 of <pgc> tags.
265 <video [format="ntsc|pal"] [aspect="4:3|16:9"] [resolution="XxY"] [cap‐
267 tion="field1|field2"] [widescreen="nopanscan|noletterbox|crop"] />
268 Manually configures the video parameters for this pgcgroup. If
269 any of these are not set, then they will be inferred from the
270 source stream. Note that the DVD format only specifically sup‐
271 ports 720x480, 704x480, 352x480, and 352x240 resolutions for
272 NTSC, and 720x576, 704x576, 352x576, and 352x288 resolutions for
273 PAL, but DVD author will accept a wider range of inputs and
274 round up to the nearest size.
275 <audio [format="mp2|ac3|dts|pcm"] [channels="numchannels"] [dolby="sur‐
277 round"] [quant="16bps|20bps|24bps|drc"] [samplerate="48khz|96khz"]
278 [lang="language"] [content="normal|impaired|comments1|comments2"] />
279 Manually configures an audio stream for this pgcgroup. List
280 once for each stream. Most parameters are inferred automati‐
281 cally from the source VOBs except for PCM parameters. However,
282 language and content must be manually specified. Note that it
283 is possible to just list the language and content attributes and
284 let dvdauthor fill in the rest.
285 <subpicture [lang="language"] [content="normal|large|children|nor‐
287 mal_cc|large_cc|children_cc|forced|director|large_director|chil‐
288 dren_director"] />
289 Manually configures a subpicture/subtitle for this pgcgroup or
290 PGC. At the pgcgroup level, list once for each language. Occur‐
291 rences at the PGC level don't have lang or content attributes;
292 they inherit those from the corresponding <subpicture> tag at
293 the pgcgroup level.
294 <stream mode="normal|widescreen|letterbox|panscan" id="streamid" />
296 Specifies the ID of a stream that is the representation of this
297 subpicture in a particular display mode. This can be specified
298 per-PGC, or pgcgroup-wide.
299 <pgc [entry="entries"] [palette="yuvfile|rgbfile"] [pause="sec‐
301 onds|inf"]>
302 A PGC is just a fancy term for either a menu or a title. It has
303 a special meaning in the DVD spec so I have retained its use
304 here. PGC's can have commands that get executed before they
305 start playing or after they finish; see <pre> and <post> tags
306 below.
307 If the PGC is a menu, you can specify one or more entries for
309 it. This means that if you press the corresponding button on
310 your DVD remote, then it will go to this menu. For a VMGM level
311 menu, the only choice is title, which on my remote corresponds
312 to the top menu button. For a titleset level menu, you can use
313 root, subtitle, audio, angle, and ptt. If you want more than
314 one, separate them by a space or a comma. Note that root entry
315 is meant for commands that jump from a VMGM level menu to a
316 titleset menu.
317 If the PGC is in a titleset, then it is assumed to be a title
319 unless entry="notitle" is specified.
320 All button and menu masks and all subtitles within a PGC must
322 share the same 16 color palette. If you use spumux to generate
323 the subtitle/subpicture packets, then the color information will
324 be automatically passed to dvdauthor; however, if you use
325 another subtitler or want to have more control over the palette,
326 you can manually specify it with the palette attribute. The
327 first 16 entries of the file should be the 16 colors of the pal‐
328 ette, listed as 6 digit hexadecimal numbers representing either
329 the RGB breakdown (if the filename ends in .rgb or the YUV
330 breakdown (if the filename does not end in .rgb. After that,
331 the button group information can be listed as pairs of 8 digit
332 hexadecimal numbers; up to three button groups may be specified.
333 If you have a short video sequence or just want the video to
335 pause at the end, you can use the pause attribute to set the
336 number of seconds (as an integer) from 1 to 254. If you want
337 the video to pause indefinitely, use inf.
338 <pre> commands; </pre>
340 <post> commands; </post>
342 Sets the commands to execute before or after a PGC plays. It
343 can be used to loop the current video (by having a <post> jump
344 ... </post> sequence), or to conditionally skip certain chapters
345 if a flag has been set.
346 <fpc> commands; </fpc>
348 Sets the commands to execute when the disk is first put in the
349 player (FPC = First Program Chain). It can be used to jump to a
350 particular menu or initialize registers on startup. If not
351 specified, an implicit one will be created that jumps to the
352 first menu found, or if there is no menu it will jump to the
353 first title..
354 <vob file="file.mpg" [chapters="chapter-list"] [pause="seconds|inf"] />
356 Specifies an input video file for a menu or title, with optional
357 chapter points and pause at the end.
358 <cell [start="timestamp"] [end="timestamp"] [chapter="1|on|yes" | pro‐
360 gram="1|on|yes"] [pause="seconds|inf"]> commands; </cell>
361 A more detailed way of specifying marker points in a title. If
362 present, then the containing <vob> must not have a chapters
363 attribute. A cell can have a VM command attached to it, to be
364 executed when it plays. If the program attribute is set, then
365 this cell will be a point that the user can skip to using the
366 prev/next buttons on their DVD player remote. If the chapter
367 attribute is set (implies program is set as well), then this
368 cell is also a chapter point.
369 <button [name="buttonname"]> commands; </button>
371 Specifies the commands to be executed when the user selects the
372 button with the specified name. You define button names and
373 placements with spumux.
374
376 The language is quite simple and roughly looks like C.
377 · Statements are terminated with a semicolon.
379 · Statements can span multiple lines.
381 · Multiple statements can appear on one line.
383 · Whitespace (space, tab, newlines) are not important, except to sepa‐
385 rate keywords and identifiers.
386 · C-style /* ... */ comments are allowed. Or you can use XML comments
388 <!-- like this -->
389 VARIABLES
391 The DVD virtual machine processes 16 bit values. It supports up to 16
392 general purpose registers; however dvdauthor reserves 3 for internal
393 use. Thus register 0-12 are avaialable for use and are referred to as
394 g0 through g12.
395 There are also 24 system registers, which can be referred to as s0
397 through s23. Not all of these can be set. Many of these have mnemonic
398 synonyms.
399 audio (s1, rw)
401 Denotes the audio stream, ranging from 0-7.
402 subtitle (s2, rw)
404 The subtitle track, ranging from 0-31. If you want the subtitle
405 to always be displayed, then you should add 64 (i.e. choose
406 64-95). Simply selecting the track (0-31) means that only the
407 forced subtitles will be displayed, whereas enabling the track
408 (64-95) means that all the subtitles will be displayed. This
409 allows you to have forced subtitles only for the parts of the
410 movie where the actors are speaking a foreign (to the viewer)
411 language, but still have normal subtitles for the hearing
412 impaired. The hearing impaired viewers would enable the track
413 (64-95) while the other viewers would just select the track
414 (0-31) they would be able to share the track.
415 angle (s3, rw)
417 Selects the angle (currently untested).
418 button (s8, rw)
420 Denotes the currently highlighted button. Note that the value
421 is multiplied by 1024, so the first button is 1024, the second
422 is 2048, etc.
423 EXPRESSIONS
425 Expressions follow typical C syntax except that booleans are not con‐
426 vertible to integers and vice versa. Operators and comparisons are:
427 ==, !=, >=, >, <=, <, &&, ||, !, eq, ne, ge, gt, le, lt, and, or, xor,
429 not, +, -, *, /, %, &, |, ^
430 Since the code is encapsulated in XML, the parser will catch any
432 unescaped < characters (i.e. not written as "<"), thus alphabetic
433 mnemonics have been provided for all comparison operators for consis‐
434 tency. Or you can put the code in a <![CDATA[ ... ]]> section.
435 There is also a numerical function:
437 random(EXPRESSION)
439 Computes a psuedo-random number, between 1 and the supplied num‐
440 ber, inclusively.
441 BLOCKS
443 Blocks are either a single statement (terminated by a semicolon), or a
444 group of statements wrapped in curly braces. For example:
445 ·
447 g3=s7;
448 ·
450 {
451 audio=1;
452 subtitle=65;
453 jump vmgm menu 3;
454 }
455 STATEMENTS
457 The statements supported are fairly simple at the moment.
458 VARIABLE=EXPRESSION;
460 Sets a variable equal to the result of an equation.
461 if (EXPRESSION) BLOCK;
463 if (EXPRESSION) BLOCK; else BLOCK;
465 Calculates the expression; if true, then it executes the block
466 of code.
467 jump TARGET;
469 call TARGET [resume CELL];
471 resume;
473 Jumps to a particular title or menu, or calls a particular menu,
474 or returns to the calling title. You can only execute a call
475 from a title to a menu; all other forms are illegal. The pur‐
476 pose of using call instead of jump (besides the fact that they
477 support a mutually exclusive list of targets) is to allow the
478 menu to return to the point in the title where the call origi‐
479 nated using resume. You can manually specify the return cell by
480 using the resume keyword, however if you do not specify one and
481 you use the command in a post instruction block, then it will
482 presume cell 1.
483 TARGETS
485 The following are possible targets (note that menus do not have chap‐
486 ters):
487 [vmgm | titleset X] menu
489 [vmgm | titleset X] menu Y
491 [vmgm | titleset X] menu entry Z
493 Targets either the default menu, a menu number Y, or the menu
494 denoted as the entry for Z. The menu is in either the VMGM or
495 titleset domain. If you wish to target a menu in the current
496 domain then you can omit the domain moniker.
497 [titleset X] title Y [chapter Z]
499 Targets a title, or a chapter in a title. Numbering starts at
500 1. All of the titles on the disc are accessible in the VMGM
501 domain, or you can access them by titleset instead.
502 chapter Z
504 Targets a chapter in the current title.
505 program Z
507 cell Z Targets a program or cell in the current PGC. You can use this
509 to create looping menus: jump cell 1;
510 cell top
512 next cell
514 prev cell
516 program top
518 next program
520 prev program
522 pgc top
524 next pgc
526 prev pgc
528 up pgc
530 pgc tail
532 (Jump only) performs relative transfers of control within the
533 current menu/title. "cell/program/pgc top" goes back to the
534 start of the current cell/program/PGC; "next/prev cell/pro‐
535 gram/pgc" goes to the next or previous cell/program/PGC; "up
536 pgc" goes to the "up" PGC (not currently settable in dvdauthor);
537 and "pgc tail" goes to the <post> sequence in the current PGC.
538 Chapters are numbered from 1 in each title, while programs are numbered
540 from 1 in each PGC. Thus, the latter can reset independently of the
541 former when there is more than one PGC in a title.
542
544 The following limits are imposed by the DVD-Video spec.
545 There can be no more than 99 titlesets, no more than 99 menus in the
547 VMG or a titleset, and no more than 99 titles in a titleset.
548 Each title may be made up of up to 999 PGCs. Each PGC may consist of up
550 to 255 programs. The <pre> and <post> sections of a PGC put together
551 can contain no more than 128 VM instructions.
552 Since there is only one VOB file (VIDEO_TS.VOB) in the VMG, the total
554 amount of video in the VMG menus must fit into 1073709056 bytes (524272
555 sectors of 2kiB each). In each titleset, all the menu video must fit in
556 the first VOB (VTS_nn_0.VOB), so is limited to the same amount.
557 <marc.leeman@gmail.com> MarcLeeman2003Marc LeemanFri Dec 30 19:47:26
558 CET 2005
559 23 October 2010 DVDAUTHOR(1)