.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\"
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng .
.TH "DVDAUTHOR" "1" "31 December 2016" "" "DVDAuthor Man Pages"
.SH NAME
dvdauthor \- assembles multiple mpeg program streams into a suitable DVD filesystem
.SH SYNOPSIS
\fBdvdauthor\fR [ \fB-o \fIoutput-dir\fB\fR ] \fB-x \fIxml-control-file\fB\fR
\fBdvdauthor\fR [ \fB-o \fIoutput-dir\fB\fR ] [ \fB-j\fR | \fB--jumppad\fR | \fB-g\fR | \fB--allgprm\fR ] [ \fB-T\fR | \fB--toc\fR ] [ \fB\fImenu or title options\fB\fR ]
.SH "DVD BACKGROUND"
.PP
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.
.PP
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.
.PP
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.
.SH "DVDAUTHOR DESCRIPTION"
.PP
\fBdvdauthor\fR 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 \fBdvdauthor\fR 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.
.PP
The VOBs passed to \fBdvdauthor\fR must have DVD
NAV (VOBU) packets multiplexed in at the correct locations. Many
tools can do this, including \fBmplex\fR from mjpegtools
1.6.0 or later. \fBdvdauthor\fR will then fill these
packets in with the correct data. Special care has been taken to
ensure \fBdvdauthor\fR is fifo compliant; that is every
source VOB can be the output of another program (such as
\fBmplex\fR). This can make execution faster on many
systems by avoiding extra filesystem accesses.
.SH "COMMAND LINE DESCRIPTION"
.TP
\fB-o \fIoutput-dir\fB\fR
.TP
\fB-O \fIoutput-dir\fB\fR
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).
.TP
\fB-x \fIxml-control-file\fB\fR
Specifies the control file describing the output structure to create.
.PP
Note that the remaining command-line options are \fBdeprecated\fR\&. Use the
XML control file instead.
.TP
\fB-j\fR
.TP
\fB--jumppad\fR
Enables the creation of jumppads, which allow greater flexibility in choosing jump/call destinations.
.TP
\fB-g\fR
.TP
\fB--allgprm\fR
Enable the use of all 16 general purpose registers. Prohibits the use of jumppad and some complex expressions that require temporary registers.
.TP
\fB-T\fR
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.
.TP
\fB-m\fR
Creates a menu.
.TP
\fB-t\fR
Creates a title.
.TP
\fB-v \fIvideo-opts\fB\fR
.TP
\fB--video=\fIvideo-opts\fB\fR
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
.TP
\fB-a \fIaudio-opts\fB\fR
.TP
\fB--audio=\fIaudio-opts\fB\fR
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.
.TP
\fB-s \fIsubpicture-opts\fB\fR
.TP
\fB--subpictures=\fIsubpicture-opts\fB\fR
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.
.TP
\fB-e \fIentry(s)\fB\fR
.TP
\fB--entry=\fIentry(s)\fB\fR
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
.TP
\fB-p \fIpalette-file\fB\fR
.TP
\fB--palette=\fIpalette-file\fB\fR
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. \fIFILE\fR defaults to
xste-palette.dat
.TP
\fB-c \fIchapterpts\fB\fR
.TP
\fB--chapters=\fIchapterpts\fB\fR
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.
.TP
\fB-f \fImpeg-file\fB\fR
.TP
\fB--file=\fImpeg-file\fB\fR
.TP
\fB\fImpeg-file\fB\fR
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)
.TP
\fB-b \fIbuttondef\fB\fR
.TP
\fB--button=\fIX1xY1-X2xY2,commandlist\fB\fR
creates a button of the specified size. See
LANGUAGE DESCRIPTION for a description of \fIcommandlist\fR\&.
.TP
\fB-i \fI[pre|post]=commandlist\fB\fR
.TP
\fB--instructions=\fI[pre|post]=commandlist\fB\fR
Executes the \fIcommandlist\fR
instructions either before or at the end of the menu/title. See
LANGUAGE DESCRIPTION for the format of \fIcommandlist.\fR
.SH "XML DESCRIPTION"
.PP
Here is the basic structure of the control file:
.nf
[\fIcommands;\fR]
[]
[]
[]
[]
\fIcommands;\fR
\fIcommands;\fR
[]
[]
\fIcommands;\fR
[]
[]
[]
[]
[...]
[]
[]
[]
[]
[...]
[]
[]
.fi
.PP
A breakdown of the control file:
.TP
\fB\fR
Initiates dvdauthor. dest denotes the directory where \fBdvdauthor\fR will write the files. This is overridden by the -o option. Contains up to one tag and any number of \&'s.
.TP
\fB\fR
.TP
\fB\fR
Constructs of a VMGM level menu set or a title set.
Contains zero or more tags and if a
titleset, up to one tag.
.TP
\fB\fR
Marks a list of menus with a common language for this VMGM menu
set or titleset, called in \fBdvdauthor\fR terminology a
"pgcgroup." Contains up to one