DVDwizard User Manual

Short Table of Contents

Table of Contents

DVDwizard

Creating a DVD with Chapters and Menu without User Interaction.

Introduction

DVDwizard is a wrapper-script which incorporates a fully automated creation of a DVD-structure with Chapters and menus from one or more mpeg-streams. This is done by several "sub-scripts" and various freely available tools. Needless to say, that DVDwizard is distributed under the GPL as well.

The Idea

Just issue:

#> dvdwizard my_movie.mpg

and go grab yourself a beer, have lunch oder whatever you like to do for about half an hour (depending on your machine’s speed - for me it’s 30 minutes on an Athlon 1.4 GHz, 512 MB).

Come back, issue:

#> xine dvd://$PWD/dvd/

and watch your DVD or burn it and take it to your stand-anlone DVD player.

You’ll need the programs and tools listed in TOOLS to make this work. Just install the neccessary RPMs or DEBs or compile them from source. DVDwizard checks each tool at runtime and won’t get far if some are missing.

The mentioned version numbers are the ones running on my box, so these should be working. I don’t know about any other versions, so you’ll have to try.

Changes since the Initial Version

• With version 0.4 it is possible to author multiple titlesets at once, PAL or NTSC is supported. If the movie has more than one audio stream, an audio selection menu will be shown, languages of audio tracks are now freely customizable.

  Also, a configuration file has been introduced.

• The version 0.5 almost completely reworked menu layouts, offered better support for ImageMagick > 6.0 (indeed >6.0 is neccessary now) and intro- duced Subtitle menus and the possibility to display Info-Panels with short descriptions of the movies.

  The use of a config file is now mandatory.

• With version 0.5.3 seperate font config come for buttons. And the menu titles of the main menu comes now without numbering. Please do it by youself.
• With major version 0.6 DVDwizard can be installed by make. And now there are some manpages for better and easier information.
• With major version 0.7 DVDwizard support i18n for output messages, every DVDwizard tool supports option --help and --version, the common functions are not longer read from dvdwizardrc at dvdwizard’s data dir but simply from dvdwizard_common, that is located via PATH. DVDwizard has support for audio for vizually impaired now. There’s a new tool dvdwizard_test to test the DVDwizard installation.

  Last but not least this docu has been started.

See the complete list of changes in CHANGELOG file.

Things to come may be found in the TODO file.

Authors and Contributions

There where several people who helped in making dvdwizard better:

Stefan Becker

maintainer of lxdvdrip

• Parms for subtitle language und Widescreen option.
• Support for dts and pcm audio tracks.
• Hint for specifiyng video characteristics.

Jean-Luc Damnet

french translation of the menu text items. Merci!

Ralph Glasstaetter

Huge efforts around fonts&colors, intro movie, custom audio track and lots of other ideas.

Rick Harris

Reducing flickering of menus on TV screen by adding a little motion blur to the background images.

Markus Kohm

Major changes for version 0.7.

Danilo Marques

The portuguese (south-american) translation of the menu text items. Obrigado!

Joo Martin

Maintainance and development of dvdwizard since version 0.54.

Roberto Neri

The italian translation of the menu text items. Grazie!

Jan Panteltje

• Discovered some system-dependent bugs.
• Hints and Tips for new or better features.
• Installation script.

Claus Regelmann

• Patch for correct audio language assignment for multi-title, multi-audio DVDs.
• A series of patches to the 0.5 version for better handling of unavailable stream informations, better thumbnail placement and restart improvements

Detlef Reichelt

Supplying a patch to replace toolame with twolame.

Rodrigo Rios

The Spanish translation of the menu text items. ¡Gracias!

Rui Santos

The portuguese (european) translation of the menu text items. Obrigado!

Henry W. Schmitt

Released ‘http://commons.wikimedia.org/wiki/File:Clapperboard.svg’ into the public domain.

Mikhail Sokolov

The russian translation of the menu text items. Thanks!

Manfred Tremmel

Intense testing of the new version and useful hints on better support for ImageMagick 6.2.x.

Wolfgang Wershofen

All the development work of dvdwizard since the beginning (2004) and the support to many users and developers using dvdwizard.

You may find an up to date list of people at CONTRIB.

Feedback

Wolfgang tried to test the whole package as good as possible. On his box (SuSE 9.3 through openSuSE 10.2, nothing special), it runs smoothly but he cannot give a guarantee, that it runs the same on your machine. Joo tested the whole package since version 0.5.2 on his Debian box. Markus uses the whole package almost every week on his openSuSE box.

We are sure, there are some bugs in the coding. We consider this software as beta, so use it at your own risk.

