DVDwizard v0.6
==============

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.

Here's 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-alone DVD.

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.

A lot of things have changed 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.

See the complete list of changes in the CHANGELOG file.

Things to come may be found in the TODO file.


Installation
============

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.

A. Installation with install.sh
-------------------------------
DVDwizard has an install script in it's tarball, that will cover the 
neccessary steps of the installation for you. Now it works with "make"

Just run:
#> sh ./install.sh

B. installation with Makefile
-----------------------------
The new and better way is the installation with the new Makefile.
It now the following commands:

make					create usable script files in ./bin
make clean				delete all files in ./bin
make install			install all dvdwizard files into the system
make uninstall			deinstall all dvdwizard files into the system

Note: Do NOT install the files manually. Then it do not work.

Note: The command collection file "dvdwizardrc" now will be installed
into /usr/local/share/dvdwizard/. But this can be changed.

Post-Installation
-----------------
After successfully installing DVDwizard, feel free to load the config-file 
into your favourite editor and change it as needed. The sample file is well
documented.


Handling
========

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. The following steps will be done 
to accomplish this task:

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

   To create a nice and graphical Chapter-Selection menu (see 3. below), 
   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:

   a. Specify a fix interval in seconds, e.g. a chapter every 10 minutes: 
      #> dvdwizard -c 600

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

   c. 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, I use 
   DVDwizard to operate the DVB-streams of my digital Satellite Set-Top-Box.
   The streamed files have names like 
   "TV_STATION_This_is_the_movie_title_20030321_201502.mpg"
   so I get rid of the TV-station name at the beginning and the timestamps
   at the end.

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.


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


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.


The "Sub-Scripts"
=================

All scripts incorporated in DVDwizard may also be used independent from 
each other and directly by the user. This way, there are more options to 
choose from than DVDwizard uses. Some infos can be found in the manpages.


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.

We are sure, there are some bugs in the coding. I 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 I 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/.


Enjoy!

