Provided by: dvdauthor_0.7.0-1.2ubuntu1_amd64 bug

NAME

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

SYNOPSIS

       dvdauthor [ -o output-dir ] -x xml-control-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  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 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  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.

COMMAND LINE DESCRIPTION

       -o output-dir

       -O output-dir
              The destination directory to store the DVD-Video  file  structure  in.   If  -O  is
              specified, then any existing directory is deleted.

       -j

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

       -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 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 control 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"]
                       [content="normal|impaired|comments1|comments2"] />
                [<audio ... />]
                <subpicture [lang="language-code"]>
                   <stream mode="normal|widescreen|letterbox|panscan"
                       [content="normal|large|children|normal_cc|large_cc|children_cc|forced|director|large_director|children_director"]
                       id="streamid" />
                   [<stream ... />]
                </subpicture>
                [<subpicture ... />]
                <pgc [entry="title"] [palette="yuvfile|rgbfile"]
                     [pause="seconds|inf"]>
                   <subpicture>
                      [<stream ... />]
                   </subpicture>
                   <pre> commands; </pre>
                   <vob file="file.mpg" [chapters="chapter-list"]
                        [pause="seconds|inf"]>
                        <cell [start="timestamp"] [end="timestamp"]
                           [chapter="1|on|yes" | program="1|on|yes"] [pause="seconds|inf"]>
                           commands;
                        </cell>
                   </vob>
                   [<vob ... />]
                   <button [name="buttonname"]> commands; </button>
                   [<button ... />]
                   <post> commands; </post>
                </pgc>
                [<pgc ... />]
             </menus>
             [<menus ... />]
          </vmgm>
          <titleset>
             <menus [lang="language-code"]>
                [<video ... />]
                [<audio ... />]
                <pgc [entry="entries"]
                     [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                   [...]
                </pgc>
                [<pgc ... />]
             </menus>
             [<menus ... />]
             <titles>
                [<video ... />]
                [<audio ... />]
                <pgc [entry="notitle"] [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
                   [...]
                </pgc>
                [<pgc ... />]
             </titles>
          </titleset>
          [<titleset ... />]
       </dvdauthor>

       A breakdown of the control 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.  This  is overridden by 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 zero or more  <menus>
              tags and if a titleset, up to one <titles> tag.

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

       <titles>
              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"] [content="normal | large | children | normal_cc | large_cc |
       children_cc | forced | director | large_director | children_director"] />
              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"] [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.

              If  the  PGC  is  in  a  titleset,  then  it  is  assumed  to  be  a  title  unless
              entry="notitle" is specified.

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

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.

       • C-style /* ... */ comments are allowed. Or you can use XML comments <!-- like this -->

   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 mnemonic synonyms.

       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
       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  consistency.  Or  you  can put the code in a <![CDATA[ ... ]]>
       section.

       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.

   TARGETS
       The following are possible targets (note that menus do not have chapters):

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

       Chapters  are  numbered  from  1 in each title, while programs are numbered from 1 in each
       PGC. Thus, the latter can reset independently of the former when there is  more  than  one
       PGC in a title.

LIMITATIONS

       The following limits are imposed by the DVD-Video spec.

       There  can  be  no more than 99 titlesets, no more than 99 menus in the VMG or a titleset,
       and no more than 99 titles in a titleset.

       Each title may be made up of up to 999 PGCs. Each PGC may consist of up to  255  programs.
       The  <pre>  and  <post>  sections  of  a  PGC put together can contain no more than 128 VM
       instructions.

       Since there is only one VOB file (VIDEO_TS.VOB) in the VMG, the total amount of  video  in
       the  VMG  menus  must  fit  into  1073709056  bytes (524272 sectors of 2kiB each). In each
       titleset, all the menu video must fit in the first VOB (VTS_nn_0.VOB), so  is  limited  to
       the same amount.  <marc.leeman@gmail.com> MarcLeeman2003Marc LeemanFri Dec 30 19:47:26 CET
       2005

                                         23 October 2010                             DVDAUTHOR(1)