DVDwizard

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 with 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 The script 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.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

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