DVD2DIVX MANUAL =============== 1. Introduction 1.1. Purpose and Philosophy 1.2. Key Features 1.3. Requirements 1.3.1. Software 1.3.2. Time and Disk Space 1.4. Background Articles 1.5. Legal Notice 2. Step By Step Walkthrough 2.1. Preparations to get started 2.2. Initial settings in config file (Part I) 2.3. run `dvd2divx audio' 2.4. run `dvd2divx calc' 2.5. run `dvd2divx crop' 2.6. Completing settings in config file (Part II) 2.7. run `dvd2divx preview' 2.8. run `dvd2divx video' 2.9. run `dvd2divx mix' 2.10. Erasing Temporary Files 3. Splitting a Movie (optional) 3.1. Overview 3.2. find_env 3.3. find_key 3.4. to_frame / from_time / between 4. Copyright and Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Introduction 1.1. Purpose and Philosophy This script covers all steps that are necessary to transcode a movie from DVD into a movie in DivX format. It is basically a frontend for `mencoder', the encoding software that is part of the `mplayer' distribution. mencoder is highly configurable and enables you to create high quality video encodings. This script is meant to be a compromise that provides good configurability and still handles the generation of the complicated mencoder commands with many parameters. 1.2. Key Features Of course, there are many programs around that help to convert a DVD into a DivX movie. Besides mencoder there is also `transcode'. If you do not want to use mencoder you should stop reading because this is the wrong tool for you ;) The next thing is that you could use mencoder directly by hacking the necessary command into your shell. But, if you did that before, you will agree that this is prone to errors. On the other hand, there are some fire-and-forget tools around that do all the work for you and make more or less intelligent decisions resulting in more or less quality. dvd2divx tries to help you by doing the work for you that's always the same. And it wants you to have adequate control over the settings that affect the quality of the result. Key features are: - step-by-step approach comprises the actions `audio', `calc', `crop', `preview', `video', `mix' and `split' - preview functionality lets you check if your settings will lead to a satisfying result - create an arbitrary number of stand-alone movies with audio tracks in different languages while encoding the video only once - audio tracks can be manipulated with a tool of your choice, e.g. low-volume movies can be normalized - all encoding steps run with lowest scheduling priority so that you can work on other things without perceptible performance loss 1.3. Requirements 1.3.1. Software You will need a Unix system with a Boune Again SHell (bash) to run this script. Besides this, an installation of mplayer (which includes mencoder) and lame is required. I tested this program with - GNU bash, version 2.05a - MPlayer 1.0pre5-2.95.4 http://www.mplayerhq.hu - lame 3.90 http://www.mp3dev.org/ Optional: if you want to normalize the audio track of the movie I can recommend the program `normalize', written by Chris Vaill. But, as stated above, you are free to use any tool that can handle wave files (.wav). 1.3.2. Time and Disk Space In order to give you an idea of how long the actions will approximately take and how much free disk space you will need, here some rough numbers measured for - a typical two hour movie - encoded in a video bitrate that results in a 2x700MB movie - mixed with two different audio tracks The duration of most actions mainly depends on the CPU. If you send me measurements for your CPU I will add them to this table. The actions calc and crop are fast enough to be neglected. Duron 800 audio 2 h preview 2 min video 5 h mix 3 min Required disk space for the settings mentioned above: 1.5 GB (log files; temporary audiodump.wav) OUTDIR_TMP 1.5 GB (MP3-encoded audio tracks; encoded video) OUTDIR_FINAL 2.8 GB (final movie files in two different languages) 1.4. Background Articles Before using this script you should gain a certain insight in the technical backgrounds of the process of DVD encoding. There are many mencoder tutorials around: http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-dvd-mpeg4.html tutorial that is part of the mplayer documentation with good explanations of some technical details http://www.bunkus.org/dvdripping4linux/index.html english tutorial, quite comprehensive, covers not only encoding with mencoder but also with transcode tool suite 1.5. Legal Notice Please keep in mind that, depending on the laws in your country, creating a copy of a DVD might be prohibited, even if you own it and the copy is for private use only. Make sure that your data source permits duplication! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Step By Step Walkthrough The recommended order of dvd2divx actions that can be found throughout this manual is not arbitrary; there are good reasons to stick to it -- at least if you are new to this subject. Keep in mind that you can always get help by calling `dvd2divx -h'. This will show you a usage screen summarizing the command line options. 2.1. Preparations to get started First of all, the DVD data must be accessible. There are several ways to achieve this: - You can simply put the DVD into your drive and mount it. - You can use a program like `vobcopy' which lets you mirror the DVD data onto your hard disk (will occupy about 8GB of disk space). You could use the following command: vobcopy -m -o - You can dump the DVD to your hard disk by using the dd command that is part of almost every Unix system. Then mount the dvd image as a loop device. Remember not to mount the DVD itself because the dd command will access the device on a lower level. Example: dd if=/dev/dvd of=./image; mkdir data; mount -t iso9660 -o loop image data). If possible, I recommend using dd or vobcopy because access to your hard disk is much faster and your DVD drive might become quite hot when reading for many hours. Now that the DVD is accessible, create an empty directory to work in and `cd' into it. For the rest of the process stay in here. All log files will be created inside this directory as well as the video preview and a script to delete all of these temporary files after the DivX movie was created. 2.2. Initial settings in config file (Part I) Generate a template configuration file by executing `dvd2divx -g'. Open the generated conf file with the editor of your choice and adapt it to your needs. The included comments will help you and if you also read the rest of this paragraph, you should have no problems finding approprate settings. Note: blanks are input seperators in shell commands. Although this script should handle paths or filenames containing whitespace correctly as long as you put quotes around them, it is recommended to avoid blanks if possible. DVD_TITLE A number represending the DVD title that contains the main movie. Usually this will be "1" but there are also many movies around that have their main movie in title 37 or something like this. When using vobcopy to mirror the DVD on your hard disk, you can take a look at vobcopy's output. It lists each title with its number of chapters. Thus, if the movie is not in title 1 start trying titles that contain many chapters. That's usually a good guess. DVD_DEVICE The full path to the directory containing the DVD data. This is the directory that usually has a folder `VIDEO_TS' in it. You can use your DVD drive directly (e.g. "/mnt/dvd") or specify a directory on your hard disk if you mirrored the DVD (e.g. "/home/user/tmp/movie/data"). OUTDIR_TMP The directory which audio tracks and video will be put in before mixing them. Because of the fact that dvd2divx encodes audio tracks and the video seperately and mixes them together in the end, there is the need for some temporary disk space. OUTDIR_FINAL The directory which will contain the final movie files. After dvd2divx action `mix' a stand-alone movie for each of the chosen languages will be created in this directory. TITLE_SHORT A short but descriptive working title used for temporary files. Be creative, do not use `foo' for each of your movies because if it is unique you can use the same OUTDIR_TMP even if you work on several movies at the same time. If it is not you will overwrite temporary files from the other project. That would be annoying. TITLE_FINAL The title of the final movie created in OUTDIR_FINAL. Specify the title only, filename extensions will be added automatically. LANGUAGES A list of language abbreviations. The list entries must be surrounded by parentheses and seperated by spaces. Refer to the mplayer manual to find out valid tokens. Typical values are `en' for english, `de' for german and so on. One stand-alone version of the movie will be created for each language. ARTIST [optional] String variable that can be used to set the artist field in the movie header. This could be your name or pseudonym. AUDIO_MOD [optional] Modification of the audio track. A typical use case for this is a command to raise the audio volume. This command will be executed for each audio track specified in LANGUAGES. This variable's value can be either a shell command in which $dumpfile is a placeholder for the wave file or it can be a simple exclamation mark ("!"). In the latter case the program will stop and wait until you press a key to proceed. Before doing that you can manipulate the audio track. The first variant is the more elegant way and works with any command line tool. Just put the placeholder $dumpfile at the position where the tool expects the input wave file. It is also possible to execute a whole batch of commands, e.g. AUDIO_MOD='yourTool "$dumpfile" output.wav; mv output.wav "$dumpfile"' Note: You MUST put single quotes (') around the command to protect the $dumpfile variable against being expanded prematurely. Moreover you should put double quotes (") around the variable itself in case its value contains whitespace. FFOURCC [optional] FourCC is an AVI tag to identify the software used to encode and the intended software to use for decoding the video. *** Important for users of MEncoder >= 1.0pre7 *** libavcodec, the native MPEG-4 encoding library usually shipped with MEncoder, used to set the FourCC to 'DIVX' when encoding MPEG-4 videos. For MEncoder versions later than 1.0pre7 the new default is 'FMP4', but you may override the FourCC tag by setting this variable. Refer to the MPlayer documentation for further information. The rationale for using 'DIVX' as tag value was that it is supported by a broad range of players, including some hardware DVD players. The drawback of this camouflage is that some players may fail to playback files that were encoded using advanced libavcodec features not supported by DivX4. A compromise may be 'XVID' that is closer to libavcodec functionality and still is supported by many other players. You may change the FourCC of existing files, e.g. mencoder input.avi -o output.avi -ffourcc XVID NOSOUND [optional] Forces option -nosound instead of -oac copy during video encoding. By default, the original audio stream is copied while the video encoding process is running. This should make sure that audio and video are in sync when muxing an audio track into the movie later. In other words, the copied audio stream will be discarded later and replaced by an MP3 encoded stream. If the NOSOUND variable is set the video will be encoded without regarding the audio track, i.e. without mencoder's sync correction that skips or duplicates video frames to maintain sync. In theory this can result in audio and video being badly out of sync but my experience is quite contrary to this. This setting can help to get both streams perfectly in sync, although I cannot recommend this method generally. 2.3. run `dvd2divx audio' This action should always be the first to be executed because you will not know which bitrate to use for the video encoding until the audio track is encoded. Based on the size of the encoded audio track you can then calculate the video bitrate for some typical target sizes, e.g. 700MB or 1400MB. 2.4. run `dvd2divx calc' In this step you calculate the video bitrate. This action expects three numeric parameters: - the target size (in MB). Typically this will be something like 700 or 1400 if you are planning to burn the resulting movie on one or two CD-ROMs. - the audio size (in bytes). Put in the exact file size of the MP3 file created in action `audio'. If multiple audio tracks have been created use the largest number. - the length of the movie (in seconds). Make sure to be as exact, using the playtime printed on the DVD cover is not recommended -- it is in minutes anyway. One way to get this value is examining the logfile from action `audio'. Supposed the last position is 1:34:35 you would calculate the number of seconds like this: 1*60*60 + 34*60 + 35 == 5675 Example: $ dvd2divx calc 700 89107656 5675 => 894 kbit/s You will need this result below. You can experiment with different target sizes leading to different video bitrates. At this point I do not provide a recommendation for a minimal bitrate. It depends on the type of movie as well as on your personal taste. That's why dvd2divx has a `preview' action. 2.5. run `dvd2divx crop' Cropping is the process of cutting the black bands off the movie material. It would be a waste of information if you encoded them into your DivX movie. Luckily, mencoder comes with an autodetection algorithm to calculate the area that actually contains the movie's pictures. The only requirement is that this autodetection should be run on a bright scene occupying the whole picture area. By default dvd2divx jumps to chapter 2 for crop detection but I recommend checking if that scene meets the requirements. If not, play the beginning of some other chapters until you found one starting with a bright scene. For example, if chapter 4 seems adequate call `dvd2divx crop 4'. 2.6. Completing settings in config file (Part II) After executing the actions `audio', `calc' and `crop' you have gathered all information necessary to complete the settings in the config file (Part II). Affected variables in this step will be: - ENC_BITRATE - ENC_CROP - ENC_SCALE [optional] ENC_BITRATE Edit the value of the variable ENC_BITRATE and set it to the value you calculated during action `calc', e.g. ENC_BITRATE="894". ENC_CROP As for cropping, dvd2divx extracted the relevant data from the crop step's log file and created the file `crop.stats'. This contains a summary of the crop detection and helps you selecting the right crop area. The number in the first column indicates how often the respective crop area was proposed: 2 crop area: X: 1..614 Y: 11..575 (-vf crop=612:564:2:12) 2 crop area: X: 1..616 Y: 11..575 (-vf crop=614:564:2:12) 8 crop area: X: 1..695 Y: 3..575 (-vf crop=694:572:2:4) 2 crop area: X: 1..711 Y: 3..575 (-vf crop=710:572:2:4) 1390 crop area: X: 1..718 Y: 2..575 (-vf crop=716:574:2:2) 72 crop area: X: 1..718 Y: 3..575 (-vf crop=716:572:2:4) Usually one line will have by far the highest count. That's the one to use. In this example the fifth line is the right one. If, like in this example, the chosen scene started dark and became bright after a few seconds the values will have changed and then become stable. That's why there are some other values that can be ignored. The line order can be ignored as well. The important piece of information is the colon-separated value after `-vf crop='. Set the variable ENC_CROP accordingly, e.g. ENC_CROP="716:574:2:2". ENC_SCALE [optional] Optional variable to scale the movie. If this is not set the movie will be stored in its original dimensions. Because of the way the video is stored on a DVD the player must scale the movie to the correct aspect ratio while watching it; this is how it works for DVDs. For AVI videos like DivX it is also possible to store an aspect ratio, but it depends on the player software whether this information is interpreted. mplayer stores that aspect ratio in the movie's meta data and plays these movies correctly, but can never be sure if this is also implemented in other players. Thus I recommend setting this variable. Due to the encoding algorithm it is required that the scaling dimensions are multiples of 16. The following example will show you how to calculate the scaling for a movie which has the typical widescreen aspect ratio of `2.35:1'. The aspect ratio can usually be found on the back of the DVD box. If not, try using an internet search engine, or make a screendump while playing the movie and calculate it yourself. Based on the width of the video after cropping you can calculate the height to use. The width of the DVD source material is typically 720 and therefore we will use this width in the following example. But sometimes the width will be reduced due to cropping. Thus, if after action `crop' the width becomes smaller than 720 you should rather scale to 704 (more generally: 720 - n*16) because downscaling yields better quality than upscaling. In this case you will have to calculate the vertical scaling based on a width of 704 to match the aspect ratio. 720 / 2.35 == 306 306 modulo 16 == 2 306 - 2 == 304 The calculated height must be in-/decreased to be a multiple of 16. This depends on how far you are off. In this case, subtracting 2 is obviously preferable to adding 14. As a result of this calculation you will use ENC_SCALE="720:304" 2.7. run `dvd2divx preview' This step is short but helpful. A one-minute DivX movie will be created using the settings specified in the config file. You can add an optional parameter, e.g. `dvd2divx preview 5' if you want the preview to start at chapter 5. After executing this action you can playback `video--preview.divx.avi' and check if the video parameters are satisfying for you, especially the video quality (depending on the chosen video bitrate) and the video scaling. Note that the sound is irrelevant in this step as it will be remuxed during action `mix' later. Concentrate on the video quality and adapt the settings if necessary, that's what this step is for (it's preVIEW). If the preview looks good take a deep breath and relax. Most of your work is done. But for your CPU the toil is about to begin... 2.8. run `dvd2divx video' There is not much to say about this step. It will take several hours for this to finish. The video will be encoded in two passes. The first pass is for analysis of the source material while the second pass actually performs the encoding. That's only a rough and incomplete explanation of the encoding process. Further details would lead off the topic of this manual. Please refer to other sources for deeper insight. 2.9. run `dvd2divx mix' In this step the final movie(s) will be created. In the directory specified by the variable OUTDIR_FINAL you will find one movie for each of the selected languages. 2.10. Erasing Temporary Files As you have learned the dvd2divx actions create log files and other temporary files that can be deleted once the movie was finished. In order to help you cleaning up a shell script called `make_clean' is generated in the working directory. It deletes all these temporary files from the current working directory and from the OUTDIR_TMP folder. The configuration file will not be deleted; maybe you want to keep it for future reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Splitting a Movie (optional) This step is necessary for example if you have chosen a video bitrate for a target size of 2x700MB and now have a 1.4GB movie that you want to split in two halves. Splitting a DivX movie is not trivial and you should have some basic understanding how this movie format works. The main task is finding an appropriate position for the splitting. Appropriate means that it must be the position of a keyframe and the output file matches the desired file size. dvd2divx helps you by providing some `split actions'. They are summarized on a special help page that will be shown by calling `dvd2divx -h split'. The common syntax is as follows: dvd2divx split The first parameter of the action split is always the location of the movie file to be split. This will only be read from, so there is no danger of destroying that movie -- unless you specify the same file as output of the splitting, of course. 3.1. Overview Let's start with the big picture: what are the necessary steps and what is to be done there? At first, you need to have a rough idea where the splitting should take place, i.e. you need to find out the environment to start playback. Then, you look for the exact keyframe. Finally you create a stream copy of the source movie into some output file; start and/or end of this stream copy will be specified with the help of that keyframe you just found out. The follwing sections will clarify their explanations by a common example: the file ~/movies/my_movie.en.divx.avi was created with a video bitrate that led to a file size of 1.4GB. In order to burn it on two CD-ROMs it is to be split in two roughly equal-sized parts. 3.2. find_env Syntax : dvd2divx split find_env [] Example: dvd2divx split ~/movies/my_movie.en.divx.avi find_env Following the example mentioned above the splitting should result in two movie files of about 700MB. Therefore this step finds the environment in which you can start looking for an adequate keyframe for splitting. With the optional parameter you can specify how far mencoder should read from the beginning of the file; this defaults to `696mb' because that position hits the 700MB quite well. Take a look at the file `split--find_env.log'. The last line that starts with `Pos:' will look similar to this: Pos:4150.0s 103751f (49%) 2663fps Trem: 0min 1395mb A-V:0.040 [1288:115] Now you know that the split position should be at second 4150 or some seconds before. To find such a position you will start playback somewhere around 4100s. 3.3. find_key Syntax : dvd2divx split find_key