SearchWiki:

Overview

PmWiki

Side Bar

Recent Changes Printable View Page History Edit Page

The DVDAuthor XML file format can be used to control DVDAuthor's behavior, allowing a complicated DVD file structure to be built in a single invocation of DVDAuthor.

The following documentation takes the dvdauthor manual page as a starting point.

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>]
             [<titlemap titleset="num" title="num"/>]
             [<titlemap ... />]
             <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="root|subtitle|audio|angle|ptt[,...]"]
                     [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. Using the allgprm attribute enables the use of all 16 general purpose registers. Prohibits the use of jumppad and some complex expressions that require temporary registers.

 <vmgm>
 <titleset>

The following constructs apply to a VMGM level menu set or a title set. Either a <vmgm> or a <titleset> may 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 DVDAuthor will accept a wider range of inputs and round up to the nearest size. Only one video track is allowed within a VOB file.

 <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. Up to 8 audio tracks may be multiplexed within a VOB file.

 <subpicture 
  lang="language" />

Not yet documented in the dvdauthor manual page.

Up to 32 subtitle tracks may be multiplexed within VOB files, numbered positionally from 0 to 31. However, the multiplexing process does not tag subtitle tracks with the language of the subtitles.

The <subpicture /> tag satisfies this need, enabling the DVD player to know what language corresponds with what subtitle track. The first <subpicture /> element corresponds to subtitle track 0, the next to track 1, and so on.

Valid values of the "lang" attribute are the two letter language codes recognized by DVD players, as defined in ISO 639. These codes are listed in the dvdauthor example web pages.

 <pgc 
  [entry="root|subtitle|audio|angle|ptt[,...]"]
  [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. Multiple entries are separated by a comma in the value of the entry attribute. See dvdauthor-users #10693415 for a discussion (the patch mentioned has been implemented in dvdauthor-0.6.12-alpha-2992.)

Having an entry 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.

The commands to be executed must follow the syntax of the Virtual Machine Language.

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

The commands to be executed must follow the syntax of the Virtual Machine Language.

This is likely the data structure exploited by commercial DVDs which show commercial advertisements when first played.

 <titlemap titleset="num" title="num"/>

Not yet documented in the dvdauthor manual page. This is seen in the output of dvdunauthor in the 0.6.12 alpha release 2992. Defines the global title numbers that can be referenced from the VMGM without needing to specify the titlesets (http://dvd.sourceforge.net/dvdinfo/ifo_vmg.html#tt).

 <vob 
  file="file.mpg" 
  [chapters="chapter-list"] 
  [pause="seconds|inf"] />

Not yet documented in the dvdauthor manual page. This is where you specify the actual MPEG file containing the menu or title.

Information found on the net, and empirical testing, shows that chapter-list is a list of time offsets that can be jumped to, usually with the "next" button. The times are given in HH:MM:SS.HU format, unnecessary components can be omitted. An example:

  chapters="0,0:33.50,3:45,1:07:45"

seems to give breakpoints at 33 1/2 seconds, 3 minutes 45 seconds, and 1 hour 7 minutes 45 seconds.

The pause attribute pauses at the end of the file for the given number of seconds, or literally typing "inf" gives you the infinite pause that should be used on menus.

  pause="5"
  pause="inf"

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

Not yet documented in the dvdauthor manual page. The timestamps have the form HH:MM:SS.SSS.

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

The commands to be executed must follow the syntax of the Virtual Machine Language.

Not yet documented in the dvdauthor manual page.

Actually, buttonname corresponds to the names of buttons in the Spumux xml control file. This way, "areas" of the subtitle are defined as buttons in the spumux control file, and tied into the menu via the name attribute as shown here.

Edit Page - Page History - Printable View - Recent Changes - WikiHelp - SearchWiki
Page last modified on August 05, 2008, at 04:36 AM