DVDShrink and CopyDVD
-------------------------------------------------------

AUTHOR

   Rick Saunders 'Ozzzy'
   
   EMail:    ozzzy1@gmail.com
   IRC:      #Mandrake (Undernet)

PIRACY

   These utilities are NOT meant to be a method of pirating DVD's. They 
   were written to provide a method of:
   
      1) Creating a 'fair use' archival copy of a DVD movie, or
      2) To create a copy of a movie which can be taken to the lake or to
         a party/gathering which, if damaged, does not remove the use
         of the original DVD from the user and will remain in the possession
         of the owner of the original.
         
   Neither script contains any code that allows the decrypting of any
   DVD protected with CSS. If this ability exists, it exists in the libraries
   and tools that they call. Find information elsewhere.
   
   Piracy hurts everyone.... be responsible!

FILES (2.6.0 and later)

   batchrip.sh       Shell script to 'batch' rip DVD titles
   dvdshrink         The main shell script that does the magic
   dvdsfunctions     The functions file for 'dvdshrink'
   install.sh        A shell installer
   xdvdshrink.pl     Gtk2 GUI for 'dvdshrink'
   README.txt        This file
   INSTALL           How to install from the tarball
   example.xml       An example of a simple XMl file
   batchrip.txt      Some information on 'batchrip.sh'
   gpl.txt           The GNU Public License
   Menu screens and trailers

#########################     Definitions  ##########################

Audio stream   In it's current state, dvdshrink can only handle AC3 audio. The MPEG2 file
               is comprised of a video stream (MPEG2) and perhaps many audio streams along
               with (perhaps) several subtitle streams.
               
Authoring      As a DVD has a specific (highly specific) format you can't just burn the
               files to a blank and hope that it works. Dvdshrink will author the new 
               DVD properly for you.
               
Burn speed     While the burning application (growisofs) is smart enough to determine on it's
               own the speed that a blank DVD can be safely burned at, there may be times
               when you want a slower speed (cheap generic blanks for example)

DVD5           A single-layer 4.7G blank DVD.

DVD9           A dual-layer 8.5G blank DVD.

Episodes       A DVD with more than one 'feature' such as a season of a TV show is 
               split into titles with each title being one episode of the show.
               Each episode will have a video stream along with at least one audio
               stream and perhaps one or more subtitle streams.
               
ISO file       An image of a DVD that can be used to burn to a blank.

MPEG2 file     The file format used in DVDs. On commercial DVDs it consists of a video
               stream, one or more audio streams and one or more subtitle streams.

Project name   This is a name you can select for the project. It determines the filenames
               and directory structure that dvdshrink will use. For example: if you select
               the name 'mymovie' then if your base directory is /tmp all of the files
               will be in /tmp/mymovie.

Read device    The device that the original DVD will be read from. Usually in Mandrake this
               will be /dev/dvd unless you have multiple devices.
                              
Shrink factor  The amount that the _VIDEO_ stream will be 'shrunk' by (known as MPEG re-
               quantization) to make the original fit onto a smaller DVD blank. Dvdshrink
               will calculate one for you if shrinking is needed.
               
Sub stream     The subtitle stream(s) embedded in the MPEG2 file.

Title          Every DVD has at least one title. This is how DVDs are split up into episodes,
               or into movies and special features etc. The main title of a DVD is usually
               number 1.

Video stream   Each DVD title will have an MPEG2 video stream (the video portion).
              
Write device   The device that the new DVD5 will be written to. Again, usually in Mandrake
               this will be /dev/dvd unless you have multiple devices.

#########################     DVDSHRINK    ##########################

OVERVIEW
   
   DVDShrink is a console based DVD 'shrinker' for Linux or any other OS
   that has the necessary tools. It will take a commercial DVD and place
   the main feature onto a DVD-R, adjusting it's size if needed. It does 
   NOT do a complete copy of a DVD but only of the main title, ONE 
   audio track and ONE subtitle track.
   
   Folks, this is all 'smoke and mirrors' to quote a good friend of mine
   who I spent several hours with debugging. If things don't go quite as
   planned, have a look at the code; figure out what commands are being
   called and try it manually.
   
