README for cripple CD ripper
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Cripple is a basic CD ripper that - as it comes - uses CDparanoia/cdda2wav and
BladeEnc/LAME to rip + encode tracks from a CD.

Cripple retrives naming information for filenames and ID3 tags from the freedb
(http://www.freedb.org) or local xmcd/cddb format files, which it can write.
freedb access is implemented via HTTP (1.0/1.1), and works through proxies.
There is built-in support for writing ID3v1.1 tags to output files.

On the majority of UNIX-ish systems cripple requires no special libraries,
interpreters or such. However by its very nature it requires a comand line
ripper such as cdparanoia or cdda2wav and an encoder such as lame or bladeenc.

Getting cripple:
----------------
currently (May 2005) the homepage for cripple is,

	http://www.vortex.prodigynet.co.uk/cripple/


Contact:
--------
send suggestions, bugs etc. to,

	 cripple@vortex.prodigynet.co.uk


Copying / modifying:
--------------------

cripple is released under the GNU Public License. see COPYING for details.


What it does do:
----------------

	- Query freedb (or read file) for Artist, Album, Year, Genre and
	  Track names.
	  
	- Save freedb responses to a files so you can query a load of CDs
	  in a couple of minutes and rip them later.
	  
	- Use CDparanoia/cdda2wav + BladeEnc/LAME to produce MP3 files named,
	  'Artist - Album - Track no. - Track name.mp3' or
	  'Album - Track no. - Artist - Track name.mp3' (for compilations).
	  
	- Slap an ID3v1.1 tag on each file's virgin ass with Artist, Album,
	  Year, Genre, Track no, Track title (+ optional comment) fields.

	- Automatic name capitalisation using a variety of algorithms.

	- Work with HTTP proxies.

	- Read mode2-form1 data tracks for cd copying (work in progress!).

	- Identify and avoid data tracks


What it does not do:
--------------------

	- Use EXTD / EXTTn cddb entries to make comment for ID3 tag.

	- Convert '\n' '\t' '\\' in cddb info as specified by the CDDB
	  protocol specification - they are pretty stupid in filenames or
	  ID3v1 tag fields.

	- rip hidden tracks (track 1 index 0), neither CDparanoia or cdda2wav
	  can do this (TODO).

	- deal with tracks recorded with preemphasis (TODO).

	- retrieve CDtext (TODO)

	- produce any PCM type output (raw,wav etc.) (TODO).

	- submit data to the freedb (possible TODO)


Instaling:
----------
see INSTALL


COMPATIBILITY / PORTING:
------------------------
most of cripple should require only minor tweaks to build and run on untested
UNIX-like systems, however, the code in disc.c to access the CDROM drive, read
the TOC etc. is specific to the kernel's CDROM interface. Currently 4
interfaces are supported: Linux/Solaris, Free/NetBSD etc.,  DEC OSF/1 and
win32-NT. Only linux and cygwin/win2k have been extensively tested. Porting to
other UNIXis OSes should mostly involve adding/fixing code in disc.c.

Porting to native win32 would be a lot of work, but running under Cygwin works.
For cygwin/win32-NT your best bet for a ripper is probably libcdio's version of
cdparanoia called cd-paranoia. Apart from sometimes getting the endian-ness
wrong, it should work as well as cdparanoia on linux.


Use:
----
see manpage e.g. 'man ./cripple.1'


TODO:
-----

- retrieve TOCs for every session on a cd so we get track lengths right.
- use a runtime config file for people with compiler-phobia.
- user-specified filename format (life would be easier if everyone used a
  single, sensible format).
- add detection and support for ripping hidden tracks (pre-gap of 1st track).
  neither cdparanoia or cdda2wav seem to have support for this.
- do ripping ourself? (using libparanoia???), needed for above.
- have some way of performing deemphasis (cdda2wav?)
- produce some sort of rawish (raw,wav etc.) output and info/toc files for cd
  copying using cdrdao/cdrecord. idea would be to write wav at same time as mp3
  to save reading the cd twice to rip+copy.
- user selection of entry to use when we get an inexact/multiple cddb match.
- info page.

Acknowledgements / links:
-------------------------

	- discid by Jeremy D. Zawodny	http://freshmeat.net/~jzawodn/
	- CDparanoia			http://www.xiph.org/paranoia/
	- libcdio			http://www.gnu.org/software/libcdio/
	- BladeEnc			http://bladeenc.mp3.no
	- LAME				http://www.mp3dev.org
	- FLAC 				http://flac.sourceforge.net/
	- The folks at freedb		http://www.freedb.org
	- cdda2wav by Heiko Eissfeldt
	
	
BUGS: Probably lots (especially with the HTTP stuff), but it ussually works
----- for me.

      cdda2wav/cdparanoia will use wrong track length for last track on all but
      the last session when using kernel cd driver rather than scsi (see TODO).

