dvdwizard v0.4.2
================
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 following tools to make this work:

- dvdauthor 0.6.7
- ImageMagick 5.5.7
- toolame 0.2l
- ppmtoy4m and mplex from mjpegtools 1.6.1.90
- mpeg2enc von libmpeg2 0.2.1
- transcode 0.6.4
- sed > 4.0

The above version number 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 note for ImageMagick-6.0.7:
Something has changed in ImageMagick-6.0.7 concerning the definition of transparency. This leads to the fact
that spumux isn't able to detect the button positions anymore. You may solve this by either downgrade to an
earlier ImageMagick-version or you may modify spumux with the patch "subgen-image.patch" supplied with
dvdwizard. Just copy the file into the directory of dvdauthor and issue

	patch -Np0 -i subgen-image.patch

After that, recompile dvdauthor and spumux will happily recognize all buttons again. ;-)
In the meantime, latest alpha versions of dvdauthor handle ImageMagick >6.0 correctly without this patch.


dvdwizard is a part of a whole DVB-streaming toolbox named udrec_suite aiming at users of the digital
set-top box dBoxII running on Neutrino-Linux. udrec_suite is available at sourceforge.net (http://udrecsuite.sf.net).

A lot of things have changed since the initial version. It is now 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.
Things to come may be found in the TODO file.


Installation:
=============
Just copy the executable files to a directory that's in your $PATH and you're ready to go. If you achieved dvdwizard
as part of udrec_suite, this will be accomplished by udrec_suite's installation routines, otherwise it must be done
manually.

The following files from the tarball must be copied to a directory in your path:
- dvdwizard			Main-Script
- mk_vtsm			Creates Chapter-Selection-Menus
- mk_vtsm_audio		Creates Audiotrack-Selection-Menu
- dvdwizardrc		variouse subroutines, called from most other scripts
- chaptercheck		Check and transform Chapter-Timecodes or intervals
- dvdtguess			Guess movie title from filename
- dvdcpics			Create Chapter-Screenshots for chapter selection menus
- mk_vmgm			Create DVD main menu
- mpgprobe			Get Video and Audio characteristics from MPEG-Stream

If you have an older version of dvdwizard running, you should backup 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.

Since version 0.4 dvdwizard reads parameters from a configuration file. You find a sample file in the tarball named
dvdwizard.conf.sample which should be installed the following way:

mkdir $HOME/.dvdwizard
cp dvdwizard.conf.sample $HOME/.dvdwizard/dvdwizard.conf

After that, feel free to load the 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 are 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. dvdwizard -c 600 - a chapter every 10 minutes)

   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 als 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 chapter selection.
   The vmgm created by dvdwizard will be just like this. It show's the title and lets you either start the
   movie directly or go to the Titleset-Menus.
   dvdwizard creates a background-Picture for the menu internally, however there is a possibility to
   specify a special background-picture for the menu on the command-line (dvdwizard -B <file>).
   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 whitespace 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)
   Just as the vmgm menu, also vtsm menus will be created. on the left side of the menu, you'll find text buttons
   for navigating within the menus (if there are more chapters than will fit on a single menu - currently 15 chapters
   will fit on one menu). The rest of the menu is used for the chapter thumbnails, with which one can directly
   jump to a desired chapter.
   Just like for the vmgm, a background-picture may be specified on the command-line (dvdwizard -b <file>), otherwise
   dvdwizard creates one.
   In the same manner, an audio selection menu will be produced, if the input mpeg stream has more than one audio
   track.

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 called dvdwizard and check, if everything went well. If you're satisfied with the result, you
can burn this directory oonto 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
./vtsm				holds the titleset menus
./cpics				Created Chapter-Screenshots (each titleset has it's own subdirectory VTSx)

Files:
dvdwizard.cmd		All called scripts from  dvdwizard including all parameters
dvdwizard.log		Logfile with all programm output
dvdwizard.xml		XML-definition for dvdauthor
vmgm.mpg			DVD main menu


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.
Here's a short description of the scripts:

dvdwizard:
----------
Usage: dvdwizard [options] mpeg-file(s)

miscellaneous options:
----------------------
-h | --help   	print this lot out
-v | --version	print version and exit

general processing:
-------------------
-C | --config-file	filename of dvdwizard-configuration file
			[~/.dvdwizard/dvdwizard.conf]
-o | --output		Path where the final DVD will be stored [$BASEDIR/dvd]
-x | --xml		Print dvdauthor XML-specs into this file
			[$BASEDIR/dvdwizard.xml]
-l | --logfile		Write Log-Messages to this file [$BASEDIR/dvdwizard.log]
--restart		Do not start from beginning but from step x
			x may be dvdcpics, mk_vmgm, mk_vtsm, author
--xmlonly		Do not author final DVD, only create menus and xml

Note: $BASEDIR defaults to the current directory if not stated otherwise in the
config file (either default ~/.dvdwizard/dvdwizard.conf or specified with the -C
option)

DVD-specific options:
---------------------
-T | --vmgm	DVD-Title <string> Titlestring for the whole DVD [-t]
                if not specified, Titlestring from the first Title on the
                DVD will be used
-B | --vmgmbg	Background-Picture for VMGM-Menu
-N | --tvnorm	TV-Norm to use <PAL|NTSC> [PAL]
-V | --tvsize	Visible Area on TV-Screen <XxY> [635x535]
-WS             Widescreen-Option (nopanscan or noletterbox) for whole DVD
		may be overwritten by -ws for a specific titleset
-P | --palette  Name of palette File, needed i. E. for subpictures
-A | --Audio	language for audiotracks. <lang1,lang2,...,langn> [de,en]
		for each different audio-track format (mp2,ac3), assignment of
		language starts from beginning of list. first mp2 and ac3 track
		found in stream will be assigned to "lang1", second track to
		"lang2" etc.
		applies to all titlesets on the DVD, may be overwritten by -a
		for a specific titleset
--audio-seq	Assign languages in sequential mode, regardless of audio formats
--notitle	Suppressed printing of DVD-Title on VMGM-Menu

Title-specific options:
-----------------------
-t | --vts	Create a new titleset on the DVD with the subsequent options and
		mpeg-files.
		-t must be followed by a filename or a string or the word "auto"
		"auto" determines title-string from filename of first mpeg-file,
		if -t is followed by an existing filename, that file is considered
		to be the first mpeg in this titleset, else the string is used as
		movie title for this titleset
-c | --chapters	Chapter-Specification <0|file|timecodes|interval> [300]
		0 means no chaptering except for different mpeg-files
-b | --vtsmbg	Background-Picture for VTSM-Menu
-ws             Widescreen-Option (nopanscan or noletterbox) for this titleset
-a | --audio	see -A, but only applies to this titleset
-s | --subpic   pass subpicture information to dvdauthor.
                This is a string like "en" for english, "de" for German etc.
                More Languages by Comma Separation, i.e. "-s de,en".

Note: Every new "-t" creates a new titleset on the DVD. Subsequent options -c,
-b and -a and mpeg-file(s) apply only to that titleset. To create a DVD with 2
titlesets, use for example:
	dvdwizard -t auto -c 300 title1.mpg -t auto -b background.ppm title2.mpg

dvdwizard is the wrapper script, which calls all subsequent scripts for fully automated processing

Example:		dvdwizard -c chapters.txt -B oe_cover.png Oceans_Eleven.mpg

	Creates a DVD-structure from MPEG-Stream Oceans_Eleven.mpg into the default Subdirectory ./dvd of the acutal
   working directory and creates the chapters according to the timecodes found in the file chapters.txt.
   The file oe_cover.png is used as background picture for the vmgm menu, the title for the VMGM will be
   "Oceans Eleven"


mk_vmgm:
--------
Usage: mk_vmgm [options]

miscellaneous options:
----------------------
-h | --help     print this lot out

general processing:
-------------------
-C | --config-file      filename of dvdwizard-configuration file
                        [~/.dvdwizard/dvdwizard.conf]
-o | --output           Path where the final DVD will be stored [$BASEDIR/dvd]
-x | --xml              Print dvdauthor XML-specs into this file
                        [./dvdwizard.xml]
--notitle               Suppressed printing of DVD-Title on VMGM-Menu

Note: $BASEDIR defaults to the current directory if not stated otherwise in the
config file (either default ~/.dvdwizard/dvdwizard.conf or specified with the -C
option)

DVD-specific options:
---------------------
-T | --vmgm     Title of the DVD to display on menu
                If not specified, titlestring from the first title on the DVD will be
                used
-B | --vmgmbg   Image to use as background for the menu buttons
                If not specified, mk_vmgm will create one from scratch
-N | --tvnorm   Choose from PAL (25fps, 720x576) or NTSC (29.97 fps, 720x480)
                [PAL]
-V | --tvsize   Visible area of frame on TV set. [635x535]

Title-specific options:
-----------------------
-t | --vts      Titlestring for titleset. repeat for each titleset
                Will be ignored for single-titleset DVDs if -T is given
-b | --vtsmbg   Image to use as thumbnail for the vtsm in a Multi-Titleset-DVD
--hasaudio      Title has multiple audio tracks. A button to jump to the audio
                selection menu will be created
--hasinfo       Title has EPG-Informations available. A button to jump to the
                info panel will be created (not yet implemented)

Note: Every new "-t" marks a new titleset on the DVD. Subsequent options
-b, --hasaudio and --hasinfo apply only to that titleset.

Creates the vmgm menu for the DVD


chaptercheck:
-------------
Usage: chaptercheck <chapterspec>

currently supported options:
----------------------------
chapterspec     Definition of Chapters as <file>|<timecodes>|interval|0 [none]
-N | --tvnorm   Choose tv-norm from PAL or NTSC [PAL]
-h | --help     print this lot out

Checks specified timecodes for errors and creates the timecodes, if only an interval was specified.
If the timecodes are correct, the list is written to /dev/stdout.


dvdcpics:
---------
Usage: dvdcpics -i <dvd-image> -o <output-directory> [options]

currently supported options:
----------------------------
-C | --config-file      filename of dvdwizard-configuration file
                        [~/.dvdwizard/dvdwizard.conf]
-i | --input            Path where the DVD can be found
-t | --vts              Titleset on the DVD to process [1]
-o | --output           Path where the Pictures will be stored
-b | --batch            no user interaction - image will be choosen automagically
                        Interactive mode is the default (User chooses picture)
-f | --fsize            Frame-Size (eg 720x576) for Screenshots. If not specified,
                        defaults to attributes of the video stream
-h | --help             print this lot out

Creates the chapters-screenshots for the vtsm menu. if parm -b is not specified, dvdcpics will display the 10 captured
frames from the beginning of each chapters letting the user manually specify, which one to take as chapter thumbnail.
For this, the script needs a connection to the XServer, because it uses "display vid:*.jpg" from ImageMagick to
put the frames on the screen.


mk_vtsm:
--------
Usage: mk_vtsm [options] image-files

currently supported options:
----------------------------
-C | --config-file      filename of dvdwizard-configuration file
                        [~/.dvdwizard/dvdwizard.conf]
-o | --output-dir       Define Output-Directory where ready-made menu-mpegs should
                        be written to [.]
-x | --xml-file         Define filename for xml-definition
                        [<output-dir>/dvdauthor.menu.xml]
-b | --vtsmbg           Image to use as background for chapter thumbnails.
                        If not specified, mk_vtsm will create one from scratch
-r | --thumbaspectratio Define the desired aspect ratio for the thumbnails [16:9]
-c | --chaptersperrow   Define how many chapter thumbnails will fit in a row [3]
-N | --tvnorm           TV-Norm to use <PAL|NTSC> [PAL]
-V | --tvsize           Visible area of frame on TV set. At least my tv does not
                        show full "", but maybe yours can. [635x535]
-t | --vts              Titleset on the DVD where the menus should belong to [1]
--hasaudio              Title has multiple audio tracks. A button to jump to the audio
                        selection menu will be created
--hasinfo               Title has EPG-Informations available. A button to jump to the
                        info panel will be created (not yet implemented)
-h | --help             print this lot out

Creates the vtsm menu. Each Chapter may be started directly by clicking a thumbnail-button.


mk_vtsm_audio:
--------------
Usage: mk_vtsm_audio [options]

currently supported options:
----------------------------
-C | --config-file      filename of dvdwizard-configuration file
                        [~/.dvdwizard/dvdwizard.conf]
-o | --output-dir       Define Output-Directory where ready-made menu-mpegs should
                        be written to [.]
-x | --xml-file         Define filename for xml-definition
                        [<output-dir>/dvdauthor.menu.xml]
-b | --vtsmbg           Image to use as background for chapter thumbnails.
                        If not specified, mk_vtsm will create one from scratch
-N | --tvnorm           TV-Norm to use <PAL|NTSC> [PAL]
-V | --tvsize           Visible area of frame on TV set. At least my tv does not
                        show full "", but maybe yours can. [635x535]
-t | --vts              Titleset on the DVD where the menus should belong to [1]
--hasinfo               Title has EPG-Informations available. A button to jump to the
                        info panel will be created (not yet implemented)
-a | --audio            available audio-tracks as comma-separated list of
                        format+language eg. mp2+de,ac3+en [mp2+de]
-h | --help             print this lot out

Creates the audio track selection menu within a titleset


dvdtguess:
----------
Usage: dvdtguess filename
Guessed Titlestring is returned via /dev/stdout

This script tries to guess the movie title from its filename. It is deeply correlated to the way,
files are named for recordings within udrec_suite so results for other files may be poor.


mpgprobe:
---------
Usage: mpgprobe mpeg-file

Outputs Video and Audio specs of the mpeg file to stdout, example:

Video:704x576 16:9 25.000		# Frame-Resolution, aspect ratio, frames per second
Audio:ac3 mp2 mp2				# Formats of contained audio tracks



Feedback:
=========
I've tried, to test the whole package as good as possible. On my pc (SuSE 9.0, nothing special), it runs
smoothly but I can't guaranty, that it runs the same on your machine. I'm sure, there are some bugs in the
coding. I consider this software as pre-alpha, so use it at your own risk.
I designed the process according to my needs when recording DVB-streams from digital TV broadcasts. 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. Just mail me at "itconsult at wershofen.de".

Enjoy!