We designed the process according to our needs when recording DVB-streams from digital TV broadcasts or bond some videostreams to a DVD. Those streams are written into a large mpeg file, which we then use as input to DVDwizard.

If you have other default procedures when creating a DVD with dvdauthor, this tools may or may not help you.

Every kind of constructive feedback is highly appretiated. Please use the mailing list on http://sourceforge.net/projects/dvdwizard/.

1 Installation

In this chapter you are told, what to do before installation of DVDwizard, how to install it, and what to do after installation.

1.1 Pre-Installation Thoughts

If you have an older version of DVDwizard running (prior to 0.6), you should backup and delete the existing scripts before installing the new ones. Be sure to avoid any kind of mixture between old and new versions since they are by no means compatible. Too much has changed, sorry.

You may also remove the a installed older version of DVDwizard prior to 0.7. If you still have that old distribition you may use

#> make uninstall

within the root directory of a unpacked version of that old distribution to uninstall it. Remember, that you need to be root for installation and uninstallation, so maybe you have to use

#> sudo make uninstall

instead.

1.2 Installation with Makefile

Since version 0.6 the new and best way is the installatin using the Makefile. You need the make programm to do so. It knows the following commands:

make

make build

Create usable files in ./build. This is neccessary to expand some variables only known at installation time.

make check

Test if all directories and tools needed by DVDwizard are available.

make clean

Delete all files created at build, that are not needed to create a distribution archive.

make dist

Build a tar archive with all files needed for a valid DVDwizard distribution. You may copy that tar file to another computer, unpack it and use make install to install it.

make distbz2

Like make dist but also a bzip2 compressed tar.bz2 will be made.

make distgz

Like make dist but also a gzip compressed tar.gz will be made.

make distlzma

Like make dist but also a lzma compressed tar.lzma will be made.

make distzip

Like make dist but also a zip archive will be made.

make distclean

Delete all files created at build.

make install

Install all DVDwizard files into the system.

Note: If environment variable DESTDIR was set, the installation will be done relativ to this directory. Providers may use this to build packages for the system but install them outside.

make languages

Create all i18n files.

make uninstall

Removes all DVDwizard files from the system.

Note: You should use the same DESTDIR setting you’ve used at installation.

So to build and install DVDwizard into you system you’ll only need:

make
sudo make install

1.3 Installation with install.sh

You may simply use

./install.sh

to do the installation steps shown at Installation (Makefile). You will be asked for root password for the installation.

1.4 Post-Installation

To check the correct installation of DVDwizard you should run dvdwizard_test (see dvdwizard_test). To do so, first create a new directory, go to this directory and then call dvdwizard_text at this new directory. This will generate a DVD with two test movies. You may play it using xine. Just call

xine dvd://$PWD/dvd/

to do so.

After successfully installing DVDwizard, feel free to load the config-file /etc/dvdwizard.conf or the sample config-file /usr/local/share/doc/dvdwizard/dvdwizard.conf.sample (or similar path) into your favourite editor and change it as needed. The sample file is well documented. You may save the changed config-file into ~/.config/dvdwizard/dvdwizard.conf to create a private config-file.

After every change of dvdwizard.conf you may use dvdwizard_test to test the new configuration.

2 Handling

Using DVDwizard to create a DVD with title and chapter menu from one or more MPEG-streams is very easy. The most simple example for a ohne title DVD would be

dvdwizard -t foo.mpg

where foo.mpg is the MPEG file of the movie. The movie will be titled “Foo”. See the documentation of dvdtguess at dvdtguess for more information about generation of title from file name.

But DVDwizard has a large number of options to change its behaviour. See dvdwizard for more information about those. If you want to know how dvdwizard works, you should read How it works.

The following sections will tell you more about the single scripts, used by DVDwizard. The most important one is dvdwizard.

2.1 The script dvdwizard

Until we’ll find the time to put some text here, just try dvdwizard --help or man dvdwizard.

2.2 The script chaptercheck

chaptercheck tests if a given chapter specification is valid and generates a dvdauthor compatible one. It is invoked as:

chaptercheck option... chapterspec

chapterspec is a chapter specification. This may be either 0 or an interval or a comma separated list of timecodes or a filename.

The interval is just a numeric value in seconds. chaptercheck will then create a comma separated list of timecodes starting from 0 until the end of duration see Option -L, each timecode interval seconds later than the previous one.

A timecode is given in [[hours:]minutes:]seconds[.fraction]. You may omit hours and minutes or hours only and you may omit fraction. Note, that each timecode has to be a multiple of the frame duration, e.g. 40m,s generating a PAL-DVD.

If a filename was given, the file should store the timecodes.

chaptercheck understands the general option -h or --help, -v or --version and -C or --config-file and some individual options.

