dvdauthor - assembles multiple mpeg program streams into a
suitable DVD filesystem
dvdauthor [ -o output-dir ] -x
xml-control-file
dvdauthor [ -o output-dir ] [
-j | --jumppad | -g | --allgprm ] [ -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 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 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.
- -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.
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.
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 -->
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 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 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;
}
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.
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.
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