RipIt version 3.6.0 16/06/07
Originally written by Simon Quinn, maintianed by Mads Martin Joergensen,
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 to
      "mp3", "ogg", "flac" or "m4a" ("aac").
    * "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, oggenc, flac and/or faac)
    * ID3 tag them (v1 & v2)
    * Extracts possible hidden tracks
    * Optional: creates a playlist (M3U) file
    * Optional: prepares and sends a CDDB submission
    * Optional: saves the CDDB file
    * Optional: creates a toc (cue) file to burn a CD in DAO with text
    * Optional: anaylze the wavs for gaps and splits them into chunks
    * Optional: merges wavs for gapless encoding
    * Optional: creates a md5sum for each type of sound files.


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/ to create mp3, 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 are newer versions available.


Calling RipIT
-------------
Depending on the installation, type ripit or ./ripit in the directory
where ripit resides.


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 paramters in a config file located in $HOME/.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 re-
entering all your parameters on the command-line.

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 evaluated by perl, so one can put any legal
variables and characters in here (even /).
The '" and "' are important and MUST surround the template.
Variables that may be used:
  $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
$HOME/.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 sendmail works.
If one told RipIT not to be connected to the internet (using option
--nosubmission), the file cddb.toc will be saved in the $HOME-directory,
and can later be submitted
But even with option --nosubmission RipIT will try to do a CDDB lookup,
and if it finds something, one only has to edit the entry, i. e. this
option only prevents to send the file directly! Be aware that the
subject of the e-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, Lame uses both id3v1 & id3v2.

The following options are available:

ripit [--device|d cd-device] [--outputdir|o path] [--ripper|r cdripper]
      [--dpermission number] [--fpermission number]  [--nicerip number]
      [--ripopt ripper-options] [--rip] [--disable-paranoia|Z] [--wav|w]
      [--ghost|G] [--extend seconds]  [--prepend seconds]   [--encode]
      [--coder|c encoders]  [--faacopt options]  [--flacopt options]
      [--lameopt options] [--quality qualities-list] [--bitrate|b rate]
      [--maxrate|B rate]   [--vbrmode|v old or new]   [--preset|S mode]
      [--oggencopt options] [--comment id3-comment] [--genre|g genre-tag]
      [--utftag|U] [--year|y year-tag] [--lowercase|l] [--underscore|u]
      [--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] [--ejectcmd command] [--ejectopt options for command]
      [--help|h]  [--lcd] [--lcdhost host] [--lcdport port]  [--config]
      [--save] [--savenew]  [--sshlist remote hosts] [--local]  [--scp]
      [--archive|a] [--playlist|p number]  [--infolog path]  [--md5sum]
      [--cdtoc number] [--loop] [--verbose|x number] [--chars|W [list]]
      [--normalize|N] [--normopt|z options] [--version|V]  [--resume|R]
      [--merge list] [--core numbers] [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. Default: not set
--merge ordered list of comma separated intervalls
			   Place a hyphen or a + between first and last
			   tracknumber to be merged. Separate several
			   intervals with a comma. Default: not set
--outputdir directory - Where the sound should go, default: not set.
--dpermission number	 - Define directory permissions, default: 0777.
--fpermission number	 - Define permissions of sound and log files,
			   default: 0644
--device cddevice	 - Path of audio CD device, default: /dev/cdrom.
--ripper ripper	 - Cdripper to use, 0 - dagrab, 1 - cdparanoia,
			   2 - cdda2wav, 3 - tosha, 4 - cdd, default: 1.
--ripopt options	 - Options for audio CD ripper.
--disable-paranoia    - When using dagrab, the number of retries will be
			   set to 3, with cdparanoia this option is equal
			   to the -Z option. Default: off.
--ghost		 - Analyze wav and split into possible chunks of
			   sound. This overrided option merge.
			   Default: off.
--extend seconds	 - Enlarge splitted chunk by number of seconds
			   if possible, default 6.
--prepend seconds	 - Enlarge splitted chunk by number of seconds
			   if possible, default 6.
--coder encoder	 - Encoder to use, 0 - Lame, 1 - Oggenc,
			   2 - Flac, 3 - Faac, comma separated 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 separated 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", default: 5,3,5,100.
--vbrmode mode	 - Variable bitrate, only used with Lame, mode is
			   new or old, see Lame manpage.  The Lame-option
			   quality will be changed to -V instead of -q if
			   vbr-mode is used; default: not set.
--bitrate rate	 - Encode mp3 at this bitrate for Lame. If option
			   --vbrmode used, bitrate is equal to the -b
			   option, so one might want to set it off,
			   default 128.
--maxrate rate	 - maxrate (Bitrate) for Lame using --vbrmode is
			   equal to the -B option for Lame or the -M option
			   for Oggenc, default: 0.
--preset mode		 - Use the preset switch when encoding with Lame.
			   With otpion --vbrmode new --preset fast will be
			   used. Default: off.
--chars [list]	 - Exclude characters in filenames (not in tags)
			   and (ending!) periods. The argument is optional.
			   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.
			   if your configuration supports it.
--comment comment	 - Specify a comment (mp3, m4a), or a description
			   tag (ogg, flac). Default: not set.
--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.
			   Default: not set.
--year year		 - Specify (and override CDDB) year (mp3, m4a) or a
			   date tag (ogg, flac). Default: not set.
--dirtemplate '"  foo $parameters "'
--tracktemplate '" foo $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"').
--sshlist list	 - Comma separated list of remote machines where
			   RipIT should encode. The output path must be
			   the same for all machines. Specify the login
			   (login@machine) only if not the same for the
			   remote machine. Else just state the machine
			   names. See EXAMPLES of manpage for more
			   information. Default: not set.
