1DVDAUTHOR(1)                  DVDAuthor Man Pages                 DVDAUTHOR(1)
2
3
4

NAME

6       dvdauthor - assembles multiple mpeg program streams into a suitable DVD
7       filesystem
8

SYNOPSIS

10       dvdauthor [ -o output-dir ] -x xml-control-file
11
12
13       dvdauthor [ -o output-dir ] [ -j | --jumppad | -g | --allgprm ] [ -T  |
14       --toc ] [ menu or title options ]
15
16

DVD BACKGROUND

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
25       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
38       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

DVDAUTHOR DESCRIPTION

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
56       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

COMMAND LINE DESCRIPTION

65       -o output-dir
66
67       -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
73       -x xml-control-file
74              Specifies  the  control  file describing the output structure to
75              create.
76
77       Note that the remaining command-line options are  deprecated.  Use  the
78       XML control file instead.
79
80       -j
81
82       --jumppad
83              Enables  the creation of jumppads, which allow greater flexibil‐
84              ity in choosing jump/call destinations.
85
86       -g
87
88       --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
93       -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
97       -m     Creates a menu.
98
99       -t     Creates a title.
100
101       -v video-opts
102
103       --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
110       -a audio-opts
111
112       --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
123       -s subpicture-opts
124
125       --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
131       -e entry(s)
132
133       --entry=entry(s)
134              Makes the current menu the default for certain circumstances. It
135              is a comma separated list of any of:
136
137              for TOC menus: title
138
139              for VTS menus: root, ptt, audio, subtitle, angle
140
141       -p palette-file
142
143       --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
150       -c chapterpts
151
152       --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
159       -f mpeg-file
160
161       --file=mpeg-file
162
163       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
168       -b buttondef
169
170       --button=X1xY1-X2xY2,commandlist
171              creates a button of the specified size. See LANGUAGE DESCRIPTION
172              for a description of commandlist.
173
174       -i [pre|post]=commandlist
175
176       --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

XML DESCRIPTION

182       Here is the basic structure of the control file:
183
184       <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
248       A breakdown of the control file:
249
250       <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
256       <vmgm>
257
258       <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
263       <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
269       <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
275       <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
285       <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
295       <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
304       <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
309       <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
317              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
327              If  the  PGC  is in a titleset, then it is assumed to be a title
328              unless entry="notitle" is specified.
329
330              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
343              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
348       <pre> commands; </pre>
349
350       <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
356       <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
364       <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
368       <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
379       <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

LANGUAGE DESCRIPTION

385       The language is quite simple and roughly looks like C.
386
387       · Statements are terminated with a semicolon.
388
389       · Statements can span multiple lines.
390
391       · Multiple statements can appear on one line.
392
393       · Whitespace  (space, tab, newlines) are not important, except to sepa‐
394         rate keywords and identifiers.
395
396       · C-style /* ... */ comments are allowed. Or you can use  XML  comments
397         <!-- like this -->
398
399   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
405       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
409       audio (s1, rw)
410              Denotes the audio stream, ranging from 0-7.
411
412       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
425       angle (s3, rw)
426              Selects the angle (currently untested).
427
428       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
433   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
437       ==,  !=, >=, >, <=, <, &&, ||, !, eq, ne, ge, gt, le, lt, and, or, xor,
438       not, +, -, *, /, %, &, |, ^
439
440       Since the code is encapsulated  in  XML,  the  parser  will  catch  any
441       unescaped  <  characters  (i.e. not written as "&lt;"), 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
445       There is also a numerical function:
446
447       random(EXPRESSION)
448              Computes a pseudo-random number, between 1 and the supplied num‐
449              ber, inclusively.
450
451   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
455       ·
456         g3 = s7;
457
458       ·
459         {
460           audio = 1;
461           subtitle = 65;
462           jump vmgm menu 3;
463         }
464
465   STATEMENTS
466       The statements supported are fairly simple at the moment.
467
468       VARIABLE = EXPRESSION;
469              Sets a variable equal to the result of an equation.
470
471       if (EXPRESSION) BLOCK;
472
473       if (EXPRESSION) BLOCK; else BLOCK;
474              Calculates  the  expression; if true, then it executes the block
475              of code.
476
477       jump TARGET;
478
479       call TARGET [resume CELL];
480
481       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
493   TARGETS
494       The  following  are possible targets (note that menus do not have chap‐
495       ters):
496
497       [vmgm | titleset X] menu
498
499       [vmgm | titleset X] menu Y
500
501       [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
507       [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
512       pgc Z  Targets a PGC in the current VMGM or titleset.
513
514       chapter Z
515              Targets a chapter in the current title.
516
517       program Z
518
519       cell Z Targets  a program or cell in the current PGC.  You can use this
520              to create looping menus: jump cell 1;
521
522       cell top
523
524       next cell
525
526       prev cell
527
528       program top
529
530       next program
531
532       prev program
533
534       pgc top
535
536       next pgc
537
538       prev pgc
539
540       up pgc
541
542       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
550       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

LIMITATIONS

555       The following limits are imposed by the DVD-Video spec.
556
557       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
560       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
564       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
570
571
572                               31 December 2016                   DVDAUTHOR(1)
Impressum