Provided by: dvdauthor_0.6.14-1build2_i386 bug

NAME

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

SYNOPSIS

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

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

DVD BACKGROUND

       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 frusterating 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 DESCRIPTION

       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 configuration
       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.

COMMAND LINE DESCRIPTION

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

       -j

       --jumppad
              foo

       -g

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

       --video=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

       --audio=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

       --subpictures=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
              tracks.

       -e entry(s)

       --entry=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

       --palette=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-
              palette.dat

       -c chapterpts

       --chapters=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

       --file=mpeg-file

       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

       --button=X1xY1-X2xY2,commandlist
              creates a button of the specified size. See LANGUAGE DESCRIPTION
              for a description of commandlist.

       -i [pre|post]=commandlist

       --instructions=[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.

XML DESCRIPTION

       Here is the basic structure of the configuration file:

       <dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"]>
          <vmgm>
             [<fpc>commands;</fpc>]
             <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"] />
                [<audio ... />]
                <subpicture lang="language" />
                <pgc [entry="title"] [palette="yuvfile|rgbfile"]
                     [pause="seconds|inf"]>
                   <pre> commands; </pre>
                   <vob file="file.mpg" [chapters="chapter-list"]
                        [pause="seconds|inf"] />
                   [<vob ... />]
                   <button [name="buttonname"]> commands; </button>
                   [<button ... />]
                   <post> commands; </post>
                </pgc>
                [<pgc ... />]
             </menus>
          </vmgm>
          <titleset>
             <menus>
                [<video ... />]
                [<audio ... />]
                <pgc [entry="entries"]
                     [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                   [...]
                </pgc>
                [<pgc ... />]
             </menus>
             <titles>
                [<video ... />]
                [<audio ... />]
                <pgc [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                   [...]
                </pgc>
                [<pgc ... />]
             </titles>
          </titleset>
          [<titleset ... />]
       </dvdauthor>

       A breakdown of the config file:

       <dvdauthor       [dest="output-dir"]       [jumppad="1|on|yes"        |
       allgprm="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.

       <vmgm>

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

       <menus [lang="language-code"] >

       <titles>
              Marks  the  list  of  menus  or titles for this VMGM menu set or
              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"] />
              Manually configures an audio channel for  this  pgcgroup.   List
              once   for   each   channel.    Most   parameters  are  inferred
              automatically from the source VOBs except  for  PCM  parameters.
              However,  language  must be manually specified.  Note that it is
              possible to just list the language attribute and  let  dvdauthor
              fill in the rest.

       <subpicture lang="language" />
              foo

       <pgc            [entry="entries"]           [palette="yuvfile|rgbfile"]
       [pause="seconds|inf"]>
              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 below.

              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
              specified.

              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"] />
              foo

       <cell  [start="timestamp"]  [end="timestamp"]   [chapter="1|on|yes"   |
       program="1|on|yes"] [pause="seconds|inf"] />
              foo

       <button [name="buttonname"]> commands; </button>
              foo

LANGUAGE DESCRIPTION

       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.

   VARIABLES
       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
       pseodonyms.

       audio (s1, rw)
              Denotes the audio channel, 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
       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, thus alphabetic mnemonics  have  been  provided
       for all comparison operators for consistency.

       There is also a numerical function:

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

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

       ·
         g3=s7;

       ·
         {
           audio=1;
           subtitle=65;
           jump vmgm menu 3;
         }

   STATEMENTS
       The statements supported are fairly simple at the moment.

       VARIABLE=EXPRESSION;
              Sets a variable equal to the result of an equation.

       if (EXPRESSION) BLOCK;

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

       jump TARGET;

       call TARGET [resume CELL];

       resume;
              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:

              [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.

              [vmgm | 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

              program Z

              cell Z Targets a chapter, program, or cell in the current  title
                     or  menu (note that menus do not have chapters).  You can
                     use this to create looping menus: jump cell 1;

                                13 January 2007                   DVDAUTHOR(1)