RipIt version 3.3.7 23/04/05
Originally written by Simon Quinn, now maintained by Felix Suwald
Web Site: http://www.suwald.com/ripit/ripit.html


What Is It?
-----------
RipIT is used to create MPEG-1 Layer 3 or Ogg Vorbis or Flac
(mp3/ogg/flac) audio files from an Audio CD. It is simply a front-end,
written in perl, for these excellent programs:
    * "dagrab", "cdparanoia" etc. for ripping the audio CD tracks
    * "Lame", "OggVorbis" or "Flac" for encoding the wav files
    * "CDDB_get" for CDDB retrieval

It runs in text mode (no fancy GUI here) and does everything required
to produce a set of mp3/ogg/flac files without any user-intervention.
This program does the following with an Audio CD:
    * Get the audio CD Album/Artist/Tracks information from CDDB
    * Rip the audio CD Tracks (using dagrab or other cdrippers)
    * Encode the files (using lame, oggvorbis and/or flac)
    * ID3 tag them (v1 & v2)
    * Optional: creates a playlist (M3U) file (lists MP3s created,
      used by various MP3 players)
    * Optional: Prepares and sends a CDDB submission.
    * Optional: Saves the CDDB file.


Installation
------------
If you use the tarballs instead of the rpm-package, then there is no
installation required for the program itself, but the following software
MUST be installed and in your PATH:

* perl v5 - will most probably already be installed

* cdda2wav - will most probably already be installed or
  cdparanoia - will most probably already be installed or
  dagrab v0.3.5 - http://web.tiscalinet.it:/marcellou/dagrab.html or
  tosha or cdd

* lame v3.89 or later - http://lame.sourceforge.net/  or
  oggenc (from OggVorbis) - http://vorbis.com  or
  flac - http://flac.sourceforge.net/index.html

* CDDB_get perl module - to install do the following:
        Login as root and connect to the Internet
        Enter "perl -MCPAN -e 'install CDDB_get'"
        Should be successful so exit by pressing "q"
        Please check that you use the newest version,
        at least version 2.22 - http://armin.emx.at/cddb/ !


Calling RipIT
-------------
Either type ./ripit.pl in the directory where ripit.pl resides,
or as a root user, create a link in your /usr/bin (or whatever)
directory:
# ln /path/to/ripit.pl /usr/bin/ripit
Now you should be able to start the script by typing ripit only.


Configuring RipIT
-----------------
There are some user configurable parameters for the program and these
are located at the top of the program. You may use option --Save to save
your own paramteres in a config file saved in ~/.ripit instead of
editing the source code itself.

  $cddevice       - is the cdrom device used for ripping,
  $output         - where the ripped & encoded files will go,
  $ripper         - set to 0 for dagrab, 1 for cdparanoia, etc.
  @coder          - Comma seperated list, 0 Lame, 1 OggVorbis, 2 Flac.
  $bitrate        - bitrate for lame, if --vbrmode used, bitrate is
		      equal to the -b option, so one might set it to zero!
  $hirate         - Bitrate for Lame, if --vbrmode used, hirate is
		      equal to the -B option.
  @quality        - Comma seperated list: quality for lame in vbr mode
		      (0-9), best quality = 0, quality for ogg (1-10)
		      best = 10; or compression level for Flac (0-8),
		      lowest = 0.
  $genre          - genre of Audio CD for ID3 tag,
  $year           - year of Audio CD for ID3 tag,
  $utftag	    - if zero decode utf tags to ISO8895-1.
  $eject          - eject the CD when done (1 yes, 0 no),
  $halt           - shutdown machine when finished (1 yes, 0 no),
  $savepara	    - Save parameters passed in cofig file.
  $submission     - do ask for CDDB submission (1 yes, 0 no),
  $playlist       - do create the m3u playlist file (1 yes, 0 no),
  $interaction    - if 0 do not ask anything, take the 1st CDDB entry
		      found or use default names! (1 yes, 0 no),
  $underscore     - use _ instead of spaces in filenames
                    (1 - yes, 0 - no),
  $lowercase      - lowercase filenames (1 yes, 0 no),
  $archive        - save CDDB files in ~/.cddb dir (1 yes, 0 no),
  $mirror         - the host (a freedb mirror) that shall be used
                    instead of freedb (default).
  $transfer       - Transfer mode, cddb or http, will set default port
                    to 8880 or 80 (for http).
  $vbrmode	    - Variable bitrate, only used with lame,
		      (new or old), see lame-manpage.
  $proxy          - set the proxy.
  $mailad	    - Users return e-mail address, used for sumitting
		      a CDDB entry.
  $nice	    - Set nice.
  $CDDB_HOST	    - Set cddb host.
  $dirtemplate    - contains a template of the directoryname that will
                    be used (see below for more information).
  $tracktemplate  - contains a template of the filename that will be
                    used (see below for more information).

  Not yet used:
  $cdopt          - additional options for the cdaudio ripper
  $encopt         - additional options for the mp3 encoder