FEATURES
   
   Automatic configuration
   
      On first execution the script will prompt the user for the values that
      it needs to run. After that the script will determine what it needs.
      
   Automatic mode.   

      No intervention from the user is required. This is the default mode but
      can be over-ridden from the command-line with a full-featured set of
      options.
      
      If the user has two DVD devices (ie: a reader and a burner) the script
      can be configured or run to do an auto-burn of the copy.
   
   Failure handling.
   
      If one of a set of pre-determined commands fails the script offers the
      user the ability to attempt to fix any problem and re-start the script
      from the point of failure; saving time and worry.

   Progress reporting                     
   
      A simple but informative user interface. The user knows what step the
      script is at at all times, but the output from the various tools is
      surpressed; most being many lines of gobledy-gook.
      
   Space saving
     
      The script can be configured/run to remove working files as they become
      redundant thereby saving space on the hard drive.
      
   Simplicity

      No in-depth knowledge of DVD structure or layout is required by the
      user.

REQUIRED SOFTWARE
   
   The following software MUST be installed and functioning for the DVDShrink
   to do it's job:

      The transcode package and it's required codecs (ripping etc),
      the mjpegtools package (re-multiplexing),
      the mkisofs package (creating ISO images),
      the subtitleripper package (converting subtitles),
      the gocr package (for subtitles),
      the dvd+rw-tools package (burning), and
      the dvdauthor package (authoring DVDs).
   
   The script also makes calls to 'cat', 'stat' and a few other standard Linux
   tools. You'll want to make sure that they are in your toolset (coreutils package).
   
   If you want to run the GUI front-end you'll need to have perl and perl-GTK2 installed.

SCRIPT FUNCTION
   
   The script is written for bash. It won't work on any other shell.

   The script follows a fixed set of steps in shrinking a DVD down from a
   size that fits on a DVD9 (commercial) to one that fits onto a DVD-R or
   RW. These are:

      determine the DVD's Volume ID       -> dd           (coreutils)
      determine the DVD's chapter scheme  -> tcprobe      (transcode)
      rip the tracks                      -> tccat        (transcode)
                                          -> tcextract    (transcode)   
      resize the video track              -> tcrequant    (transcode)
      remultiplex the video and audio     -> mplex        (mjpegtools)
      turn the subtitle track into images -> subtitle2pgm (subtitleripper)
      mux the subtitles with the MPEG2    -> spumux       (dvdauthor)
      author the DVD                      -> dvdauthor    (dvdauthor)
      create an ISO image                 -> mkisofs      (mkisofs)
            or
      burn the new DVD                    -> growisofs    (dvd+rw-tools)   
      
   The script writes it's progress in the project's directory tree which
   keeps track of where it is in the process. If the script is restarted with the
   --restart option, it reads this file and knows where to begin anew. Also,
   once in a blue moon a command WILL finish with usable output but will error
   out. In this case, if the output looks good issue the --jumpin option to
   continue on as if nothing happened
   
   The script writes it's run-time variables in a file called
   '/tmp/dvdshrink.var' which is read after a failure/restart and allows the
   script to skip many of the 'houskeeping' functions and go right to the 
   correct spot to begin execution with all needed variables set.
   
   The script will place all of it's working and temporary files in a directory
   called $BASEDIR/<DVD Volume ID> by default. $BASEDIR is set by the user 
   during initial configuration. Make sure that the directory selected is on
   a file system that has enough space to hold about twice the size of the
   original movie (from 10G to 18G).

SCRIPT OPTIONS

-A|--authoronly

   This will have the script stop after authoring the new DVD5. It will 
   leave the files in the directory <basedir>/<projectname>/BUILD. You can 
   use the 'mkisofs' command on this directory to make an ISO image of the 
   DVD or use 'growisofs' to burn it to DVD5.
   
