Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DVDAUTHOR(1)		      DVDAuthor	Man Pages		  DVDAUTHOR(1)

       dvdauthor - assembles multiple mpeg program streams into	a suitable DVD

       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.  Conceptu-
       ally, a menu contains buttons which can be assigned  actions  and  pro-
       vides  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 ti-
       tleset 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	title-
       sets.  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  ac-
       cess 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	 exam-
       ple,  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 con-
       trolling	dvdauthor with command line arguments, then each step will oc-
       cur  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	multi-
       plexed  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 en-
       sure 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

       Note that the remaining command-line options are	 deprecated.  Use  the
       XML control file	instead.


	      Enables  the creation of jumppads, which allow greater flexibil-
	      ity in choosing jump/call	destinations.


	      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

	      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,	nopan-
	      scan, noletterbox, crop.	Default	is 4:3,	720xfull

       -a 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  Eng-
	      lish  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,

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

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

	      Specifies	where to get the subpicture palette. Settable per  ti-
	      tle  and	per  menu. If the filename ends	in .rgb	(case insensi-
	      tive) then it is assumed to be RGB, otherwise it is YUV. Entries
	      should  be  6  hexadecimal  digits.  FILE	 defaults to xste-pal-

       -c 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	trans-
	      posing  that  occurs within dvdauthor). The chapter markers ONLY
	      apply to the next	file listed. Defaults to 0.

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

	      creates a	button of the specified	size. See LANGUAGE DESCRIPTION
	      for a description	of commandlist.

       -i [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"]>
	     <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"
		       id="streamid" />
		   [<stream ...	/>]
		[<subpicture ... />]
		<pgc [entry="title"] [palette="yuvfile|rgbfile"]
		      [<stream ... />]
		   <pre> commands; </pre>
		   <vob	file="file.mpg"	[chapters="chapter-list"]
			<cell [start="timestamp"] [end="timestamp"]
			   [chapter="1|on|yes" | program="1|on|yes"] [pause="seconds|inf"]>
		   [<vob ... />]
		   <button [name="buttonname"]>	commands; </button>
		   [<button ...	/>]
		   <post> commands; </post>
		[<pgc ... />]
	     [<menus ... />]
	     <menus [lang="language-code"]>
		[<video	... />]
		[<audio	... />]
		<pgc [entry="entries"]
		     [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
		[<pgc ... />]
	     [<menus ... />]
		[<video	... />]
		[<audio	... />]
		<pgc [entry="notitle"] [palette="yuvfile|rgbfile"] [pause="seconds|inf"]>
		[<pgc ... />]
	  [<titleset ... />]

       A breakdown of the control file:

       <dvdauthor     [dest="output-dir"]     [jumppad="1|on|yes"    |	  all-
       gprm="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. Con-
	      tains up to one <vmgm> tag and any number	of <titleset>'s.


	      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>

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

	      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"] [cap-
       tion="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 sup-
	      ports 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="sur-
       round"]	 [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  automati-
	      cally  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|nor-
       rector"]	/>
	      Manually configures a subpicture/subtitle	for this  pgcgroup  or
	      PGC.  At the pgcgroup level, list	once for each language.	Occur-
	      rences 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="sec-
	      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

	      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  ti-
	      tleset 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 an-
	      other 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 pal-
	      ette,  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"	| pro-
       gram="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 at-
	      tribute.	A cell can have	a VM command attached to it, to	be ex-
	      ecuted 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 at-
	      tribute 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.

       o Statements are	terminated with	a semicolon.

       o Statements can	span multiple lines.

       o Multiple statements can appear	on one line.

       o Whitespace  (space, tab, newlines) are	not important, except to sepa-
	 rate keywords and identifiers.

       o 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

       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 im-
	      paired.  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  con-
       vertible	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  un-
       escaped < characters (i.e. not written as "&lt;"), thus alphabetic mne-
       monics 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:

	      Computes a pseudo-random number, between 1 and the supplied num-
	      ber, 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.

	      Sets a variable equal to the result of an	equation.


       if (EXPRESSION) BLOCK; else BLOCK;
	      Calculates  the  expression; if true, then it executes the block
	      of code.

       jump TARGET;

       call TARGET [resume CELL];

	      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  pur-
	      pose  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	origi-
	      nated 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 chap-

       [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 do-
	      main, 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/pro-
	      gram/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.
       <> MarcLeeman2003Marc Leeman

			       31 December 2016			  DVDAUTHOR(1)


Want to link to this manual page? Use this URL:

home | help