Table of Contents
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 | -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 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
- -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 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
- 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 configuration file:
<dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"]>
<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"] />
[<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"
| 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.
- <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|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"] />
- 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.
- <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"] />
- 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.
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 avaialable 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 pseodonyms.
- audio (s1, rw)
- Denotes the audio channel, 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,
thus alphabetic mnemonics have been provided for all comparison operators
for consistency.
There is also a numerical function:
- random(EXPRESSION)
- Computes a psuedo-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:
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:
- [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.
- [vmgm | 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.
- chapter Z
- program Z
- cell Z
- Targets
a chapter, program, or cell in the current title or menu (note that menus
do not have chapters). You can use this to create looping menus: jump cell
1;
Table of Contents