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
deleted.
- -j
- --jumppad
- Enables the creation of jumppads, which allow greater
flexibility in choosing jump/call desinations.
- -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"]>
<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"]>
- 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 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 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 psuedo-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.
- 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 LeemanFri Dec 30 19:47:26 CET
2005