Individual Options of chaptercheck

-L seconds

--maxlen seconds

Specifies the maximum length of the movie in seconds. No chapter time code may be behind this value. Defaults to 14400 seconds = 240 minutes = 4 hours.

Note: DVDwizard calculates the duration of a movie usind ffmpeg -i and specifies the calculated duration using this option while calling chaptercheck.

2.3 The script dvdcpics

dvdcpics extracts screenshots from DVD chapters as input for mk_vtsm (menu creation).

2.4 The script dvdtguess

dvdtguess is a simple script to determine the video title from the MPEG filename. It add blanks before upper-case characters, convert underlines to blanks and remove the suffix.

2.5 The script dvdwizard_test

dvdwizard_test is a script to test the installation of dvdwizard and the required tools. You should call it in a new, empty directory. It will generate two movies and two background pictures at the current working directory and call dvdwizard to generate the dvd structure at sub-directory dvd.

To do so, it needs the file Clapperboard.svg. This file will be searched at the dvdwizard directory. You may also set environment variable CLAPPERBOARD to the path and name of that file at DVDwizard’s configuration file.

All options but -h or --help and -v or --version will be passed to dvdwizard before the first title option. Option -C or --config-file will be recognized but also passed to dvdwizard.

2.6 The script mk_vmgm

Until we’ll find the time to put some text here, just try mk_vmgm --help or man mk_vmgm.

2.7 The script mk_vtsm

Until we’ll find the time to put some text here, just try mk_vtsm --help or mk_vtsm.

2.8 The script mk_vtsm_info

Until we’ll find the time to put some text here, just try mk_vtsm_info --help.

2.9 The script mk_vtsm_lang

Until we’ll find the time to put some text here, just try mk_vtsm_lang --help.

2.10 The script mpgprobe

Until we’ll find the time to put some text here, just try mpgprobe --help.

2.11 The script txt2png

Until we’ll find the time to put some text here, just try txt2png --help.

2.12 The script dvdwizard_common

This is a sub-script with common functions for DVDwizard. It will be loaded by every DVDwizard script.

2.13 General Options

All the programs of DVDwizard understand options. Some options will be understood by every program, some are individual. The general options are:

-C filename

--config-file filename

Use filename instead of the default DVDwizard configuration file. The first default is ~/.config/dvdwizard/dvdwizard.conf. The second default is the file dvdwizard.conf at the configuration directory, usually /etc/dvdwizard.conf.

-N PAL|NTSC

--tvnorm PAL|NTSC

Choose either TV norm PAL or NTSC. Default is PAL.

-h

--help

If any argument of the program is either -h or --help the program will show only some help information and terminate.

-v

--version

If any argument of the program is either -v or --version the program will show only some version information and terminate.

3 How it works

DVDwizard takes the MPEG-streams specified on the command line and create a DVD structure in a directory. This directory can be burned on a DVD and should run on a stand-alone DVD-player.

3.1 Generating a DVD Structure

The following steps will be done to accomplish the task of generating a DVD structure:

1. Create Chapter-Screenshots for the Chapter-Selection Menu

   To create a nice and graphical Chapter-Selection menu (see step 3), a frame from the beginning of every chapter is captured, which will be converted to a thumbnail and shown as a button for the menu. To produce this screenshots, DVDwizard creates a temporary DVD-structure, which will not yet have any menus but will have chapters. The definition of the chapter-timecodes may either generated by DVDwizard (Default: a chapter every 5 minutes) or specified manually on the commandline (‘dvdwizard -c interval|string|file’).

   Here are the three possibilities:

   1. Specify a fix interval in seconds, e.g. a chapter every 10 minutes:

       #> dvdwizard -c 600
         

   2. Specify a string with the desired timecodes in the same format, dvdauthor expects them: [h:][mm:]ss[.frac], where frac are ms, to make frame accurate specifications. This frac must be a multiple of 40 (1 Frame = 40 ms for PAL), e.g.

       #> dvdwizard -c 39.400,5:12.640,1:10:42.080 
         

      starts a chapter at 39 seconds and 10 frames, 5 minutes, 12 seconds and 16 frames and the last at 1 hour, 10 minutes, 42 seconds and 2 frames. dvdauthor may not be frame accurate, if the specified frame is not an I-Frame. In this case, dvdauthor puts the chapter boundary on the most recent I-frame before the specified timecode.

   3. Specify a text file containing the timecodes as described unter b. this way, you may note down your chapter breakpoints in a file and pass it to DVDwizard.

   Chapter specification will be syntax-checked, because dvdauthor simply ignores misfigured timecodes and you end up with less chapters than specified. Will be noticed too late in most cases. :-|

   The temporary DVD-structure, which will be build with these chapters, is used for speeding up the process. With this DVD, transcode can extract the frames in DVD-chapter-mode, which is much faster than seeking through the whole mpeg-stream for the desired frames.

   On my box (Athlon 1.4 GHz), transcode seeks with about 35 to 40 fps. With this rate, it would take approx. 90 minutes to get through a 2 hour movie. In chapter-mode, transcode doesn’t need more than 5 minutes for the same task, so the 10 minutes to create the DVD structure are a good investment.

   To extract the best possible screenshot from the beginning of each chapter, 10 frames out of the first 200 frames of the chapter as transcoded to jpegs. The frame with the largest filesize is selected as the chapter-screenshot. This is done to avoid having black screenshots if a chapter starts with a fade-in. the larger the jpeg is, the more different colors and forms must be in the frame. Works perfect in my opinion.