Of course being a perl programer you can easily configure anything in
the program to your taste. Please inform the maintainer if you made some
improvements! You find my e-mail address at the bottom of this file.


Setting the Templates
---------------------
The dirtemplate and tracktemplate contain the format of the directory
and filename for the output directory and tracks.
These variables are later eval'd by perl so you can put any legal
variables and characters in here you like. The '" and "' are important
and MUST surround the template.
Variables you may want to use:
  $album     - CD album name
  $artist    - CD artist name
  $genre     - CDDB genre or the genre passed from command line
  $tracknum  - number of the current CD track
  $trackname - name of the current CD track
  $year      - CDDB year or the year passed from command line.

Example:
  '"$tracknum $artist - $trackname - $genre"' would produce:
  07 The Game - Swandive - Trip-Hop


Using RipIt
-----------
Insert an audio CD and type "./ripit.pl" or simply "ripit" as mentioned
above. The program will then merrily go away and rip/encode the whole
audio CD unless it encounters a problem.

First the album/artist/track/genre(IDv3)/year/category(CDDB) information
is retrieved from CDDB via the internet. If not connected to the inter-
net (or no CDDB entry is found), you will be prompted to choose either
if the tracks shall be ripped with default names or manually entered
names, except if the option --nointeraction was passed.
Then you will be asked, if you want to make a CDDB submission or correct
an existing one. In the second case, you can confirm the CDDB settings
with Enter. Submission to freedb-submit@freedb.org is gruanted, if you
changed at least one single entry and if the nail (mail) shell-command
works. If you told RipIT having no connection to the internet (with
option --nosubmission), the file cddb.toc will be saved in the home
directory, and you can submit it later.
But even with option --nosubmission RipIT will try to do a CDDB lookup,
and if it finds something, you only have to edit the entry, i.e. this
option only prevents you from sending the file directly! Be aware that
the subject of the mail must be exactly as displayed by RipIT.

The sound files will be put into a directory with the format according
to the directory template, default setting is:
$OUTPUTDIR/Artist - Album/
with the track name consisting of the track number and songname (or
whatever is specified in the track template).

The sound files will automatically be id3 tagged. The tagging is
performed by the encoders, which use both id3v1 & id3v2.

The following options are available, case sensitive!, and
therefore non-ambiguous, so you may use -S instead of --Save!

ripit.pl [--device cddevice] [--outputdir dir]
         [--dirtemplate '"...$parameters..."']
         [--tracktemplate  '"...$parameters..."']
         [--ripper cdripper] [--coder encoders]
         [--quality qualities] [--bitrate rate]
         [--vbr-mode old or new] [--hirate rate]
         [--archive] [--genre genre] [--playlist]
         [--year year] [--lowercase] [--underscore]
         [--transfer cddb or http] [--proxy path]
         [--mirror TLD] [--cddb server] [--Save]
         [--interaction] [--submission] [--halt]
         [--eject] [--nice adjustment]  [--Help]
         [--version] [--mail address]
         [track_selection]

[track_selection]     - Tracks to rip from. If not specified all tracks
                        will be ripped. You can also specify a single
                        track by using a single number, or a selection
                        of tracks using numbers separated by commas or
                        hyphens, i.e. 2,6,10, or 3,5,7-9 .
                        Using a number followed by a comma or hyphen
                        will rip from that track to the end of the CD
                        i.e. 3,5- rips track 3 and from track 5 to the
                        last one.
--bitrate [rate]      - Encode mp3 at this bitrate for lame, if
			   --vbrmode used, bitrate is equal to the -b
			   option, so one might set it to zero
			   (default 128)!
--hitrate [rate]      - Bitrate for lame using --vbrmode,
			   hitrate is equal to the -B option.
--device [cddevice]   - Path of audio CD device.
--ripper [ripper]     - Cdripper to use, 0 - dagrab, 1 - cdparanoia,
                        2 - cdda2wav, 3 - tosha, 4 - cdd.
--coder [encoder]     - Encoder to use, 0 - Lame, 1 - OggVorbis,
                        2 - Flac, comma seperated list!
			   E.g. --coder 2,0,1 --quality 3,5 will set
			   Flac-quality to 3 and Ogg-quality to 5.
			   What about Lame-quality? As lame does not
			   need quality for constant-bitrate, it assumes
			   that no quality is used, but sets it to the
			   lame-default value of 5 for the case one uses
			   vbr mode! Better use
			   --coder 2,0,1 --quality 3,5,5 .
--quality [quality]   - Comma seperated list in the same order than the
                        list of encoders passed!
                        Quality for ogg (1-10) highest = 10;
                        or compression level for Flac (0-8),
                        lowest compression = 0; or quality for Lame
                        in vbr mode (0-9), best quality = 0.
