Intermediate Form

Front Page Posts

dvd.py Menu File Documentation

All of the commands given in the documentation are either python functions or python class constructors. (The distinction is not important to the user, as the classes automatically add themselves to the approprate data structures.)

If you're not familiar with python, the following is a simple guide to python syntax that should get you familar enough to write a menu file. If you are familar with python, realize that the menu file can contain arbitrary python code, as long as it calls the approprate functions. The order of function calls at runtime is what matters, not when the calls appear in the python code.

A python string is given in quotes. Inside it, backslashes are used to escape the following character, or to introduce special characters such as newline ( ). For example, one can write:

   "/home/tom/dvd/chapter1.mpg"
   "How to \"quote\" quotes.mpg"

Numbers are simply given as a sequence of digits. Be sure to remove leading zeros. Lists are given as a comma-separated list of items given in betweed square brackets ('[' and ']'). A tuple is a comma-separated list of items given in parenthesis ( '(' and ')'. For example:

   [ 1, 2, 3, 4, 5 ]
   (1, 2, 3)

In this documentation, functions are given by specifying a fuction name, followed by a list of parameters. A parameter may be followed by an equal sign, which gives the default value for that parameter. If a parameter begins with two stars, it is a bin for keyword arguments, which are passed into another function. An example function is:

my_function(a, b=100, c=42, **kwargs)

Arguments without defaults must be given in every call to the function. Arguments with defaults may be given in order, or they mey be specified as a keyword = value. Unknown keywords are placed in kwargs, which may then be passed to another function.

All of the following pairs of function calls are equivalent.

  my_function(1) == my_function(1, 100, 42)
  my_function(1, 2) == my_function(1, 2, 42)
  my_function(1, b=2) == my_function(1, 2, 42)
  my_function(1, c=3) == my_function(1, 100, 3)
  my_function(1, 2, 3) == my_function(1, 2, 3)
  my_function(1, d=100) == my_function(1, 100, 42, d=100)

There are two concepts that are important in understanding how menus are created. The first is that of the drawing cursor, and the second is the default action.

Menus are drawn on a 704 x 480 grid, with (0, 0) being the upper-left corner of the picture. The drawing cursor consists of three values. The first is a y coordinate, the second is an x coordinate, and the third is the x coordinate after a carriage return (crx). The x coordinate is used for the current thing being drawn, while crx is the value that x is reset to after a carriage return occurs, when a label and text is drawn. It's used to allow for lines of text consisting of multiple buttons.

The default action is used by the label command when it has no action specified. It is set by the title command, and is reset by the label or newmenu commands, even if the commands have an explicitly specified actions.

The default command allows title and label commands to be specified in pairs, without requiring the explicit specification of actions.

background

background(self, file)

This loads in an image file, scales it to 704 x 480, and uses it as a background for the menu.

file A string containing the filename of an image.

chapter, chapters

chapter(chapters)
chapters(chapters)

Sets the default chapters list that is used by the title command, when it is called with the chapters parameter set to None. Used when multiple titles have chapter breaks in the same place, as in a TV show with a title sequence of a fixed length.

chapters A list of chapters strings, or a single chapter string.

color, colors

color(normal=None, highlight=None, selected=None)
colors(normal=None, highlight=None, selected=None)

Allows the user to change the color of text that appears in the menus. The color depends on the context that something is used in. Normal is the color of text, or a button on the menu that does not have the focus. Higlight is the color of a button that the user has given focus to, but not selected. Selected is the color of a button that has been selected (by pushing enter), but for which the action assigned to that button has not been completed.

All colors are given as tuples of (red, green, blue), where each of the three values may range between 0 and 255. For example, white would be (255, 255, 255), yellow would be (255, 255, 0), and red would be (255, 0, 0). (These are the defaults for normal, highlight and selected, respectively.)

One should not use black as a color, as it is used as the chroma-key.

`normal`	The color of normal text. If None, keep the current value.
`highlight`	The color of higlighted text. If None, keep the current value.
`selected`	The color of selected text. If None, keep the current value.

font

font(file, size, skip=0)

Sets a new default font for text and labels in the menus. This must appear before any call to text or label.

`file`	A string containing a full path to a truetype font file.
`size`	The size, in pixels, of the font.
`skip`	An additional amount of spacing between things written in this font.

label

label(self, text, action=None, **kwargs)

This defines a textual button in the dvd menu, which when selected invokes the specified action. The action must be given in dvdauthor's command language. Some examples of useful actions are:

jump title 1; - Jumps to the start of the first title. Since we're in the vmgm (menu) domain when running this command, we can jump to the titles by number, ignoring the existence of titlesets.

jump title 2 chapter 3; - Jumps to the third chapter of the second title. Like titles, chapters are numbered starting from 1.

jump menu 2; - Jumps to the numbered menu. The first menu is numbered 1, additional menus added with the newmenu command are numbered starting with 2.

`text`	The text of the button, passed to text.
`action`	The action, or None to take the default action.
`kwargs`	Additional keyword arguments are passed to text when the text is drawn. This allows halign and valign to be used.

moveto

moveto(self, x, y)

Moves the drawing cursor to the specified x and y coordinates.

newmenu

newmenu(self)

Introduces a new menu. This command is used as a separator between menus, so one shouldn't place a newmenu command before the items in the first menu. The newmenu command clears out the background and contents of the menus, so a new background should be introduced if desired. (Otherwise, the default black background will be used.) It does not reset the count of titlesets, which are added to the DVD as a whole, not to any individual menu.

rmoveto

rmoveto(self, x, y)

Moves the drawing cursor to new x and y coordinates. The new location of the cursor is the current location with the arguments added to x and y, respectively.

text

text(self, text, cr=True, halign='left', valign='top')

Draws the text to the menu, using the current font and colors.

The halign and valign arguments specify the position of the drawing cursor in the text. To center the text on the screen, one can use a command like:

    moveto(704 / 2, 480 / 2)
    text("Centered!", halign="center", valign="center")

If cr is False, the cursor is moved to the right by the horizontal size of the drawn text. If cr is True, the x position of the cursor is set to the saved crx position, and the cursor is moved down by the height of the text.

`text`	The text to draw.
`cr`	Should a carriage return occur.
`halign`	One of "left", "center", "right".
`valign`	One of "top", "left", "bottom".

title

title(self, file, pause=0, chapters=None, pre=None, post='call vmgm menu 1;')

This introduces a new titleset to the dvd, and inserts into it one or more mpeg files. The titlesets on the DVD are numbered in the order in which title commands execute in the menu file, starting from 1. The movies are always title 1 in the titleset, but they can also be accesed as a numbered title from the VMGM domain (that is, the menus).

This command also sets the default action to start playing the newly added title.

`file`	A list of mpeg filenames, which comprise the contents of the title. If a single string is given instead, it is automatically turned into a list containing the string. The files are added in the order in which they appear in the list.
`pause`	How long to pause after each movie file plays. This is a list of values, that must be of the same length as the list of files. If a single value is given, it is turned into a list of the appropriate length. This should be a lenght of time in seconds, or the string "inf" to pause forever.
`chapters`	A list of strings giving the times of chapter breaks in each movie file. Once again, it must be the same length as the list of movie files, and is automatically turned into a list of the appropriate length if it is not. Each string is a comma separated list of chapter breaks, which may be either an integer number of seconds or in MM:SS (minutes and seconds) format. If None, takes the default set by the chapters command.
`pre`	A string containing a command in the dvdauthor command language specifiying something to do before playing the title. I've yet to use this.
`post`	A string containing a command in the dvdauthor command language specifiying what to do after all movies have finished playing. The default command jumps to the first menu on the DVD.