DVDAUTHOR(1)

📦
version 0.7.2 · 9 versions
, in alpine 3.24, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🌸 dvdauthor — DVDAuthor Man Pages 🌸

okay bestie, sit DOWN because we're about to talk about dvdauthor, and this thing is a whole icon. it assembles multiple mpeg program streams into a suitable DVD filesystem. yes literally. that's the gig. 💅

✨ 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 🦋

okay so high level? a DVD is just a collection of menus and titles. that's it. that's the whole vibe.

conceptually, a menu contains buttons which can be assigned actions, and it provides a list of choices to the end user. a title contains the main content of the DVD. BUT — and this is the plot twist — in reality many of the features available in menus (including buttons, pausing, and looping) are also available in titles. so the line between them is lowkey fake. 🙈

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 instead. it's a collection of menus (no titles) that can access the menus and titles of all the titlesets. she's the social butterfly of the disc, fr fr. 🦋

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. like. many. 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. iconic planning behaviour honestly. 👑

💖 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. multitasking queen. ✨

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. efficiency slay. 🔥

🌈 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). note the word "safely" in there, bestie — she's not coming for your random files.
  • -x xml-control-file — specifies the control file describing the output structure to create. this is the main character of the whole operation tbh. 👑
heads up: note that the remaining command-line options are deprecated. use the XML control file instead. i'm not saying it, the manpage is saying it. 🫶
  • -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. so like, you can't have both. pick your fighter. 💅
  • -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. the options are: 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. the options are: 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 (,). the options are 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). pipes and shell commands, we love a flexible queen. 🫶
  • -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 🎀

okay bestie, deep breath, this is the part where dvdauthor actually learns what you want. you hand it an XML control file and it reads it like a text from you at 2am — very important, must be followed exactly. here's the basic structure:

<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>

💅 the breakdown, tag by tag 💅

<dvdauthor [dest="output-dir"] [jumppad="1|on|yes" | allgprm="1|on|yes"] [format="ntsc|pal"] [provider="provider"]>

This is the one that kicks everything off — the main character tag, if you will. dest says which directory dvdauthor is gonna write the files into. heads up: the -o option overrides this. You get up to one <vmgm> tag in here and any number of <titleset>'s. go wild.

<vmgm>

<titleset>

These two are constructed out of either a VMGM level menu set or a title set. They contain zero or more <menus> tags, and — if it's a titleset — up to one <titles> tag. 🦋

This marks a list of menus that all share a common language for this VMGM menu set or titleset. In dvdauthor terminology that's called a "pgcgroup." Inside you get up to one <video> tag, up to one <audio> tag, up to one <subpicture> tag, and any number of <pgc> tags. no cap.

<titles>

This one marks the list of titles for this titleset — also a "pgcgroup," same terminology, keep up bestie. Inside: up to one <video> tag, up to eight <audio> tags, up to 32 <subpicture> tags, and any number of <pgc> tags. yes, 32. iconic.

<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 you don't set any of these, they get inferred from the source stream — the lazy girl's dream. but wait: the DVD format only specifically supports 720x480, 704x480, 352x480, and 352x240 resolutions for NTSC, and 720x576, 704x576, 352x576, and 352x288 resolutions for PAL. DVD author will still accept a wider range of inputs though, and it rounds 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 one audio stream for this pgcgroup. List it once for each stream — one tag per stream, that's the rule. Most parameters get inferred automatically from the source VOBs, except for PCM parameters. But language and content must be manually specified. Fun fact though: it's totally possible to just list the language and content attributes and let dvdauthor fill in the rest. slay.

<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 it once for each language. When they show up at the PGC level they don't have lang or content attributes — they just inherit those from the matching <subpicture> tag at the pgcgroup level. generational wealth but for attributes.

<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. You can set this per-PGC, or pgcgroup-wide. your call, bestie.

<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 its use has been retained here. PGC's can have commands that get executed before they start playing or after they finish — check out the <pre> and <post> tags below for that. 👑

If the PGC is a menu, you can specify one or more entries for it. What that means: if you press the corresponding button on your DVD remote, it goes 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. Want more than one? Separate them with a space or a comma. note that the 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's assumed to be a title unless entry="notitle" is specified.

Okay this next bit is important so listen up: 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 gets automatically passed to dvdauthor. But if you use another subtitler, or you just want 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 you 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. Want the video to pause forever? use inf. infinite pause. main character energy. ✨

<pre> commands; </pre>

<post> commands; </post>

Sets the commands to execute before or after a PGC plays. You can use it to loop the current video (by having a <post> jump ... </post> sequence), or to conditionally skip certain chapters if a flag has been set. conditional skipping is lowkey so powerful.

<fpc> commands; </fpc>

Sets the commands to execute when the disk is first put in the player. FPC = First Program Chain, iykyk. You can use it to jump to a particular menu or initialize registers on startup. If you don't specify one, an implicit one gets created that jumps to the first menu found — or, if there is no menu, it jumps 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 optional pause at the end. simple. clean. 🍓

<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. heads up: if this is 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. And if the chapter attribute is set (which implies program is set as well), then this cell is also a chapter point. two for one 💅

<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. that's the whole thing, she's simple but she's essential. 🦋

✨ LANGUAGE DESCRIPTION ✨

okay bestie, the mini-language you use to write DVD navigation code is genuinely so simple, and it roughly looks like C. that's it. that's the whole vibe. 🎀

here's the ground rules:

  • 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 🌸

so 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. 🤯 (yes bestie, one track, two audiences, it's giving efficiency)

🦋 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. no cap.

💫 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 &lt;), 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:

  • a single statement, doing its little solo thing:
g3 = s7;
  • or a whole squad of statements in braces:
{
  audio = 1;
  subtitle = 65;
  jump vmgm menu 3;
}

👑 STATEMENTS 👑

The statements supported are fairly simple at the moment. (at the moment. she's humble.)

  • 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;

so about that jump / call / resume trio, because this is the part people get wrong: they jump to a particular title or menu, or call a particular menu, or return 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.

and here's how those relative ones actually behave, because the names are doing a lot of heavy lifting: "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. (iykyk, this one bites people)

💀 LIMITATIONS 💀

The following limits are imposed by the DVD-Video spec. so like, not dvdauthor's fault, she's just working with what the disc format gave her. 🙈

  • 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.
⭐ and the author credit on this page literally reads <marc.leeman@gmail.com> MarcLeeman2003Marc Leeman — legendary, slightly haunted, we respect it. 💜

okay bestie that's the whole page!! this was DVDAUTHOR(1), last touched 31 December 2016 — go forth and author some DVDs, you absolute main character. 🫶✨💅

📦 where this page comes from