DVDwizard
Introduction
1 Installation
2 Handling
3 How it works
Index
DVDwizard
Introduction
  The Idea
  Changes since the Initial Version
  Authors and Contributions
  Feedback
1 Installation
  1.1 Pre-Installation Thoughts
  1.2 Installation with Makefile
  1.3 Installation with ‘install.sh’
  1.4 Post-Installation
2 Handling
  2.1 The script ‘dvdwizard’
  2.2 The script ‘chaptercheck’
    Individual Options of ‘chaptercheck’
  2.3 The script ‘dvdcpics’
  2.4 The script ‘dvdtguess’
  2.5 The script ‘dvdwizard_test’
  2.6 The script ‘mk_vmgm’
  2.7 The script ‘mk_vtsm’
  2.8 The script ‘mk_vtsm_info’
  2.9 The script ‘mk_vtsm_lang’
  2.10 The script ‘mpgprobe’
  2.11 The script ‘txt2png’
  2.12 The script ‘dvdwizard_common’
  2.13 General Options
3 How it works
  3.1 Generating a DVD Structure
  3.2 Created Objects
  3.3 Restrictions
Index
  Author Index
  Programm Index
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 *note 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 *note 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 *note dvdtguess:: for
more information about generation of title from file name.

   But DVDwizard has a large number of options to change its behaviour.
See *note dvdwizard:: for more information about those.  If you want to
know how dvdwizard works, you should read *note 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 *note 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 *note ‘-h’ or ‘--help’:
Option -h, *note ‘-v’ or ‘--version’: Option -v. and *note ‘-C’ or
‘--config-file’: Option -C. 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 *note ‘-h’ or ‘--help’: Option -h. and *note ‘-v’ or
‘--version’: Option -v. will be passed to dvdwizard before the first
title option.  Option *note ‘-C’ or ‘--config-file’: Option -C. 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 (*note step
     3: it:VTSM.), 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, 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
============

* Menu:

* Becker, Stefan:                        Authors.             (line 115)
* Damnet, Jean-Luc:                      Authors.             (line 120)
* Glasstaetter, Ralph:                   Authors.             (line 122)
* Harris, Rick:                          Authors.             (line 125)
* Kohm, Markus:                          Authors.             (line 128)
* Marques, Danilo:                       Authors.             (line 130)
* Martin, Joo:                           Authors.             (line 133)
* Panteltje, Jan:                        Authors.             (line 137)
* Regelmann, Claus:                      Authors.             (line 141)
* Reichelt, Detlef:                      Authors.             (line 147)
* Rios, Rodrigo:                         Authors.             (line 149)
* Santos, Rui:                           Authors.             (line 151)
* Schmitt, Henry W.:                     Authors.             (line 154)
* Sokolov, Mikhail:                      Authors.             (line 157)
* Tremmel, Manfred:                      Authors.             (line 159)
* Werhofen, Wolfgang:                    Authors.             (line 162)

Programm Index
==============

* Menu:

* chaptercheck:                          chaptercheck.        (line 315)
* dvdcpics:                              dvdcpics.            (line 352)
* dvdtguess:                             dvdtguess.           (line 358)
* dvdwizard:                             dvdwizard.           (line 309)
* dvdwizard_test:                        dvdwizard_test.      (line 365)
* mk_vmgm:                               mk_vmgm.             (line 384)
* mk_vtsm:                               mk_vtsm.             (line 390)
* mk_vtsm_info:                          mk_vtsm_info.        (line 396)
* mk_vtsm_lang:                          mk_vtsm_lang.        (line 402)
* mpgprobe:                              mpgprobe.            (line 408)
* txt2png:                               txt2png.             (line 414)