--scp			 - If fs can not be mounted on (remote) machine(s),
			   use scp to copy wavs to remote machines.
--local		 - Only used with option --sshlist; if all
			   encodings shall be done on remote machines, use
			   --nolocal, default: on.
--cddb server		 - CDDB server, default freedb.org. Note, the full
			   address is mirror.freedb.org, i. e. default is
			   freedb.freedb.org.
--mirror mirror	 - Choose "freedb" or one of the freedb.org
			   mirrors, default: freedb. For more information
			   check the webpage www.freedb.org. There is no
			   list of mirrors available these days. This
			   option might be obsolet as freedb uses random
			   servers, but the default setting is mandatory.
--protocol level	 - The CDDB protocol level for CDDB query. Level 6
			   supports UTF-8 and level 5 not. Default: 6
--proxy address	 - The http proxy to use when accessing the cddb
			   server. The CDDB protocol must be http! Default:
			   not set.
--transfer mode	 - Transfer mode, cddb or http, will set
			   default port to 8880 or 80 (for http).
--nice value		 - Set niceness of encoding process, default 0.
--nicerip value	 - Set niceness of ripping process, default 0.
--archive		 - Read and save CDDB files in the directory
			   $HOME/.cddb/"category". Default: off.
--eject		 - Ejects the CD when finished, default off.
--ejectcmd command	 - The command to use for ejecting CD (see --eject)
			   Default: eject.
--ejectopt options	 - Arguments to the ejecting CD command (see
			   --ejectcmd), default: path of CD device.
--halt			 - Powers off the machine when finished if the
			   configuration supports it.
--submission		 - Specify --nosubmission if the machine is offline
			   and the created file cddb.toc shall be saved
			   in $HOME instead of being submitted. With option
			   --archive the data will also be saved in the
			   $HOME/.cddb directory.
--mail address	 - Users return e-mail address, needed to submit a
			   CDDB entry. Default: not set.
--playlist number	 - Create the m3u playlist file, or use --playlist
			   0. For filenames without paths use --playlist 2.
			   Default: 1 - on.
--interaction		 - Specify --nointeraction if ripit shall take
			   the first CDDB entry found and rip without any
			   questioning, default: on.
--lcd			 - Use lcdproc to display status, default: not set.
--lcdhost host	 - Set host address for lcdproc, default: localhost.
--lcdport port	 - Set port address for lcdproc, default 13666.
--infolog path/file	 - Log operations (system calls, file/directory
			   creation) to file, given with full path;
			   default: not set.
--lowercase		 - Lowercase filenames, default: off.
--underscore		 - Use _ instead of spaces in filenames, default:
			   off.
--utftag		 - If negated decodes Lame-tags to ISO8859-1.
			   Default off.
--rip			 - Prevent ripping (if wavs present) with
			   --norip. This might be useful to encode the same
			   format in different qualities. Default: not set.
--encode		 - Prevent encoding (generate only wavs) with
			   --noencode. Default: on.
--wav			 - Keep the wav files, default: off.
--normalize		 - Normalize the wav files, default: off.
--normopt options	 - Options passed to normalize, default: -bv.
--cdtoc number	 - Create a cd.toc for CDRDAO (1 yes, 0 no).
--help			 - Print a short manpage.
--version		 - Print version and exit.
--verbose number	 - Normal output: 2, minimal output (1), nothing at
			   all (0) (except error-messages), or be very
			   verbose (3). Default is 2.
--config		 - Read the config file or use --noconfig,
			   default on.
--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!
--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
--resume		 - Resume a previously started session.
--md5sum		 - Create a MD5-sum file for each type of sound
			   files.
--core number		 - Comma separated list of numbers  giving  maximum
			   of allowed encoders to run at the same time.
			   Default: 1.


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 in between two
ripping processes is its progress in the format "Encoding track x of y"
and some more depending on verbosity.

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.


Historical 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


Historical Felix Suwald's Comment
---------------------------------
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 re-enter 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. Please specify a
subject more concise than "RipIT" when sending a mail, thanks!

Cheers
Felix Suwald, Zürich, Switzerland

Please send bugs/comments/wishes to: ripit[_æt_]suwald[_ðöt_]com with a
explanatory subject (not only "RipIT").