-B|--noburn

   Tells dvdshrink to prompt you before it tries to burn a new DVD
   
-D|--nodeletefiles

   Tells dvdshrink _NOT_ to remove it's working files as it goes (to a point). 
   This will take up a LOT of disk space, but will leave you the files if 
   you need them later.
   
-F|--forceburn

   Tells dvdshrink that you don't want to be prompted before burning (only 
   works if you have more than one device). After authoring it will auto-
   matically start the burn to your blank.
   
-I|--info

   If this option is passed dvdshrink will read the information for the 
   first title on the source DVD and present it to you.
   
-K|--noshrink

   Tells dvdshrink _NOT_ to shrink the video stream at all. If you are 
   buring to a dual-layer DVD then you can pass this and get a less com-
   pressed MPEG2 file.

-L|--listall

   Tells dvdshrink to present you with a list of the titles, then a list 
   of the audio streams, THEN a list of the subtitle streams. You can 
   chose which ones you want to work on from the lists. The same as is-
   suing -t list -a list -u list.
   
-M|--bigmpegonly

   Tells dvdshrink to _STOP_ after ripping the selected streams and re-
   multiplexing them into a new MPEG2 file while _NOT_ shrinking the 
   video stream.

-O|--saveiso

   Tells dvdshrink to not only burn the new DVD, but to create an ISO
   file on your drive for archiving.
   
-P|--pauseonexit

   This was added for the GUI so that the console window would be left 
   open after the project was complete. If it wasn't issued then the 
   console would disappear as soon as the project finished (or errored) 
   and you would not know what happened in the case of an error.

-S|--bigstreamonly

   Tells dvdshrink to just rip the elemental streams (video, audio and 
   subtitle) that you selected then _STOP_.
   
-T|--showtitles

   Dvdshrink will present you a list of all the titles on the DVD then 
   exit.
   
-V|--showvalues

   Normally, dvdshrink shows you a small synopsis of what it's going to 
   do before it starts doing it. With this option passed, dvdshrink will 
   tell you a whole lot more and give you a chance to back out.

-a|--audio <num>

   This option allows you to pass a specified audio stream to dvdshrink 
   to be ripped. The default is 0 which is the first audio stream on the 
   source DVD. If you want to see a list of the audio streams then pass 
   -a list to the app.
   
-b|--burn

   Tells dvdshrink to auto-burn the new DVD. This does _NOT_ mean that it 
   won't prompt you, but it tells you that it's ready to go and gives you 
   a last chance to put the blank in.
   
-c|--configure

   Allows you to re-configure dvdshrink.
   
-d|--deletefiles

   Passing this option over-rides whatever is in the default configuration 
   and allows you to have dvdshrink auto-delete it's working files even 
   if you've set it not to in the configuration. It saves space on the 
   working drive.         
   
-e|--episodes <num>

   On an 'episodic' source DVD9 like a television show set, this tells 
   dvdshrink how much to shrink each MPEG2 file so that you can put <num> 
   on a single DVD5. Normally it is not used for movies and is only passed 
   to dvdshrink by the 'batchrip.sh' script.

-i|--isoonly

   Tells dvdshrink to _NOT_ burn a new DVD5 but to create an ISO file 
   that can be used to create one. Stored in /tmp.   
      
