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