dvd-baker

NAME

dvd-recipe - Recipe file format for dvd-baker  

DESCRIPTION

dvd-baker uses a dvd-recipe file that describes the ingredients and format of a DVD.  

SYNTAX

A recipe file for dvd-baker is constructed in an XML-like fashion.  

CONCEPT

The recipe file is made up of blocks and tags.

The simplified block structure without start/end tags:

    header
    titles
     *  settings
         *% function
     *% title
         *% slideshow
              *% image
    menus
     *% menu
            buttons
             *% button

Where:
    * indicates an optional block/tag
    % indicates a repeatable block/tag

BLOCKS

    Depending on the block type, a block will contain other blocks and/or tags.
        [blockname/]
              block content
           [/blockname]

    Valid block names (in structure format):

    [dvd-recipe/]
          [header/]
             *% [depend/]
                  [/depend]
            [/header]
          [titles/]
             *  [settings/]
                   *% [function/]
                        [/function]
                   *% [effect/]
                        [/effect]
                   *  [leader/]
                        [/leader]
                   *  [trailer/]
                        [/trailer]
                  [/settings]
              % [title/]
                   *  [settings/]
                        [/settings]
                   *% [slideshow/]
                         *  [settings/]
                              [/settings]
                         *% [image/]
                              [/image]
                        [/slideshow]
                   *% [video/]
                        [/video]
                  [/title]
            [/titles]
          [menus/]
             *  [settings/]
                  [/settings]
              % [menu/]
                   *  [settings/]
                        [/settings]
                   *% [image/]
                        [/image]
                      [buttons/]
                          % [button/]
                              [/button]
                        [/buttons]
                  [/menu]
            [/menus]
      [/dvd-recipe]

TAGS

    A tag is a single line.

        [tagname] argument <argument1...argumentN>

    Valid tag names and their respective parent blocks:

    [header/]
          [version]
       *  [sourceType]
          [base]
       *  [fetch]
       *  [sessionId]
    [depend/]
          [name]
          [version]
          [command]
       *% [echo]
    [effect/]
          [name]
       *% [IFS]
       *% [image]
       *% [effect]
       *% [execute]
       *% [audio]
    [function/]
          [name]
       *% [command]
    [titles/]
       *% [duration]
    [title/]
          [id]
       *% [duration]
       *% [movie]
       *% [title]
    [slideshow/]
       *% [name]
       *% [duration]
       *% [image]
       *% [audio]
    [image/]
       *  [mimetype]
          [item]
       *  [duration]
       *  [subtitle]
    [video/]
       *  [mimetype]
          [item]
    [menus/]
       *  [duration]
    [menu/]
          [id]
       *  [name]
       *  [duration]
       *  [image]
       *  [parent]
    [button/]
          [name]
          [title] or [submenu]
       *  [image]

TAG DEFINITIONS

