Provided by: dvdauthor_0.7.2-3_amd64 
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.
• 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
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 "<"), 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:
•
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.
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
05 November 2024 DVDAUTHOR(1)