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

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

dvdauthor [ -o output-dir ] [ -j | --jumppad ] [ -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 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 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.

-o output-dir

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

-j

--jumppad

foo

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

foo

-e entry(s)

--entry=entry(s)

foo

-p palette-file

--palette=palette-file

foo

-i commandlist

--instructions=commandlist

foo

-c chapterpts

--chapters=chapterpts

foo

-f mpeg-file

--file=mpeg-file

mpeg-file

foo

-b buttondef

--button=buttondef

foo

Here is the basic structure of the configuration file:

<dvdauthor [dest="output-dir"] [jumppad="1|on|yes"] >
   <vmgm>
      <menus [lang="language-code"] >
         <video [format="ntsc|pal"] [aspect="4:3|16:9"]
                [resolution="XxY"] [caption="field1|field2"]
                [widescreen="nopanscan|noletterbox"] />
         <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"]>

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

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.

<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

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

EXPRESSIONS

BLOCKS

STATEMENTS