RipIt version 3.5.1 16/06/06
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, Ogg Vorbis, Flac, Faac or Wav
(mp3/ogg/flac/m4a/wav) 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" "Flac" or "Faac" 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/m4a 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 cdparanoia or other cdrippers)
    * Encode the files (using lame, oggvorbis flac and/or faac)
    * 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
------------
There is no installation required for the program itself.  To install it
correctly (with man-page, config file and the ability to call the script
by typing ripit only), either use the rpm-package or the Makefile in the
tarball. Then type (as root)

make install

and you are done.


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
  faac - http://www.audiocoding.com

* CDDB_get perl module - to install do the following:
        Login as root and connect to the Internet
        Enter "perl -MCPAN -e 'install CDDB_get'"
        Please check that you use the newest version,
        at least version 2.22 - http://armin.emx.at/cddb/ !
        Note that there is a newer version: 2.27 to be used!


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


Configuring RipIT
-----------------
There are some user configurable variables for the program and these are
located at the top of the program.  Use options  --savenew  or --save to
save your own paramteres in a config file located in ~/.ripit instead of
editing the source code itself. Do not edit the source code anymore!  It
may be easier to edit the config file with an editor instead of reenter-
ing all your parameters on the CL.

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 (even /) 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 tracktemplate:
  '"$tracknum $artist - $trackname - $genre"' would produce:
  07 The Game - Swandive - Trip-Hop

Example dirtemplate:
  '"$artist $year/$album"' would produce a "2-level" directorytree:
  Swandive 1997/Intuition/

Using RipIt
-----------
Insert an audio CD and type "./ripit" 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/year/category(CDDB) information is
retrieved from CDDB via the internet. If not connected to the internet
(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. With the option
--archive, RipIT also checks for CDDB entries on your machine in the
~/.cddb directory.
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:

ripit [--device|d cd-device] [--outputdir|o path] [--ripper|r cdripper]
      [--ripopt options]  [--wav|w]  [--disable-paranoia|Z]  [--encode]
      [--coder|c encoders-list] [--faacopt options] [--flacopt options]
      [--lameopt options] [--oggencopt options] [--quality qualities-list]
      [--bitrate|b rate] [--maxrate|B maxrate] [--vbr-mode|v old / new]
      [--preset|S mode]  [--comment id3-comment]  [--genre|g genre-tag]
      [--lowercase|l] [--underscore|u] [--utftag|U] [--year|y year-tag]
      [--dirtemplate '"$parameters"'] [--tracktemplate '"$parameters"']
      [--cddbserver|C server] [--mirror|m mirror]  [--protocol|L level]
      [--proxy|P path]  [--transfer|t cddb or http]  [--mail|M address]
      [--submission|s] [--interaction|i] [--nice|n adjustment] [--halt]
      [--eject|e] [--help|h]  [--lcd] [--lcdhost host] [--lcdport port]
      [--sshlist remote machines] [--local] [--scp] [--config] [--save]
      [--savenew] [--archive|a] [--playlist|p] [--infolog path] [--rip]
      [--cdtoc number] [--loop] [--verbose|x number] [--chars|W [list]]
      [--normalize|N] [--normopt|z options] [--version|V]
      [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)! Bitrate can be turned off with
			   parameter "off".
--maxrate [rate]	 - Bitrate for lame using --vbrmode,
			   maxrate 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.
--ripopt [options]	 - Options for audio CD ripper.
--coder [encoder]	 - Encoder to use, 0 - Lame, 1 - OggVorbis,
			   2 - Flac, 3 - Faac, comma seperated list!
			   E.g. --coder 2,0,1 --quality 3,5 will set
			   Flac-quality to 3 and Oggenc-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 .
--lameopt [options]	 - More user defined options for Lame.
--oggencopt [options] - More user defined options for Oggenc.
--flacopt [options]	 - More user defined options for Flac.
--faacopt [options]	 - More user defined options for Faac.
--quality [quality]	 - Comma seperated list in the same order than the
			   list of encoders passed!
			   Quality for oggenc (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.
			   The qualitiy can be turned off with the
			   parameter "off".
--sshlist [list]	 - Comma seperated list of remote machines.
--scp			 - If fs can not be mounted on (remote) machine(s),
			   use scp to copy wavs to remote machines.
--outputdir [dir]	 - Where the sound should go.
--comment [comment]	 - Specify a comment (mp3, m4a), or a description
			   (ogg, flac) tag.
--genre [genre]	 - Specify (and override CDDB) genre, must be a
			   valid ID3-genre name if using Lame, can (but
			   shouldn't) be anything if using other encoders.
--year [year]         - Specify (and override CDDB) year (mp3, m4a) or a
			   date tag (ogg, flac).
--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.
--lcdhost [host]	 - Set host address for lcdproc, default localhost.
--lcdport [port]	 - Set port address for lcdproc, default 13666.
--infolog [path/file] - Log certain operations to file.
--cdtoc [number]	 - Create a cd.toc for CDRDAO (1 yes, 0 no).
--verbose [number]	 - Normal output: 2, minimal output (1), nothing at
			   all (0) (except error-messages), or be very
			   verbose (3). Default is 2.
--normalize		 - Normalize the wav files, default: off.
--normopt [options]	 - Options passed to normalize, default: -bv.
--chars [list]	 - Exclude characters in filenames (not in tags)
			   and (ending!) periods. Following characters will
			   be erased, if no argument stated: :*#?\$\!  else
			   only ending periods and all passed ones. Use
			   argument "off" to switch it off. Default off.

OPTIONS without argument (some may be negated, e.g. --noplaylist):
--config		 - Read the config file or use --noconfig,
			   default on.
--eject		 - Ejects the CD 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		 - Read and save CDDB files in ~/.cddb directory.
--lcd			 - Use lcdproc to display status, default: not set.
--lowercase		 - Lowercase filenames.
--underscore		 - Use _ instead of spaces in filenames.
--utftag		 - If negated decodes tags to ISO8859-1.
--parano		 - Do not use the paranoia mode in cdparanoia.
--local		 - Encode on local machine (default).
--wav			 - Keep the wav files.
--encode		 - Prevent encoding (do only wavs) with --noencode.
--rip			 - Prevent ripping (if wavs present) with
			   --norip. This might be useful, if someone
			   wants the same format in different qualities.
--loop			 - Continue ripping and encoding as soon as a new
			   CD is inserted. This option implies that the CD
			   is ejected when done. You may need to run as
			   root: cd /usr/include/sys; h2ph ioctl.h
--halt			 - Powers off the machine when finished
			   if your configuration supports it.
--help			 - Print a short manpage.
--version		 - Print version and exit.
--save			 - Add parameters passed on command line to
			   config file. An existing config file will be
			   saved in config.old!
--savenew		 - Save only parameters passed on command line to
			   a new config file. An existing config file will
			   be saved in config.old!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 output can be switched off with option --verbose 0.

For questions about the lcdproc feature, please contact max.kaesbauer
[at] gmail [dot] com.

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 3000 lines more, I hope to code
a little better ;).
The main changes when I started were:
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 failure at 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. Thanks to all testers
and those who send me feedback or feature requests.

Cheers
Felix Suwald, Zürich, Switzerland

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