Grip/GCD
========

Grip is a gtk-based cd-player and cd-ripper. It has the ripping capabilities
of cdparanoia builtin, but can also use external rippers (such as
cdda2wav). It also provides an automated frontend for MP3 encoders, letting
you take a disc and transform it easily straight into MP3s. The CDDB
protocol is supported for retrieving track information from disc database
servers. Grip works with DigitalDJ to provide a unified "computerized"
version of your music collection. GCD is the cd-player only version of Grip.

Because Grip and GCD share much of their functionality, this file documents
both of them. If you installed only GCD, you should ignore the bits that
talk about "ripping" and "encoding" of tracks.


Requirements
============

To use Grip/GCD, you must have:

 o GTK+ (see http://www.gtk.org)
 o POSIX thread support (http://pauillac.inria.fr/~xleroy/linuxthreads)
 o a net connection (if you want to use CDDB lookup)
 o a CD player (surprise, surprise)

Grip is designed to work closely with DigitalDJ, my SQL-based mp3 jukebox
system (although it does not require it). DigitalDJ can be obtained from:

  http://www.nostatic.org/ddj


Installation
============

If you obtained Grip or GCD from the RPM distribution then they are already
installed. If you have the source distribution, you need to compile it.
Edit the Makefile and the header file config.h to correspond to your
system. If you are compiling GCD, just type "make gcd". If you are compiling
Grip, you need to decide whether to compile grip with cdparanoia builtin or
not.

To build with cdparanoia:

 o if you downloaded the grip source distribution *with* cdparanoia
   included, you are set. if not:

   o get the cdparanoia source distribution
   o unpack it somewhere
   o make a symbolic link "cdparanoia" in the grip source directory that
     points to it (ie: ln -s /usr/src/cdparanoia-III-alpha9.5 cdparanoia)

 o cd to the cdparanoia directory
 o configure it ("./configure")
 o do "make lib"
 o cd back up to the grip directory
 o type "make" and then "make install"


To build *without* cdparanoia:

 o type "make gripnopar"
 o if you want GCD compiled as well, type "make gcd"
 o type "make install"


Running Grip/GCD
================

Grip's usage is:

  grip [-d <device>] [-s] [-l]

    -d <device>        Use <device> as cd-rom device
    -s                 Launch in "small" (cd-only) mode
    -l		       'local' mode -- don't try to use CDDB
    -r                 Don't do I/O redirection
    -v                 Verbose (debug) mode

GCD's usage is:

  gcd [-d <device>] [-f] [-l]

    -d <device>        Use <device> as cd-rom device
    -f                 Launch in "full" (track-display) mode
    -l		       'local' mode -- don't try to use CDDB
    -v                 Verbose (debug) mode

The most handy way to launch Grip/GCD is from your window manager's doc. A
dock icon (gripicon.tif/gcdicon.tif) is included with the distribution.

Grip's operation should be pretty self-explanatory. Tracks to rip are
selected with the right mouse button. To select all tracks on the disc,
click the "Rip" column label. When you select "Rip" or "MP3-encode" from the
"Rip" page, Grip will rip or rip/encode the tracks you have selected. If you
select "Rip partial track", only the current select of the current track
will be ripped or encoded. Start/End sector values are ignored if partial
track ripping is not enabled.

Grip and GCD used to be installed as setuid root. This was for several
reasons. First, most people have their systems configured such that their
user accound does not have access to the cd drive. Secondly, cdparanoia
requires access to both the cd device and (for scsi drives) the generic scsi
device (usually /dev/sg<something>). Despite this, I no longer install the
programs setuid root. This means that you will have to set the permissions
correctly on the appropriate devices, or run the program as root.

**************************************************************************
******************************** IMPORTANT! ******************************
**************************************************************************

If you have trouble with Grip or GCD, read the "Common Questions"
section. I'm getting bogged down in email these days. This being said, I do
appreciate feedback on Grip. If, after reading through this document
carefully, you still have a question, or have a feature request, feel free
to email me. Do read the file TODO first, however, to check whether it's
already on my list.

**************************************************************************
******************************** IMPORTANT! ******************************
**************************************************************************


Configuring Grip/GCD
====================

The 'Config' menu allows you to configure your ripping program and your CDDB
database. Rip/Encode/ID3 options are only available in Grip.

Here are the options:

CD options:

 o Don't interrupt playback on exit/startup: If this is not selected, Grip
                                             will stop play when it starts
                                             and when it stops.

 o Rewind when stopped: If selected, Grip will rewind to the first track
                        when play is stopped.

 o Startup with first track if not playing: If this is not selected, Grip
                                            will begin with whatever track
					    the cd-player played last.

 o Reshuffle before each playback: If selected, Grip will re-randomize the
                                   tracks each time playback begins when in
                                   shuffle-play mode.

 o Work around faulty eject: Try this if Grip is having trouble ejecting
                             your cds.

Rip Options:

 o Ripper: This allows you to select one of the preset rippers. This will
           fill in sensible default parameters for calling the ripper. If
           you select "grip (cdparanoia)", Grip will use its builtin version
           of cdparanoia (only available if paranoia has been compiled
           in). If the builtin ripper is selected, the following options are
           available:

           o Disable paranoia: Disables all paranoia checking.

           o Disable extra paranoia: Only cdda2wav-style overlap checking
                                     will be done.

           o Disable scratch detection: Do not look for scratches.

           o Disable scratch repair: Disable scratch repair (still detect)

 o Ripping executable: This should be the full path to the program you want
                       to use to rip tracks with.

 o Ripping command-line: These are the arguments that will be passed to the
                         ripping program. The '%' switches are translated as
                         follows:

                         o %t - Track to be ripped
                         o %b - Begin sector to be ripped (0 is start of
                                track) 
                         o %e - End sector of track
                         o %f - Filename to put .wav data to

 o Rip file format: This specifies the format of the filename to write
                    ripped data to. The '%' switches are translated as
                    follows:

                    o %n - Name of track being ripped
                    o %t - Number of track being ripped
                    o %a - Artist of current track
		    o %A - Artist of the current disc
                    o %d - Name of current disc
                    o %b - Begin sector to be ripped (0 is start of
                           track) 
                    o %e - End sector of track
                    o %c - cdrom device
		    o %i - CDDB discid in hex format
                    o %g - ID3 genre tag as a number
                    o %G - ID3 genre tag as a word

		    Adding a '*' between the '%' and the switch will cause
		    underscoring of the field to be skipped.
		    
 o Rip 'nice' value: The 'nice' (priority) level to run the rip at.

 o Max non-encoded .wav's: The maximum number of non-encoded .wav files grip
                           will keep around before pausing ripping.

 o Auto-rip on insert: If selected, Grip will automatically select all
                       tracks and begin ripping when a new (ie: no local
                       disc data) disc is inserted.

 o Beep after rip: If selected, Grip will "beep" after ripping is finished.

 o Auto-eject after rip: If selected, Grip will automatically eject the disc
                         when ripping is finished.

 o Auto-eject deleay: Specifies the number of seconds to wait before
                      auto-ejecting. This is useful for some drives that
                      are slow to spin down.

 o Wav filter command: This command will be run after ripping but before
                       encoding. It can be used to call a program to
                       maniuplate the .wav file in some way (such as doing
                       normalization). It accepts a single switch, %f, which
                       translates as the ripped .wav file.


MP3 options:

 o Encoder: This allows you to select one of the preset rippers. This will
            fill in sensible default parameters for calling the encoder.

 o MP3 executable: This should be the full path to the program you want
                   to use to MP3-encode tracks with.

 o MP3 command-line: These are the arguments that will be passed to the
                     MP3 encoder. The '%' switches are translated as
                     follows:

		     o %b - Encode bitrate (kbits/sec)
                     o %f - Filename of the .wav data to be encoded
                     o %o - Filename to save mp3 data to

 o MP3 file format: This specifies the format of the filename to write
                    MP3 data to. The '%' switches are the same as those
                    used in the rip file format.

 o Delete .wav after encoding?: If selected, this option will (surprise!)
                                delete the ripped .wav file after encoding.

 o Insert into SQL database: If selected, and DigitalDJ is installed, Grip
                             will place the song information into
                             DigitalDJ's song database.

 o Create .m3u files: If selected, Grip will create .m3u playlist files for
                      each cd that is ripped.

 o Use relative paths in .m3u files: If selected, mp3 filenames inside an
                                     m3u file will be relative to the
                                     location of the m3u file.

 o M3U file format: The file format of the .m3u file. The '%' switches are
                    the same as those used in the rip and encode file
                    formats.

 o Encoding bitrate (kbits/sec): Specifies the bitrate that the MP3s should
                                 be encoded at. This will only work if the
                                 '%b' option is used in the MP3
                                 command-line.

 o Number of CPUs to use: This is the number of simultaneous encode
                          processes allowed. If you have an SMP system,
                          increase this number to use more processes. Note
                          that Grip must be restarted for changes in this
                          option to take effect.

 o MP3 'nice' value: The 'nice' (priority) level to run the MP3 encode at.


ID3 options:

 o ID3 Executable: The full path to the program that will add ID3 tags to an
                   MP3 file

 o ID3 Command-line: The arguments to be passed to the ID3 program. The %
                     switches are translated as:

                    o %n - Name of track
                    o %t - Number of track
                    o %a - Artist of current track
		    o %A - Artist of the current disc
                    o %d - Name of current disc
                    o %g - ID3 genre tag as a number
                    o %G - ID3 genre tag as a word
		    o %y - Year of track
                    o %f - Name of the MP3 file

 o Add ID3 tags: If selected this option will cause ID3 tags to be added to
                 each MP3 file after it is encoded.
 

CDDB options:

 o Primary/Secondary CDDB server: These are your servers for looking up disc
                                  information over the net. If the disc is
                                  not found on the primary server, the
                                  secondary server will be checked.

   o DB server: The address of the CDDB server you wish to use.

   o DB CGI path: The path to the script on the server that handles HTTP
                  requests. This is generally "~cddb/cddb.cgi" or
                  "cgi-bin/cddb.cgi".

   o DB Submit email: The email address to send CDDB submissions to.

   o Perform CDDB lookup automatically: If selected, Grip will always try
                                         to look up an unknown disc. If not
                                         selected, lookup must be initiated
                                         manually.


Proxy options:

 o Use proxy server: If selected, CDDB requests will be sent through an
                     HTTP proxy (useful for people behind firewalls).

 o Get server from 'http_proxy' env. var:
        If set, Grip will try to read the http server/port information from
        the environment variable "http_proxy", which should take the form
        "http://server:port".

 o Proxy server: The address of the HTTP proxy server to be used.

 o Proxy port: The port to talk to the proxy on.


Misc options:

 o Email address: The email address to be used as a reply address when
                  submitting CDDB entries and bug reports.

 o CD update program: This program will be run whenever a disc is put in the
                      drive. All sensible '%' switches can be used. I use
                      this to call a program that generates a web page that
                      tells what CD I'm currently playing.

 o Do not lowercase filenames: If selected, Grip will not lowercase
                               filenames.

 o Characters to not strip in filenames: Specifies a list of characters that
                                         Grip should not strip when creating
                                         filenames. If left blank
                                         (recommended) Grip will only allow
                                         alphanumeric characters.

 o Keep application minimum size: If selected, Grip will always try to keep
                                  its window a the minimum size possible.


Common Questions
================

 Q: When I try to rip a track, I get X I/O errors. What gives?

 A: This seems to be a problem with non-thread-safe systems. Make sure your
    system is safe for threads. This often seems to be associated with libc5.


 Q: I just get a message saying that the program can't access my drive. This
    makes it hard to do much. Help!

 A: Your user account must have access to the cd device. See the
    "Running Grip/GCD" section for more information on this.


 Q: I can play cd's fine, but my ripper can't access the drive. Why not?

 A: Rippers (cdparanoia, at least) need access to the generic scsi device as
    well. See the "Running Grip/GCD" section for more information on this.


 Q: The progress bar doesn't seem to be completely accurate when doing an
    MP3 encode. Why can't it get it right?

 A: The progress bar is done based on the size of the output file. If you
    have the kbits/sec set properly, Grip should estimate the size
    properly. Note that if you use variable bitrate encoding (supported by
    encoders like LAME and xing) Grip has no way to accurately guess the
    file size.


 Q: When I encode tracks, the MP3 progress bar never does anything. What
    happened to progress?

 A: If your MP3 encoder doesn't accept an output filename (like BladeEnc),
    or you haven't passed it one on the command-line, then it might not be
    outputting to the file Grip expects. Make sure that your MP3 file format
    is set to what your encoder is actually producing.


 Q: When Grip looks up disc information, it works, but says "Error saving
    disc data". Why?

 A: Grip saves local copies of disc track information in the directory
    "~/.cddb". It must be able to create or access this directory.


 Q: How come I don't get any scrollbars in the track display?

 A: You are using a version of Grip compiled for gtk+ v1.0.x on a system
    that has gtk+ v1.2.x installed. You need to either get a binary compiled
    for the development series of gtk+, or compile Grip yourself.


 Q: When my buddy runs Grip, he gets those nifty LCD icons showing
    rip/encode/CDDB status, but I don't. What makes him so special?

 A: He's using a more recent version of gtk+ than you are. Due to bugs in
    gtk+ v1.0.x, I don't support the icons under it. Upgrade your gtk+!


 Q: I can't get Grip to rip any tracks! This makes it less than useful...

 A: Grip won't rip tracks unless you tell it what to rip. Use the right
    mouse button to select tracks for ripping.


 Q: I was listening to a CD in Grip and it sounded horrible! What's up?

 A: Perhaps you are listening to country music...


CDDB notes
==========

I have declined to sign a license agreement with Escient, the company who
owns "www.cddb.com" and runs the CDDB server "us.cddb.com". Their license
would (among other things) have required me to place advertisements in Grip
and restrict you, the user, to use only their databases. I am against this
commercial use of the track information submitted by users such as
yourself. For this reason, I encourage you to use free servers, such as
"freedb.freedb.org".


License and Disclaimer
======================

Grip and GCD are Copyright (c) 1998-2001 by Mike Oliphant. Grip and GCD may
be used and distributed under the terms of the GNU General Public
License. All other brand and product names are trademarks, registered
trademarks or service marks of their respective holders.

These programs are distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along with
this distribution; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111, USA.


Acknowledgments
===============

Thanks go to:

 o Everyone involved in GTK development for a wonderful GUI
 o Tony Arcieri, for libcdaudio, which formed the basis of Grip's low-level
   cd control and CDDB access routines
 o Monty, for cdparanoia and the paranoia library
 o Heiko Eissfeldt for cdda2wav
 o Tord Jansson for BladeEnc
 o Mike Cheng, Mark Taylor and all the others who have worked on LAME
 o Ti Kan, for the xmcd button bitmaps, many of which I use in modified form
 o Everyone has contributed code to Grip (see the CREDITS file)
 o mp3.com for hosting nostatic.org
 o Everyone else who has given me feedback and helped test Grip


---
Mike Oliphant (oliphant@gtk.org)

http://www.nostatic.org/grip
