Man Linux: Main Page and Category List


       dvdauthor - assembles multiple mpeg program streams into a suitable DVD


       dvdauthor [ -o output-dir ] -x xml-control-file

       dvdauthor [ -o output-dir ] [ -j | --jumppad | -g | --allgprm ] [ -T  |
       --toc ] [ menu or title options ]


       At  a  high  level,  a  DVD  is  a  collection  of  menus  and  titles.
       Conceptually, a menu contains buttons which can be assigned actions and
       provides  a list of choices to the end user, while a title contains the
       main content of the DVD.  However, in  reality  many  of  the  features
       available  in  menus (including buttons, pausing, and looping) are also
       available in titles.

       The menus and titles are divided into titlesets and the VMGM menu  set.
       A  titleset can contain a number of menus and titles which are meant to
       act together.  The "menu", "audio", "subtitle", and "angle" buttons  on
       the  DVD  player’s  remote  control  will  all access menus in the same
       titleset as the title which is being played.  All the titles and  menus
       of  a  given titleset have the same video, audio, and subtitle settings
       (the definitions for the menus are independent from the definitions for
       the  titles),  so  if  you want to have different settings (for example
       widescreen  vs  standard  aspect  ratios),  then  you   need   separate
       titlesets.  Titlesets are not meant to jump to one another, so the VMGM
       menu domain is used.  It is a collection of menus (no titles) that  can
       access the menus and titles of all the titlesets.

       One of the most frustrating things when deciding how to author a DVD is
       that there are often many  ways  to  accomplish  the  same  task.   For
       example,  you  must decide whether to locate menus at the VMGM level or
       the titleset level.  A typical setup is to locate the high level  menus
       at the VMGM level, and the low level configuration menus (scene / audio
       / subtitle selection) at  the  titleset.   If  there  are  DVD  extras,
       perhaps  with  a lower quality audio track and a 4:3 aspect ratio, then
       they would be in a separate titleset with a menu to  select  among  the
       extras located at the titleset level.


       dvdauthor  works  in discrete operations.  It authors each titleset one
       at a time, and then finally authors the VMGM to complete the disc.   At
       that  point  the  contents  can  be  written  out to a DVD.  If you are
       controlling dvdauthor with command line arguments, then each step  will
       occur  independently;  however  if  you are using the XML control file,
       then you have the option of combining some or all the steps into one.

       The  VOBs  passed  to  dvdauthor  must  have  DVD  NAV  (VOBU)  packets
       multiplexed  in  at  the  correct  locations.   Many tools can do this,
       including mplex from mjpegtools 1.6.0 or later.   dvdauthor  will  then
       fill  these  packets  in  with the correct data.  Special care has been
       taken to ensure dvdauthor is fifo compliant; that is every  source  VOB
       can  be  the  output of another program (such as mplex).  This can make
       execution faster on many systems by avoiding extra filesystem accesses.


       -o output-dir
              The  destination directory to store the DVD-Video file structure


              Enables  the  creation  of   jumppads,   which   allow   greater
              flexibility in choosing jump/call desinations.


              Enable  the  use of all 16 general purpose registers.  Prohibits
              the use of jumppad and some  complex  expressions  that  require
              temporary registers.

       -T     Creates  the  table  of  contents file instead of a titleset. If
              this option is used, it should be listed first, and you may  not
              specify any titles.

       -m     Creates a menu.

       -t     Creates a title.

       -v video-opts

              A  plus (+) separated list of video options.  Dvdauthor will try
              to  infer  any  unspecified  options.   pal,  ntsc,  4:3,  16:9,
              720xfull,   720x576,   720x480,   704xfull,   704x576,  704x480,
              352xfull,  352x576,   352x480,   352xhalf,   352x288,   352x240,
              nopanscan, noletterbox, crop.  Default is ntsc, 4:3, 720xfull

       -a audio-opts

              A  plus  (+)  separated list of options for an audio track, with
              each  track  separated  by  a  comma  (,).    For   example   -a
              ac3+en,mp2+de  specifies  two  audio  tracks:  the  first  is an
              English track encoded in AC3,  the  second  is  a  German  track
              encoded  using  MPEG-1 layer 2 compression.  ac3, mp2, pcm, dts,
              16bps, 20bps, 24bps, drc, surround, nolang, 1ch, 2ch, 3ch,  4ch,
              5ch,  6ch,  7ch,  8ch,  and  any  two  letter  ISO  639 language
              abbreviation.  Default is 1  track,  mp2,  20bps,  nolang,  2ch.
              ’ac3’ implies drc, 6ch.

       -s subpicture-opts

              A  plus  (+)  separated  list of options for a subpicture track,
              with each track separated by a comma (,).  nolang  and  any  two
              letter  language  abbreviation (see -a) Default is no subpicture

       -e entry(s)

              Makes the current menu the default for certain circumstances. It
              is a comma separated list of any of:

              for TOC menus: title

              for VTS menus: root, ptt, audio, subtitle, angle

       -p palette-file

              Specifies  where  to  get  the  subpicture palette. Settable per
              title  and  per  menu.  If  the  filename  ends  in  .rgb  (case
              insensitive)  then it is assumed to be RGB, otherwise it is YUV.
              Entries should be 6 hexadecimal digits. FILE defaults  to  xste-

       -c chapterpts

              Specifies  a  comma  (,) separated list of chapter markers. Each
              marker is of the form [[h:]mm:]ss[.frac] and is relative to  the
              SCR  of  the  next  file  listed  (independent  of any timestamp
              transposing that occurs within dvdauthor). The  chapter  markers
              ONLY apply to the next file listed. Defaults to 0.

       -f mpeg-file


              Specifies  either a file, a pipe, or a shell command ending in |
              which supplies an MPEG-2 system stream with VOB sectors inserted
              in the appropriate places (using mplex -f 8 to generate)

       -b buttondef

              creates a button of the specified size. See LANGUAGE DESCRIPTION
              for a description of commandlist.

       -i [pre|post]=commandlist

              Executes the commandlist instructions either before  or  at  the
              end  of the menu/title.  See LANGUAGE DESCRIPTION for the format
              of commandlist.


       Here is the basic structure of the control file:

       <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"]>
             <menus [lang="language-code"]>
                <video [format="ntsc|pal"] [aspect="4:3|16:9"]
                       [resolution="XxY"] [caption="field1|field2"]
                       [widescreen="nopanscan|noletterbox|crop"] />
                <audio [format="mp2|ac3|dts|pcm"] [channels="numchannels"]
                       [quant="16bps|20bps|24bps|drc"] [dolby="surround"]
                       [samplerate="48khz|96khz"] [lang="language"]
                       [content="normal|impaired|comments1|comments2"] />
                [<audio ... />]
                <subpicture [lang="language-code"]>
                   <stream mode="normal|widescreen|letterbox|panscan"
                       id="streamid" />
                   [<stream ... />]
                [<subpicture ... />]
                <pgc [entry="title"] [palette="yuvfile|rgbfile"]
                      [<stream ... />]
                   <pre> commands; </pre>
                   <vob file="file.mpg" [chapters="chapter-list"]
                        <cell [start="timestamp"] [end="timestamp"]
                           [chapter="1|on|yes" | program="1|on|yes"] [pause="seconds|inf"]>
                   [<vob ... />]
                   <button [name="buttonname"]> commands; </button>
                   [<button ... />]
                   <post> commands; </post>
                [<pgc ... />]
             [<menus ... />]
             <menus [lang="language-code"]>
                [<video ... />]
                [<audio ... />]
                <pgc [entry="entries"]
                     [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                [<pgc ... />]
             [<menus ... />]
                [<video ... />]
                [<audio ... />]
                <pgc [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                [<pgc ... />]
          [<titleset ... />]

       A breakdown of the control file:

       <dvdauthor       [dest="output-dir"]       [jumppad="1|on|yes"        |
              Initiates dvdauthor.  dest denotes the directory where dvdauthor
              will  write the files.  It overrides the -o option.  Contains up
              to one <vmgm> tag and any number of <titleset>’s.


              Constructs of a VMGM level menu set or a  title  set.   Contains
              zero  or more <menus> tags and if a titleset, up to one <titles>

       <menus [lang="language-code"]>
              Marks a list of menus with a common language for this VMGM  menu
              set  or  titleset, called in dvdauthor terminology a "pgcgroup."
              Contains up to one <video> tag, up to one <audio> tag, up to one
              <subpicture> tag, and any number of <pgc> tags.

              Marks the list of titles for this  titleset, called in dvdauthor
              terminology a "pgcgroup."  Contains up to one <video> tag, up to
              eight  <audio>  tags, up to 32 <subpicture> tags, and any number
              of <pgc> tags.

       <video   [format="ntsc|pal"]   [aspect="4:3|16:9"]   [resolution="XxY"]
       [caption="field1|field2"] [widescreen="nopanscan|noletterbox|crop"] />
              Manually configures the video parameters for this pgcgroup.   If
              any  of  these  are not set, then they will be inferred from the
              source stream.  Note  that  the  DVD  format  only  specifically
              supports  720x480, 704x480, 352x480, and 352x240 resolutions for
              NTSC, and 720x576, 704x576, 352x576, and 352x288 resolutions for
              PAL,  but  DVD  author  will  accept a wider range of inputs and
              round up to the nearest size.

       <audio       [format="mp2|ac3|dts|pcm"]        [channels="numchannels"]
       [dolby="surround"]                      [quant="16bps|20bps|24bps|drc"]
       [samplerate="48khz|96khz"]                            [lang="language"]
       [content="normal|impaired|comments1|comments2"] />
              Manually configures an audio stream  for  this  pgcgroup.   List
              once   for   each   stream.    Most   parameters   are  inferred
              automatically from the source VOBs except  for  PCM  parameters.
              However,  language and content must be manually specified.  Note
              that it is possible  to  just  list  the  language  and  content
              attributes and let dvdauthor fill in the rest.

       <subpicture                                           [lang="language"]
              Manually  configures  a subpicture/subtitle for this pgcgroup or
              PGC.  At the  pgcgroup  level,  list  once  for  each  language.
              Occurrences  at  the  PGC  level  don’t  have  lang  or  content
              attributes;  they   inherit   those   from   the   corresponding
              <subpicture> tag at the pgcgroup level.

       <stream mode="normal|widescreen|letterbox|panscan" id="streamid" />
              Specifies  the ID of a stream that is the representation of this
              subpicture in a particular display mode. This can  be  specified
              per-PGC, or pgcgroup-wide.

       <pgc            [entry="entries"]           [palette="yuvfile|rgbfile"]
              A PGC is just a fancy term for either a menu or a title.  It has
              a special meaning in the DVD spec so I  have  retained  its  use
              here.   PGC’s  can  have  commands that get executed before they
              start playing or after they finish; see <pre>  and  <post>  tags

              If  the  PGC  is a menu, you can specify one or more entries for
              it.  This means that if you press the  corresponding  button  on
              your DVD remote, then it will go to this menu.  For a VMGM level
              menu, the only choice is title, which on my  remote  corresponds
              to  the top menu button.  For a titleset level menu, you can use
              root, subtitle, audio, angle, and ptt.  If you  want  more  than
              one,  separate them by a space or a comma.  Note that root entry
              is meant for commands that jump from a  VMGM  level  menu  to  a
              titleset menu.

              All  button  and  menu masks and all subtitles within a PGC must
              share the same 16 color palette.  If you use spumux to  generate
              the subtitle/subpicture packets, then the color information will
              be automatically  passed  to  dvdauthor;  however,  if  you  use
              another subtitler or want to have more control over the palette,
              you can manually specify it with  the  palette  attribute.   The
              first  16  entries  of  the  file should be the 16 colors of the
              palette, listed as  6  digit  hexadecimal  numbers  representing
              either  the  RGB  breakdown (if the filename ends in .rgb or the
              YUV breakdown (if the filename does  not  end  in  .rgb.   After
              that,  the  button group information can be listed as pairs of 8
              digit hexadecimal numbers; up to  three  button  groups  may  be

              If  you  have  a  short video sequence or just want the video to
              pause at the end, you can use the pause  attribute  to  set  the
              number  of  seconds  (as an integer) from 1 to 254.  If you want
              the video to pause indefinitely, use inf.

       <pre> commands; </pre>

       <post> commands; </post>
              Sets the commands to execute before or after a  PGC  plays.   It
              can  be  used to loop the current video (by having a <post> jump
              ... </post> sequence), or to conditionally skip certain chapters
              if a flag has been set.

       <fpc> commands; </fpc>
              Sets  the  commands to execute when the disk is first put in the
              player (FPC = First Program Chain).  It can be used to jump to a
              particular  menu  or  initialize  registers  on startup.  If not
              specified, an implicit one will be created  that  jumps  to  the
              first  menu  found,  or  if there is no menu it will jump to the
              first title..

       <vob file="file.mpg" [chapters="chapter-list"] [pause="seconds|inf"] />
              Specifies an input video file for a menu or title, with optional
              chapter points and pause at the end.

       <cell   [start="timestamp"]   [end="timestamp"]  [chapter="1|on|yes"  |
       program="1|on|yes"] [pause="seconds|inf"]> commands; </cell>
              A  more  detailed way of specifying marker points in a title. If
              present, then the containing <vob>  must  not  have  a  chapters
              attribute.   A  cell can have a VM command attached to it, to be
              executed when it plays. If the program attribute  is  set,  then
              this  cell  will  be a point that the user can skip to using the
              prev/next buttons on their DVD player  remote.  If  the  chapter
              attribute  is  set  (implies  program is set as well), then this
              cell is also a chapter point.

       <button [name="buttonname"]> commands; </button>
              Specifies the commands to be executed when the user selects  the
              button  with  the  specified  name.  You define button names and
              placements with spumux.


       The language is quite simple and roughly looks like C.

       · Statements are terminated with a semicolon.

       · Statements can span multiple lines.

       · Multiple statements can appear on one line.

       · Whitespace (space,  tab,  newlines)  are  not  important,  except  to
         separate keywords and identifiers.

       · If you want to insert comments, use XML comments <!-- like this -->

       The  DVD virtual machine processes 16 bit values.  It supports up to 16
       general purpose registers; however dvdauthor reserves  3  for  internal
       use.   Thus register 0-12 are avaialable for use and are referred to as
       g0 through g12.

       There are also 24 system registers, which can  be  referred  to  as  s0
       through s23.  Not all of these can be set.  Many of these have mnemonic

       audio (s1, rw)
              Denotes the audio stream, ranging from 0-7.

       subtitle (s2, rw)
              The subtitle track, ranging from 0-31.  If you want the subtitle
              to  always  be  displayed,  then  you should add 64 (i.e. choose
              64-95).  Simply selecting the track (0-31) means that  only  the
              forced  subtitles  will be displayed, whereas enabling the track
              (64-95) means that all the subtitles will  be  displayed.   This
              allows  you  to  have forced subtitles only for the parts of the
              movie where the actors are speaking a foreign  (to  the  viewer)
              language,  but  still  have  normal  subtitles  for  the hearing
              impaired.  The hearing impaired viewers would enable  the  track
              (64-95)  while  the  other  viewers  would just select the track
              (0-31) they would be able to share the track.

       angle (s3, rw)
              Selects the angle (currently untested).

       button (s8, rw)
              Denotes the currently highlighted button.  Note that  the  value
              is  multiplied  by 1024, so the first button is 1024, the second
              is 2048, etc.

       Expressions follow typical  C  syntax  except  that  booleans  are  not
       convertible to integers and vice versa.  Operators and comparisons are:

       ==, !=, >=, >, <=, <, &&, ||, !, eq, ne, ge, gt, le, lt, and, or,  xor,
       not, +, -, *, /, %, &, |, ^

       Since  the  code  is  encapsulated  in  XML,  the parser will catch any
       unescaped < characters (i.e. not written as  "&lt;"),  thus  alphabetic
       mnemonics   have   been  provided  for  all  comparison  operators  for

       There is also a numerical function:

              Computes a psuedo-random number,  between  1  and  the  supplied
              number, inclusively.

       Blocks  are either a single statement (terminated by a semicolon), or a
       group of statements wrapped in curly braces.  For example:


           jump vmgm menu 3;

       The statements supported are fairly simple at the moment.

              Sets a variable equal to the result of an equation.


       if (EXPRESSION) BLOCK; else BLOCK;
              Calculates the expression; if true, then it executes  the  block
              of code.

       jump TARGET;

       call TARGET [resume CELL];

              Jumps to a particular title or menu, or calls a particular menu,
              or returns to the calling title.  You can only  execute  a  call
              from  a  title  to  a  menu;  all  other forms are illegal.  The
              purpose of using call instead of jump  (besides  the  fact  that
              they  support  a mutually exclusive list of targets) is to allow
              the menu to return to the point in  the  title  where  the  call
              originated  using  resume.   You can manually specify the return
              cell by using the resume keyword, however if you do not  specify
              one and you use the command in a post instruction block, then it
              will presume cell 1.

       The following are  possible  targets  (note  that  menus  do  not  have

       [vmgm | titleset X] menu

       [vmgm | titleset X] menu Y

       [vmgm | titleset X] menu entry Z
              Targets  either  the  default menu, a menu number Y, or the menu
              denoted as the entry for Z.  The menu is in either the  VMGM  or
              titleset  domain.   If  you wish to target a menu in the current
              domain then you can omit the domain moniker.

       [titleset X] title Y [chapter Z]
              Targets a title, or a chapter in a title.  Numbering  starts  at
              1.   All  of  the  titles on the disc are accessible in the VMGM
              domain, or you can access them by titleset instead.

       chapter Z
              Targets a chapter in the current title.

       program Z

       cell Z Targets a program or cell in the current PGC.  You can use  this
              to create looping menus: jump cell 1;

       cell top

       next cell

       prev cell

       program top

       next program

       prev program

       pgc top

       next pgc

       prev pgc

       up pgc

       pgc tail
              (Jump  only)  performs  relative transfers of control within the
              current menu/title.  "cell/program/pgc top"  goes  back  to  the
              start    of    the    current    cell/program/PGC;    "next/prev
              cell/program/pgc" goes to the next or previous cell/program/PGC;
              "up  pgc"  goes  to  the  "up"  PGC  (not  currently settable in
              dvdauthor); and "pgc tail" goes to the <post>  sequence  in  the
              current    PGC.     <>   MarcLeeman2003Marc
              LeemanFri Dec 30 19:47:26 CET 2005

                                 18 March 2010