2. Create the DVD-Main-Menu (VMGM, Title-Menu)

   This menu normally shows the Titel of the DVD and lets you choose some options like running the movie from start or go to the movies selection menus.

   The vmgm created by DVDwizard will be just like this, but since version 0.5 of DVDwizard it holds one menu page for every titleset on the DVD. On each page, there will be at least to options: start the movie from the beginning or go to the chapter selections menu. More options may be available, if the movie has more menus to choose from (e.g. Audio, Subtitle, Info).

   DVDwizard creates a background-Picture for the menu internally, however there is a possibility customize the looks via config file and command line options.

   Additionally, you may specify the title of the movie with

   #> dvdwizard -t string
   

   or let DVDwizard guess the title from the filename of the first mpeg-file. However, the result of this title-guessing may be poor depending on the name of your files. DVDwizard replaces all underscores to white-space and removes every uppercase words at the beginning and all fully numeric words at the end of the filename. This is due to the way, Wolfgang uses DVDwizard to operate the DVB-streams of his digital Satellite Set-Top-Box. The streamed files have names like TV_STATION_This_is_the_movie_title_20030321_201502.mpg so he gets rid of the TV-station name at the beginning and the timestamps at the end. Last thing will be to add a white-sprace after every lowercase letter immediatly followed by a uppercase letter.

3. Create Titleset-menus (VTSM, root, ptt, audio, subtitle)

   Just as the vmgm menu, also vtsm menus will be created. on the bottom of the menu, you’ll find text buttons for navigating within the menus. If multiple pages are used for one menu, you may navigate through the pages by pressing the left and right keys on your remote control.

   The rest of the menu is used for the chapter thumbnails, with which one can directly jump to a desired chapter. In the same manner, audio and subtitle selection menus will be produced, if the input mpeg stream has more than one audio and/or subtitle tracks.

4. Create xml-file for dvdauthor

   During the described steps before, the commands for dvdauthor are written into an xml-file on-the-fly, which will be used for authoring the final DVD structure. As default, this file is named dvdwizard.xml but you may specify a different name on the command-line:

   #> dvdwizard -x file
   

5. Create final DVD-structure

   As the last step, the final DVD structure is authored with all menus, chapters and things into a subdirectory called ./dvd, if not specified otherwise on the command-line:

   #> dvdwizard -o dir
   

After finishing these steps, the DVD can be played directly from that directory, for instance with xine.

Just issue:

#> xine dvd://"`pwd`"/dvd/

in the directory you executed DVDwizard and check, whether everything went well. If you’re satisfied with the result, you can burn this directory onto DVD.

3.2 Created Objects

After successfully running DVDwizard, you’ll find the following objects in your working directory (as long as no other target directories or filenames have been specified in the config file or command line):

Directories:

./dvd

created DVD-strukture

./vmgm

holds the main menu pages

./vtsm

holds the titleset menus

./cpics

created Chapter-Screenshots (each titleset has it’s own subdirectory \VTSx)

Files:

dvdwizard.cmd

all called scripts of DVDwizard including all parameters

dvdwizard.log

logfile with all programm output

dvdwizard.xml

XML-definition for dvdauthor

3.3 Restrictions

DVDwizard tries in general not to add further restrictions beyond the DVD specifications, but there are a few limitations, which are caused by DVDwizard and have nothing to do with the functionallity of e.g. dvdauthor or the DVD specs. These are the points:

• max. 9 titlesets per DVD (according to DVD-specs up to 99 titlesets possible)
• only 1 title within a titleset (according to DVD-specs up to 99 titles per titleset)
• no multi-angle DVDs

All these restrictions are in place due to the graphical presentation and/or the missing Know-How or interests of the author. There are no plans to get rid of these limitations in future releases.

Index

Author Index

Programm Index