===============================
= Documentation / Description =
===============================
vdrip.pl for GNU/Linux - (for Perl) - dated: 2009-08-18

VDRIP description
=================
VDRIP is a stand-alone encoding utility used to convert MPEG2 format
Videos (TS or PS). It compacts them efficiently and produce high quality
mpeg4 .avi files (XviD,DivX).

The videos in MPEG2 format have usually an extension .mpg  .mpeg  .m2t
or  .vob  and you get them when you record TV or Satellite programs with
a DVB adapter installed in your computer.
Internally, this utility uses the well known MPLAYER and MENCODER
softwares (see web site http://www.mplayerhq.com).
vdrip.pl is a free software running on GNU/Linux and released under the
GPL License. It is supplied as an 'all in one' file.

There is no GUI (Graphical User Interface). Everything is done in a
Terminal or Console window : it is an easy way to produce mpeg4
multimedia files.


Introduction
============
VDRIP is a stand-alone encoding utility used to convert MPEG2 format
videos (TS Transport Stream or PS Program Stream).
The purpose is to get more compact files to be stored in your personal
video library in a standard way, and to be able to use them for playback
by multimedia boxes or any mpeg4 capable devices.

The chosen final format is mpeg4 with the .avi containers.
It is the most widely used in many kinds of platforms.

The files produced by VDRIP are of very high quality.

vdrip need a GNU/linux distribution with mplayer and mencoder correctly
installed and fully functional. The Perl package is also a requirement.
Most of distributions already supplies theses requirements.

Since there is no GUI (Graphical User Interface), everything is done in
a Terminal or Console window : it is very simple! You have to enter a
command that generates a script file, then, you only have to execute it
(now the 2 steps can be done in one command).

So, as you know, VDRIP creates a script file for each MPEG2 movie that
you want to rip. After the conversion the final movie will have a
standard format : AVI file container MPEG4 format, XviD/DivX compatible).

All the jobs is done for You ! No need to learn, configure, install and
review many windows with parameters or configuration steps: everything
is already in it!

The necessary steps you will have to do are:

- open a Terminal or Console window on your favorite GNU/Linux
distribution
- enter a command to use vdrip.pl with the name of the mpeg2 file that
you want to convert as a parameter
- after this step vdrip.pl give you the name of the generated script to
use for the next step.
- you execute this script file in the same Terminal window (it is an
ordinary bash shell file) whenever you want. This is the ripping process.
- After a while you get the mpeg4 movie file, the filename is displayed
when the rip ends. 
- That's all.

By default, all the files are in the current directory.

The rip process may takes one to four hours (more or less, depending on
the video length and the power of your computer).
I get 3 hours for a 1:45 hour movie ripped in one-pass mode on one of
my systems (Pentium4 2Ghz), it is quite good for an old machine.
After the ripping step, you get the movie in the filename with a .avi
extension ready for use!
The quality is very high since VDRIP uses the HQ codec 'lavc', supplied
by MENCODER.

After the ripping process, you would probably want to cut advertisements
credits the beginning or end of the movie.
This is another optional step that can be done with one of your favorite
utilities like Avidemux.

About the MPEG2 format
======================
Theses files are mostly created on a computer when you record the
programs with a digital TV card installed in it.
Also, the device can be a USB pen which integrates a digital TV tuner.
For instance: your computer has a DVB-T adapter to receive the Digital
TV programs or a DVB-S adapter to receive the Digital Satellite TV
programs.
When you record programs that way, the resulting file usually has the
well known MPEG2 format. vdrip.pl is designed to process them to get a
more convenient and compact format to store them on your PC disks.

Remember the mpeg2 format produce very large file, as 2 Gb per hour of
movie. vdrip.pl reduces this size by four (approximately):
- 1 Gb per two hours of movie in high quality profile (fast motion at
  920kbs bit rate) - or a little smaller -:
- 700 Mb for a 1:35 hour movie at the standard quality profile (860 kbs
  at the default bit rate)
