DVDAUTHOR(1)                  DVDAuthor Man Pages                 DVDAUTHOR(1)



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 (safely)
              deleted (only items that look like part of a DVD-Video structure
              are removed).

       -x xml-control-file
              Specifies the control file describing the output structure to
              create.

       Note that the remaining command-line options are deprecated. Use the
       XML control file instead.

       -j

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

       -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"] [format="ntsc|pal"] [provider="provider"]>
          <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"] [format="ntsc|pal"] [provider="provider"]>
              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.

       o Statements are terminated with a semicolon.

       o Statements can span multiple lines.

       o Multiple statements can appear on one line.

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

       o 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 available 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 pseudo-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:

       o
         g3 = s7;

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

       pgc Z  Targets a PGC in the current VMGM or titleset.

       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 Leeman

                               31 December 2016                   DVDAUTHOR(1)