--outputdir [dir]     - Where the sound should go.
--genre [genre]       - Overrides CDDB genre, must be a valid LAME genre
                        name if using Lame, can (but shouldn't) be
                        anything if using other encoders.
--year [year]         - Tag MP3 with this year.
--mirror [TLD]        - Choose "freedb" or one of the freedb.org
                        mirrors, e.g. "at".
--transfer [mode]     - Transfer mode, cddb or http, will set
                        default port to 8880 or 80 (for http).
--vbrmode  [mode]     - Variable bitrate, only used with lame,
			   (new or old), see lame-manpage.
--cddb [server]       - CDDB server (default freedb.org).
--proxy [address]     - Set the Proxy address.
--mail [address]      - Users return e-mail address, used for sumitting
			   a CDDB entry.
--dirtemplate ['"...$parameters..."']
--tracktemplate ['"...$parameters..."']
			 - Use single AND double quotes to pass the
		          templates! Allowed are following parameters:
			   $album, $artist, $genre, $trackname,
			   $tracknum and $year, e.g. '"$artist - $year"'
			   (default dirtemplate: '"$artist - $album"'),
			   (default tracktemplate: '"$tracknum $trackname"').
--nice [value]        - Set niceness of encoders.

OPTIONS without argument (may be negated, e.g. --noplaylist):
--eject               - Ejects the CD when finished
                        if your configuration supports it.
--halt                - Powers off the machine when finished
                        if your configuration supports it.
--submission          - Specify --nosubmission if the box is offline
                        and the created file cddb.toc shall be saved
			   in the home dir instead of being submitted.
			   With option --archive it will also be saved
			   in the ~/.cddb directory.
--playlist            - Do create the m3u playlist file (1 yes, 0 no).
--interaction         - Specify --nointeraction if ripit shall take
			   the first CDDB entry found and rip without any
			   questioning.
--archive             - Save CDDB files in ~/.cddb dir.
--lowercase           - Lowercase filenames.
--underscore          - Use _ instead of spaces in filenames.
--utftag		 - If negated decodes tags to ISO8859-1.
--help                - Print this and exit.
--version             - Print version and exit.
--save                - Save parameters passed on command line to
			   config file. If you want to save the config file
			   without ripping, add option --Version and
			   nothing else will be done!


Program Notes
-------------
Most of the output to the screen is produced by the cdripper program.
The encoder output goes to /dev/null, since it's not important compared
to the cdripper output, and it only clutters.

The only encoder information printed to the screen is its progress in
the format "Encoding track x of y".

The encoding is started as a separate thread from the rest of the
program so that the encoder works in the background as the cdripper is
working.


Original Author's Comment
-------------------------
This is my first bit of perl code and I've only spent a few days writing
it so I hope you won't be too critical. I wish I had got around to
learning perl much earlier as it is a very powerful but easy to use
language.

I would be grateful for any suggestions on how to improve the code or
write better perl.

Why did I write this when there are so many other CD ripper front ends?
There are some very good Linux programs out there that all do similar
things but none of them did exactly what I wanted, which spurred me into
writing this and at the same time learn perl.


Cheers
Simon Quinn, Lancashire, UK and Mads Martin Joergensen, Odense, Denmark


Felix Suwald's Comment
----------------------
Same as author's comments! Except that one should read *changing*
instead of *writing* ;), and the writing I made is not *clean*...
Some months later, and with about 1000 lines more, I hope to code
a little better, but I still consider myself as a total greenhorn ;).
The main changes are:
1) one can use hyphens (-) in track selection. I missed it, because I
   often have audio CDs with a data (video) track in the end, so I
   wanted to avoid ripping that last one!
   Now, one can enter 1-10 instead of 1,2,3,4,5,6,7,8,9,10. You even may
   mix commas and hyphens: 1,3-5,9- .
2) As mentioned in "Using RipIt", I excpected ripit to do the job if the
   box is off-line, but it did not work with me... now it should work!
3) As mentioned in "Using RipIt", I also excpected ripit to do the job
   if no parameters are given. This did not work, but should work now!
4) I wanted to submit new CDDB entries to freedb.org. After using RipIT
   I did not want to reenter the data in grip, kscd or whatever.
   Now it should work with RipIT.
   If your submission is not OK, it will be returned to the e-mail
   address you entered. Edit it and resubmit it.
5) I never could remember the genre numbers for id3v2 tags. Now you
   can enter (a part of) the genre name, and if there are several
   possibilities, then you will be prompted to choose the one you want.

See HISTORY-file for a more detailed change-log.

Cheers
Felix Suwald, Zurich, Switzerland

Please send bugs/comments/whishes to: ripit[_at_]suwald[_dot_]com