This is very compact and it the job the codec used by vdrip.

Thanks to the mplayer and mencoder team and all the persons of the
ffmpeg lavc project! (see: "More information" chapter).

Keep in mind that the resulting conversion is very high, anyway.
The words "high" "standard" "profile" here are only used in the vdrip.pl
terminology, for comparing technical results in a more human way. I
should say: "very good result" or "very very very good result" !

I hope you know everything about XviD, DivX and MPEG4.

What vdrip.pl DOES
==================
First, it runs in a console or Terminal windows on GNU/Linux. You will
have to execute the vdrip.pl file with the Perl command.

VDRIP generates a bash script file automatically : the standard
parameters have been chosen to get high quality mpeg4 encoding, keeping
the final video size compact.

A movie of 1:30 to 2:00 hours is reduced to less than 1 Gbytes, without
taking too much time to process.

All the processing is done by VDRIP, and they are greatly optimized.

The quality is very high because VDRIP uses the HQ codec "lavc" supplied
by MENCODER
  (see: http://www.mplayerhq.hu/DOCS/HTML/en/encoding-guide.html)

VDRIP is based on the explanations and the recommendations found in the
mencoder documentation, in the MPEG4/DivX chapter
  (see: Chapter 13. Encoding with MEncoder)

Since it relies on MENCODER, the video and sound tracks should always
keep synchronized (Audio/Video synchronization) even for .m2t movies
(MPEG2-TS).
This is not always the case for other converter tools.

Let's look at some VDRIP technical details, by default:

- vdrip.pl uses its 'cropping' function (crop detection). It means that
  it removes (crops) the black bands over and below the movie image
  (and also for the left and right borders if they exist).
  It is very important to do cropping : the quality you gain worth it
  greatly. You make sure to get the best results for a shorter size of
  the final file.
- It preserves the Aspect Ratio. You might have seen movies where humans
  have egg heads. vdrip.pl preserves the MPEG2 ratio when it rescales,
  while using the largest picture size.
- It desinterlaces the video (MPEG is originally designed for TV device)
- The rip process is done in an ONE-Pass conversion. If you need a
  better image quality use the 2-Passes mode (see further).

Getting Started - Quick Start
=============================
- Please read the prerequisites chapter to check if your computer can
  run VDRIP. Normally there is no reason why VDRIP won't run on your
  computer with a modern GNU/Linux distribution : it might include the
  standard software packages like Perl, mplayer and mencoder.

  If mplayer is running correctly when playing back a movie, and if
  mencoder and Perl are also installed on your computer.. Let's start!

- Open a Terminal or console window, as an ordinary user. Go in the
  directly where the mpeg2 file is.
- Enter the vdrip.pl command like :

  perl vdrip.pl /home/myname/myholidays.m2t <ENTER>

  where "myholidays.m2t" is an example of a MPEG2 file (no space,no
  special char).
  vdrip.pl is the perl utility filename ending by .pl
  and we assume that everything is in the current directory.

- You will see a playback of one part of the file. Keep it playing!
  Wait until video playback stops (it is the crop detection sequence).
  You should see a section of the movie itself, because vdrip.pl will
  use the parameters detected by this analyze sequence. If not, the
  video format or aspect may be wrong!

- Very soon, after about 10 seconds, VDRIP gives you the filename of
  the script that it has generated: it is the same filename than the
  MPEG2 file, but with a ".sh" extension.

- To vdrip the video, enter the script command as it is. For example:
  /home/myname/myholidays.sh <ENTER>

- That's all. After a couple of hours, you will get a file whose
  filename counterpart begins by "myholidays" and finishes by ".avi".
  It is your mpeg4/DivX movie ready for use.

- Play it with your preferred movie player (MPlayer, Totem, Xine, VLC,
  XFmedia). 

- Now, you can retouch it (cut the advertising etc...) with your
  favorite software.

Notice: Do you want an all-in-one sequence ? Ok! but please check that
  the movie is correctly viewed during the crop detection sequence:

  perl vdrip.pl /home/myname/myholidays.m2t -rip1 <ENTER>

Prerequisites
=============
- GNU/linux distribution
- Perl language
- mplayer and mencoder

VDRIP runs on GNU/Linux, with a standard Perl package installed. Any
modern GNU/Linux distribution might include it.
No specific Perl module is necessary.

mplayer and mencoder are packages requirements.
If they are not installed,in a superuser console, enter the command:
# apt-get install mplayer mencoder

(may change according to your specifi distribution).
You may downloaded them from http://www.mplayerhq.hu/

VDRIP has been developed and intensively tested on the GNU/Linux
distributions Ubuntu since 8.04 with many multimedia files.

Before to use it you should test if you can play back the video that
you want to vdrip. It is an essential step to make sure mplayer can
read and display it!
If you cannot see the picture or if the sound is not here, you SHOULD
SOLVE THE PROBLEM BEFORE to use vdrip.pl because it will not work!
Search the web, the solutions are here.

Here, I describe 2 examples of problem that I remember and that I had
to solve a long time ago... They may help you.

Problem : the video did not appear on the screen while mplayer playback.
Solution: Need to create a file in /home/myname/.mplayer/config and put
a line "vo=x11" (without double-quotes).
Or try to change parameter in the menu: mplayer>preferences>Video
select "x11" (as the available driver). Restart mplayer.

Problem : Cannot hear the sound of videos while mplayer playback.
Solution: Need to configure in the menu: mplayer>preferences>Audio
select "alsa" (as the available driver). Restart mplayer.


Differences with other similar softwares
========================================
VDRIP is a command line product : there is no GUI (graphic interface).
VDRIP may replace some other graphical products with great and many
advantages.
It is faster to start with it, you spend less time to get successful
results. You don't have to review many configuration windows or tabs.
If you are looking for a compact and easy command line utility to rip
your mpeg2 videos, it worth to try.

The author wanted to make everything very easy and powerful for an end
user, keeping in the idea that the movies could be read on the most
widely used devices.

The main goals were to make sure :
  . the user won't have to spend time to learn it
  . keeping everything user friendly and efficient

Since the product need not to be installed, configured, you won't loose
your time to make many tries until you get the expected results, because
  . the standard parameters and environment are already configured
  . no technical aspects to study before to start
  . no many complex graphical windows, tabs or menus to review and
	dialog boxes to click.

Just read the Getting Started Section how to generate a script file and
execute it, that's all! To start with it, I would recommend: do simple
and do everything as it is explained in the quick start chapter before
testing advanced options.


The future of VDRIP, will it be enhanced ?
===================
- The utility is ready to release many other functions to make it a 
  complete product (some of them are already implemented). 
  It depends on You ; please take some of your time to make a report
  and say what you think about it, ask for the functions you need.

- The script file supports the 2-Passes sequence, give "2" as parameter:
  /home/myname/myholidays.sh 2 <ENTER>  (will do a 2 passes encoding)

- The script file supports a quick test mode, give "0" as parameter:
  /home/myname/myholidays.sh 0 <ENTER>  (to make a ~30 seconds encoding)

- An advanced mode for experienced users is available. It is called 
  expert mode and is enabled given the -xpert option on the command line.
  It allows:
  . to use profiles, their implementations has begun.
  . the adjustment of parameters to get even more different results
  . a powerfull debugging mode.
  Most users may not need it.

- Remember: today VDRIP does all the complex processing for you:
  and the actual released version is fully functional.
  I am using it to record Satellite programs, documentaries, and
  musical shows on my computer when I am not at home.

VDRIP Limitations:
=================
In the actual release of vdrip.pl, you should consider:

- A video that you rip will be done with "optimal" parameters.
  Chosen parameters are quite good for general use:
  video at 860 Kbps, sound track mp3 at 128 Kbps max quality, with a
  one-pass encoding sequence by default.
  Frames are desinterlaced.
  It is a good quality for most movies and documentaries.

- The naming convention used by vdrip for .avi file is special:
  the final .avi filenames may be very long. It has been designed to
  embed inside the name many technical data in compact form.
  Also the other purposes were to make possible many ripping samples
  with more than one resulting file.
  Rename the file if it does not please you.
  Report an enhancement to get rid of it if it is really annoying.

- It is not designed to backup DVDs (There are so many other tools),
  same for mpeg1 or other multimedia files.

- Case of one file containing two movies with different aspects
  (i.e. one is 720x576 pixels, the other is 544x576 pixels)
  You cannot use directly vdrip.pl. First you must :
  . convert your video file in format MPEG2-PS (only if it is in 
    MPEG2-TS), you can use the projectx/mplex suite to do so.
  . Once you get the MPEG2-PS file, use Avidemux utility to cut it in
    two pieces. Don't use Avidemux to cut MPEG2-TS movies directly
    because the audio and video tracks may be desynchronized.

   When 2 movies have different technical characteristics they must be
   extracted and stored in two separate files.

- Case of a movie with subtitles inside the black bands below the movie
  image :
  As you know, vdrip.pl has an optimized crop detection function : it
  detects the black bands and cut them.
  Unfortunately, in this case, the subtitles will be deleted!
  Solution: Since version [18f] vdrip.pl has an option to deactivate
  the crop detection: -nocrop  . Use it as a command line argument :

  perl vdrip.pl /home/myname/myholidays.m2t -nocrop <ENTER>

  When you use the "-nocrop" feature you won't see any movie playback
  on the screen. It is normal since the cropdetect feature is disabled.
  In manual mode use command 'gn' (generate-file with nocrop).

- Case of movie recorded on a channel that supplies two sound tracks
  (for example : Arte may broadcast their programs in French and German
  simultaneously - Euronews in 6 languages).
  A MPEG2 file may contain 2 or more audio sound tracks.
  Since the default sound track has no meaning (it may be any language
  and the their numbering is totally conventional), vdrip.pl
  automatically set the language code in mplayer and mencoder for you.
  VDRIP computes the parameter language from the one it has found in
  the system global variables. You have nothing to do.

RECOMMENDED TOOLS:
=================
Avidemux : graphical utility to edit video files (cut the Ads, or 
  sequences). Please don't edit MPEG2-TS files directly because it has
  not been designed for them.

Projectx and mplex: to convert MPEG2-TS to MPEG2-PS video files
  it is a requirement if you want to cut MPEG2 movies before to rip
  them with VDRIP. You can use an other tool that fully support the
  MPEG2-TS format.

Mediainfo: display technical and tag information of most video and
  audio files (very useful, I have given some help to this project).

Kaffeine : scheduled records of Digital TV and Satellite programs
  if you have a supported DVB-T or DVB-S card in your computer. It can
  be used to search programs multiplex and to play back them with EPG
  information.

MORE INFORMATION
================
There is much more information about conversion of MPEG2 files to MPEG4
on many web sites.
Besides the already mentioned documentation and quick start procedures,
this is the most interesting:

see:
http://www.mplayerhq.hu : main mplayer/mencoder web site
http://www.mplayerhq.hu/DOCS/HTML/en/encoding-guide.html :
  mencoder site, more specifically for encoding in mpeg4

FREQUENTLY ASK QUESTIONS: (to continue)
========================
SCRIPT FILE:
1- can I modify the bash script to change the video bit rate ?
   Answer: yes! and you can modify in the same way :
   . the audio bit rate
     or to use -ab option on the vdrip.pl command line (audio bit rate)
   . the "black-and-white" flag (if movie is in B&W,results are better)
     or to use -bw option on the vdrip.pl command line (black&white)
   . the language code for Satellite program audio track if satellite
	programs comes with a different one.

2- the sound track language is not correct, how can I fix it?
   Answer: you can configure it in mplayer configuration file, for
   instance add a line "alang=fr" in /etc/mplayer/mplayer.conf to 
   select the French language soundtrack by default.

# End