-k|--shrinkfactor <val>

   The amount that dvdshrink will compress an MPEG2 file to fit where you 
   want it to fit (normally on a DVD5). 1.0 means 'no compression' and the 
   script will only allow you a maximum value of 2.0. Anything higher an you 
   get spotty output which may not work at all. The calculation used is as 
   follows:
   
   k = (1.05  v)/(4.7G - (a + s)
      k = shrink factor
      v = size of video stream
      a = size of audio stream
      s = 10MB
      
-l|--deletelogs
   This switch tells dvdshrink to delete the log files that it keeps in your
   home directory after a successful rip. If the script abends then the log
   files are kept for your perusal.
   
-m|--mpegonly

   Tells dvdshrink to create an MPEG2 file and _STOP_. This file can be 
   used as is or used to custom author a new DVD5 using 'dvdauthor'
-o|--isodir

   Tells dvdshrink where to store ISO files
      
-p|--project <name>

   The project name is the name that is used to create all the direct-
   ories and filenames during a rip sequence (see Definitions)

-r|--read_device <dev>

   This is passed to dvdshrink to specify a read device _OTHER_ than 
   that specified in the configuration.
   
-s|--streamonly

   Tells dvdshrink to rip the elemental streams (video, audio and subtitles)
   and then shrink the video stream then _STOP_.
            
-t|--title <num>

   Allows you to specify which title on the DVD9 to rip. Normally on a 
   movie the first title (1) is the main feature. But if it's another title 
   you want then you can specify. Use -t list to get a list of titles on 
   the source DVD to select from.
   
-u_subtitle <num>
   
   Allows you to specify which subtitle stream to rip. Normally this is 
   not selected. If the DVD9 you want to rip is _NOT_ in your native lan-
   guage and there is no native language audio stream then you can select 
   a subtitle stream. Or, if you are hearing impaired this allows you to 
   rip and properly 'mux' in the subtitles. Use -u list to see a list to 
   select from.
   
   Note: This is smoke and mirrors. On some DVDs you may get a 95-96% rate 
   of good subtitles. On others you'll do better. In any case, there may be 
   a title or two that are corrupt.
   
-v|--version

   Show the version information and exit.
   
-w|--write_device <dev>

   Over-ride the write device in the configuration with the device specified
   by issuing the -w option.   

-h|--help

   A short synopsis of this page.
   
--long-help

   A longer synopsis of this page.
   
--restart

   If dvdshrink errors you will be told what happened, and where to find more
   information. If you think you can (or have) fixed the problem you can re-
   start dvdshrink with the --restart option to start with the function that 
   generated the error (makes life simple).
   
--jumpin

   If dvdshrink errors and you _KNOW_ that the error is wrong you can re-start
   dvdshrink with the _NEXT_ function in line to attempt to carry on.         
   
LICENSE

   Both are released under the GNU Public License. See the 'gpl.txt' file
   which is included in this package. Feel free to mess with the thing as you
   will; but I'd appreciate an email explaining what you did and why.
   
WARRANTY

   The author does NOT warrant that the software provided will function, nor
   does the author accept any responsibility for any damage or loss of data
   incurred by running this software.
   
CHANGELOG
   Version 2.6.1  -New GUI responses to fix widget mixup on 'kill bash'
                  -Removed 'Kill BASH' button, now a dialog
                  -Attempt to fix A/V synch problems with some machines
   Version 2.6.0  -Massive re-write of most bash functions for simplicity, speed
                  -and readability
                  -Added ISO save and selection of ISO storage location
                  -Slightly smarter error trapping in single mode
                  -Added tests for whether a DVD is blank or readable (as needed)
                  -Added ANSI colours in console for a prettier UI
                  -Added A/V Synchronization check of source title
                  -More readable log file(s)
                  -Many minor bug-fixes in single mode
                  -Better logic in episode mode
                  -Minor bug-fixes in episode mode
   Version 2.5.2  -Added some functionality to the episode mode in the GUI.
   Version 2.5.1  -DVD Menuing system added to BatchRip
                  -Fixed a nasty little bug in the 'dvdshrink' subtitle
                  -creator.
   Version 2.5.0  -Delete logs checkbox added. 
                  -Smarter logic in the GUI to weed out improper entries
                   in the entry boxes.
                  -Minimal 'restart' mode added to the 'episode' mode
   Version 2.4.2  -Unified single title/episode GUI. xdvdshrink.pl and
                  -xbatchrip.pl were rolled into a single app with 
                  -selectable tabs.
                  -Minor change to 'batchrip.sh' (2 lines) to match the
                  -functionality of the GUI
   Version 2.4.1  -Code optimization in the functions file
                  -Some minor GUI work
   Version 2.4    -Bugfixes (thanks Agios and HawkWind)
                  -Logic fixes in audio stream selection
                  -New smarter installer for tarball
                  -New GUI items and functionality
                  -Fixed show-stopping bug in subtitle XML file checker
   Version 2.3.2  -Bugfixes due to batch ripping
   Version 2.2.5  -Added xml creation and dvd authoring scripts to match
                  -the output of the main scripts
   Version 2.2.4  -Fixed a nasty little bug in the requantization function
                   where a custom shrink rate would cause the script to barf
                  -Added the -n (--nodiskprompt) option so you could script
                   batch ripping.
   Version 2.2.3  -Some more minor fixes to bash (mostly for GUI function-
                   ality)
                  -Fixed some bugs in GUI
                  -Added functionality to GUI
   Version 2.2.2  -Replaced 'isoinfo' with 'dd' to get volume ID
                  -Some minor fixes to bash
                  -Some minor fixes to GUI
   Version 2.2.1  -Fixed a nasty bug (how did THAT get past <sigh>
                  -Added the graphical front-end to the script
   Version 2.2    -Logging added
                  -Moved cloning/copying to 'copydvd'
                  -No more reliance on 'grep' or 'gawk'.Just about everything is 
                   in-shell now with the exception of 'cat' and  'stat' which 
                   are part of the Linux core utilities.
                  -Code cleanup
   Version 2.1    -Added selectable title list
                  -Added debugging output (per command only if failure)
                  -Fixed lack of prompt with one device and auto-burn
                  -Re-wrote the audio and subtitle selection functions
                  -All files now in working directory
                  -'--jumpin' option added
                  -Code cleanup
   Version 2.0d   -Logic cleanup
                  -Code cleanup
   Version 2.0c   -First release with subtitles activated
                  -Script split into two files, one for execution
                   and the other for the functions   
   Version 2.0    -Added error-trapping
                  -Added failure handling mode
                  -Added output options
                  -Code cleanup
                  -Commenting
   Version 1.0    -First stable release.


TROUBLESHOOTING

   If the script fails you are presented with what happened. At this point
   you have two options. Fix the files and issue a --restart option or if
   thing look good (mplex fails but the mpeg file looks good) issue a 
   --jumpin option to continue.
   
   Any other problems email me (see the email address at the top of this
   file) and I'll see what I can do.


###########################     BatchRip     ############################

OVERVIEW
   
   BatchRip includes a command-line 'batch' front-end to 'dvdshrink' 
   allowing you to archive multiple titles from a single
   (or multiple) DVD(s). The executable file is 'batchrip.sh'.

   NEW 2.6.0

   BatchRip now will build you a DVD menu system for your multi-episode
   DVDs. If there are more than one (and less than 9) titles on your
   DVD the menu is automatically inserted in the new DVD. This is very
   minimal but does allow selection. Tested for NTSC only but the PAL
   menus are included and under test.

SCRIPT SETUP
   
   BatchRip will use the DVDShrink configuration as needed.

REQIRED SOFTWARE

   BatchRip requires that you have all of the necessary dependencies for
   'dvdshrink' installed and functioning.


SCRIPT FUNCTION

   Uses 'dvdshrink' to archive multiple titles to MPEG2 then optionally
   builds 'dvdauthor' XML files and authors the DVD(s)
           
TROUBLESHOOTING
   
   No troubleshooting code is provided.

SCRIPT OPTIONS

-a|--audiostream <num>

   Tell batchrip.sh which audio stream to rip from the DVD9.
   
-B|--burndvds

   Tell batchrip.sh to start the DVD5 burn after ripping and otherwise 
   processing the source DVD9. This will prompt you to insert the cor-
   rect blank. This infers the -d and -x options.

-d|--builddvd

   Tell batchrip.sh to author the new DVD5 on the hard drive.
   
-e|--episodes

   Tell batchrip.sh how many episodes should be authored per DVD5. The 
   script is capable of ripping a whole series of original DVDs and storing 
   ALL of the MPEG2 files on the hard drive; then authoring and burning ALL 
   of the new DVDs in a single 'batch' run. To do this issue batchrip.sh with 
   only the -e option specifying how many episodes to put on each new DVD5 
   _UNTIL_ the last time batchrip.sh is called. For the last run tell 
   batchrip.sh to burn the new DVD5s by issuing the -B option. All of the 
   DVD5s will be authored and burnt in sequence with the correct number of 
   episodes per DVD.
   
-F|--forceburn

   To be used _ONLY_ when a single DVD5 is to be burnt. No prompt will be is-
   sued by the script and multiple devices are neccessary.

-i|--interactive

   Batchrip.sh will run in interactive mode querying you for information.

-l|--lasttitle <num>
   Tell batchrip the number of the last title in a sequence from a to b to 
   rip where a is the title to start with and b is the title to end with.
   
-L|--deletelogs
   Tell batchrip to delete the log files created after a successful rip.

-m|--createmenu
   Tell batchrip to create a DVD menuing system on the new DVD. This is
   very minimal and sparse but works. It is only implimented on DVDs with
   more than 1 and less than 9 titles.

-M|--nomenus
   Tell batchrip NOT to create the DVD menuing system.
      
-n|--showname <name>

   Tell batchrip.sh to use a specific show (or project) name instead of 
   querying the source DVD for the information.

-N|--noremovefiles
   Tell batchrip.sh NOT to remove working files but to leave them on
   the hard drive.

-o|--isodir
   Tells batchrip.sh where to store ISO images

-O|--saveiso
   Tells Batchrip.sh to create/store an ISO image along with burning the
   new DVD
   
-r|--riplist <comma delimited list>
   Tell batchrip to rip the specified titles in order as given. Normally 
   batchrip.sh will rip all the titles starting at the start title and 
   ending with the last title specified by the -s <num> and -l <num> options. 
   If you want to only rip titles 2,4,5 and 8 then issue -r 2,4,5,8.

-R|--removefiles
   Tell batchrip to clean up the working files when no longer needed to
   save drive space.
   
-s|--starttitle

   Tell batchrips.sh which title to start with when you wish to copy all 
   of the titles from a to b.
   
-u|--substream <num>

   Tell batchrip.sh to rip the same subtitle stream for each title it 
   works on. 

-x|--buildxml

   Tell batchrip.sh to build an XML file for each new DVD5 that it will be 
   writing with the specified number of episodes on each new DVD. Infers 
   the -d option.
         
-h|--help

   A short synopsis of this page    

--restart

   Restart the script after a title (or titles) fail. Will attempt to re-rip
   the failed titles.

--postprocess

   If all else fails, do the post-processing (XML creation, ISO creation burn
   etc.) on the titles that were correctly ripped.

Version 2.6.1    -See changelog for 'dvdshrink'
Version 2.6.0    -See changelog for 'dvdshrink'
Version 2.5.0    -See changelog for 'dvdshrink'
Version 2.4.1    -Stable

#######################################################################  
      
FUTURE
   
   Of course, bugs will be fixed as they are reported to me either on the
   Undernet (#mandrake) or by email at ozzzy1@gmail.com.
   
THANKS

   Thanks to 'Agios' 'HawkWind' and 'Benja22' on the Undernet for working with 
   the script and passing on any pitfalls and comments. And more thanks to
   'HawkWind' for working on the html version of the documentation.
   
   Also thanks to the many users on Undernet in #Mandrake or in Freenode in
   the #lfd channel for their comments and for pointing out 'issues'.
   
Regards and enjoy!



               