[#], [comment], blank lines

These are ignored and used for readability.

[audio] audiofile:track:effect1:params1:effect2:params2

Can be used in both slideshow and effect blocks, and follows dvd-slideshow format. It can be used to play sound for the following image, or if using duration='audio' on the following images, to play a sound track while those images are shown. For more information see dvd-slideshow(1)

[base]

The url or directory that describes the source location.

[command] command line with arguments

The actual command line to execute within a function or depend block. Multipe command statements can be used in which case the commands are amped () together and command lines returning false will require an OR'ed true: "|| true" for the command script to continue. Extra long command lines can be continued on the following line by suffixing a '', however, be aware that this affects the recipe line count when debugging, so multiple command statements are preferred. No parsing of these commands is done, and their progress is not shown on the progress meter. Refer to sample 1 for examples of usage.

[duration] time_in_seconds

Integer value whose meaning depends on the containing block type:

image

    Uses image duration of time_in_seconds rather than the local or global default.

menu

    Uses menu timeout of time_in_seconds rather than the local or global default.

menu-settings

    Sets the menu timeout for the current menu.

menus-settings

    Sets the global menu timeout for all following menus.

title-settings | slideshow-settings

    Sets the local default image duration for slideshow images in the remainder of that title. Image duration is then reset to global default.

titles-settings

    Sets the global default image duration for all following slideshow images.

[echo] Some important message to the baker (user)

Valid blocks are:

init|pre (prior to the [dvd-recipe/] tag

    Echo a message to the console prior to baking.

depend

    Echo a message to the baker when the dependency fails.

[effect] effect_name

Used within an effect or slideshow block, this tag inserts the results of effect: effect_name.

[execute] function_name

Executes a predefined function.
Can be located in block types: settings, effect, titles, title, slideshow
The text result of the execution (eg. a filename or title) can then be accessed using text substition: %%%function function_name%%%

[fetch] string

The string after the base URL used to fetch an item. It needs to contain a substring: ITEM_TO_DOWNLOAD which will be substituted for the itemId upon retrieval. Only used for Gallery2 v2.1 websites at present.

[id] integer

Meaning depends on the containing block type:

menu:

    Describes the menu number. Used to reference that menu by the [submenu] and [parent] tags.

title:

    The title number. Used to reference that title by the [title] tag within a button block, or from another title block. If the id is LEADER the title is played before the main menu is displayed.

[IFS] arg

Changes the default IFS (Internal Field separator) from ':' to 'arg'. Commonly used when a command result contains a ':'.

When declared in block type:

titles, menus, settings

    the IFS is global and will be used for the remainder of the recipe.

title, menu, slideshow, function, effect

    the IFS is local and is reset at the end of the current block.

[image] *

Meaning depends on the containing block type:

effect

        [image] filename:duration:subtitle:effects

    An image line in dvd-slideshow format to insert in the slideshow definition when the effect is called. Commonly used for multiple operations on the same image using text substitution. Refer to sample 1 and dvd-slideshow(1).

menu

        [image] id|filename

    The image id or file to use as an embedded image in the menu. Will only be used if dvd-baker is executed with the '-e' option.

slideshow

        [image] filename:duration:subtitle:effects

    An image line in dvd-slideshow format to insert in the slideshow definition when the effect is called.

[item] id|filename|argument

Meaning depends on the source type and containing block
Used in an image block, if the source type is:

    dir: The filename of the image, video or audio item.

    g2 : Used to describe the itemId of the image, video or audio item.

Used in a slideshow block, the argument is inserted verbatim into the slideshow definition.

[mimetype] typename

Used to describe the type of image, movie or audio, this optional tag must be specified before the [item] tag in the respective block. See /etc/mime.types for valid mime type definitions.

Default mime-types are:

    for audio:  audio/mpeg

    for image:  image/jpeg

    for movie:  video/mpeg

[movie] item

For source type:

    dir: item = the path name for a movie

    g2 : item = the id of the movie

The movie must be a dvd-ready movie (MPEG or VOB) for the chosen video format. No conversion is performed, so please don't specify an AVI and ask 'But why?'.

[name] text

The name of the block. Valid blocks for name tags:

depend

    The name of the dependency.

button

    The name of the button displayed in the menu's button list.

function

    The name of the function to call with [execute] or be included in a function result substitution %%%function some_name%%%. May not include '-' or ' '. Refer to sample 1

effect

    The name of the effect to call with [effect]. May not include a dash '-' or a space ' '.

menu

    The title displayed on the menu page.

slideshow

    This is really an effect that produces a title_page.

[parent] id

Used to describe the id_of_the_parent_menu to jump to when the 'up' button is pressed while the first menu button in the list is highlighted.

[sessionId] *

The session id used when the recipe was made from a website using authentication.

[sourceType] dir|g2

The type of source where the images are located.

Valid types are:

    dir: images are local

    g2 : images are from a gallery2 website (http://gallery.menalto.com/)

[submenu] id_number

The menu_to_jump_to when the button is pressed.

[subtitle] subtitle_text

The subtitle to display while an image is shown.

[title] id_number

Valid blocks for title tags:

button

    The id of the title to play when the button is pressed.

title

    A title to include in the current title definition. Commonly used to create a complex leader for each title, which is not referred to by buttons. Titles created in this way are referred to as 'dummy titles'. Refer to sample 1.

[version] number

Valid blocks for version tags:

header

    The version of dvd-baker the recipe is made for.

depend

    The minimum version of the dependency.

TEXT SUBSTITUTIONS

Function substitions can be made to insert the text result of a function definition.

%%%function some_name%%%%

Parameter substitutions can be made within_functions when a function is executed with arguments passed to it:

[execute] some_name arg1 arg2

Substition occurs within the command with %%%1%%% and %%%2%%% being substituted with arg1 and arg2 respectively.
See the samples for examples of this.  

NOTES

Titles can contain slideshow blocks AND/OR movie tags AND/OR video blocks.

A slideshow can be void of image blocks or tags if an effect is included that adds images.  

SEE ALSO

dvd-baker(1)

Index

NAME

DESCRIPTION

SYNTAX

CONCEPT

BLOCKS

TAGS

TAG DEFINITIONS

TEXT SUBSTITUTIONS

NOTES

SEE ALSO