Grip/GCD
========

Grip is a gtk-based cd-player and front-end for cd-rippers (such as
cdparanoia and cdda2wav) and MP3 encoders. It allows you to rip entire
tracks, or pinpoint a section of a track to rip. The CDDB protocol is
supported for retreiving track information from disc database servers. 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)


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. Type 'make', and then 'make install'. This will install both Grip
and GCD on your system.


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

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

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 withe 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.

**************************************************************************
******************************** 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. Some of the Rip options require root access to edit, as the
rip program is called with root permissions. Rip/Encode/ID3 options are only
available in Grip.

Here are the options:

Rip Options:

 o Ripping executable: (** Root only **) This should be the full path to the
                       program you want to use to rip tracks with.

 o Ripping command-line: (** Root only **) 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: (** Root only **) 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 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 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.


MP3 options:

 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 %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 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 disc
                    o %d - Name of current disc
                    o %g - ID3 genre tag as a number
                    o %G - ID3 genre tag as a word
                    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 CDDB server: The address of the CDDB server you wish to use.

   o CDDB 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".


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 Output directory: The directory to place WAV and MP3 files in. The same '%'
                     switches as in the rip/encode filenames can be used.

 o Convert spaces to underscores: If selected, this will cause all spaces in
                                  filenames to underscores.

 O Also underscore: A list of characters to replace with underscores when
                    constructing filenames.

 o CD update program: This program will be run whenver 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.


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: 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. Because
    I can only estimate what the size of the resulting MP3 file will be (I
    use 1/10th of the .wav size) the progress bar is an approximation.


 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: 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.1.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 exploitation of the track information submitted by users such as
yourself. For this reason, I encourage you to use free servers, such as
"freecddb.freecddb.org".


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

Grip and GCD are Copyright (c) 1998 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
 o Heiko Eissfeldt for cdda2wav
 o Ti Kan, for the xmcd button bitmaps, many of which I use in modified form
 o Greg Grensteiner, for giving suggesting a nice way to implement
   multi-track ripping
 o Dima Barsky, for giving me a workaround for a freezing problem that
   ocurred when running bladeenc
 o Ian Campbell, for the code that supports ID3 tagging
 o David Walluck, for helping to fix my RPM .spec file
 o David Decotigny, for sending me the basis of the loop/shuffle code
 o Everyone else who has given me feedback and helped test Grip


Revision History
================

v1.7 -- March 31st, 1999
------------------------

 o moved the proxy config options to a separate tab
 o underscoring now not done in ID3 command-line
 o added a warning when entries are submitted to a commercial server
 o added a gtk+ version compatibility warning
 o added secondary CDDB server
 o the user is now asked if they want to submit when a disc is found on the
   secondary server, but not the primary one
 o switched the freecddb cgi-path to ~cddb
 o made detection of no disc even more reliable
 o Makefile now uses install (thanks to Eduard Dulich)
 o fixed a nasty bug that could cause Grip to expand to the whole screen
   (thanks to Shaw Terwilliger for this)
 o fixed a security hole (thanks go to Jonathan Pickard)
 o added labels to the disc edit entries, and switched the order of
   title/artist 
 o fixed a problem that was resulting in an unnecessary horizontal scrollbar
   in the track list widget in GCD
 o added the ability to select CDDB genres
 o track transitions are now smooth when in normal play mode
 o added a help tab and a bug report submission form

v1.6 -- March 26th, 1999
------------------------

 o removed the leading '/' from the default CDDB cgi path
 o removed the submission of user name and host information to the CDDB
   server -- I feel that this information is private, and should not be
   submitted without the user's consent. anyway, the server has no
   (non-marketing) use for it
 o added CDDB submission
 o added editing of disc title/artist
 o low-level cd control now done by Grip instead of libcdaudio
 o all libcdauio dependencies now removed
 o added "save disc info" button
 o the GUI is now more responsive while a song is playing
 o fixed a nasty bug that was causing disc title/artist to be switched
 o fixed a problem with CDDB entries sometimes being saved as root
 o volume control is now set properly on startup
 o encoding no longer hangs if the MP3 file format is set improperly
 o fixed a problem with not stopping in non-loop play
 o fixed a problem that was causing play to stop at the end of a track if
   play had been paused (this is a low-level driver bug, I think)

v1.5 -- March 24th, 1999
------------------------

 o added a popup message if the use selects rip/encode with no tracks
   selected 
 o added another fix that *might* fix the X i/o problems some people are
   having
 o fixed a bug with start/end sector info in command-line/filename parsing
   (thanks go to Jonathan Aseltine for pointing this out to me)
 o fixed a bug that was keeping the '-d' command-line option from working
   (thanks to Alan Wild for sending this in)
 o added yet *another* fix to try to get rid of X i/o problems
 o added loop and shuffle play modes (courtesy of David Decotigny)
 o made the cgi path of the CDDB server configurable
 o switched the default CDDB server to freecddb.freecddb.org
 o fixed up shuffle play, and added playlist support
 o CDDB entry reading/writing is now done by Grip rather than libcdaudio

v1.4 -- March 8th, 1999
-----------------------

 o added '"' to the default list of underscored characters
 o added %i option to pass the discid as a command-line argument
 o added Grip URL to about page (clicking loads page in netscape)
 o fixed a problem with GCD accessing a Grip-only label
 o the track/time indicator is now displayed properly while looking up a
   disc through CDDB
 o set the volume widget to the correct scale (it was too quiet)
 o CDDB lookup can now be aborted and initiated at any time
 o clicking on the time display now toggles the mode between time played in
   track, time played in disc, time left in track, and time left in disc
 o initial support for cd-changers added, but not tested (I don't have one)
 o Track names are now editable
 o fixed a bug with handling CDDB entries with long disc/track names
 o added '-l' command-line option to disable CDDB lookup
 o fixed (I hope!) a bug with CDDB lookup of discs with many tracks
 o added a popup message when user's try to edit root-only config options

v1.3 -- March 2nd, 1999
-----------------------

 o pixmaps are now compiled into the executable
 o added a fix that *might* fix the Xlib async errors some people are getting
 o Grip can now read proxy server/port from the "http_proxy" env. variable
 o made the text entry widgets take up as much space as they can
 o the text in entry widgets is now initially set to display from the
   beginning (it looked odd before)
 o introduced GCD, a cd-player only version of Grip

v1.2 -- February 23rd, 1999
---------------------------

 o added error message when a pixmap fails to load
 o added an option to call an external program to add ID3 tags to the
   encoded files. Contributed by Ian Campbell <ijc25@cam.ac.uk>
 o cleaned up the look of the config section a bit
 o added option to limit the number of tracks to have waiting to be encoded
 o rip/encode processes that are active when Grip is shut down are now
   terminated

v1.1 -- February 17th, 1999
---------------------------

 o underscoring of spaces filenames is now optional
 o added a configurable set of characters to underscore in filenames
 o the '%t' (track) switch is now zero-padded to 2 characters
 o CDDB lookup is now done by Grip, rather than using libcdaudio
 o better handling of self-titled albums
 o 'nice' values are now supported for the rip/encode processes
 o fixed a bug that could make Grip encode when you didn't want it to
 o the time display now stops flashing if the disc is stopped while paused
 o now only options that impact the rip program/filename need root access to
   be able to configure them

v1.0 -- February 2nd, 1999
--------------------------

 o added a "CD update" program to run whenever a new disc is loaded
 o removed the extra "output directory" option in the CDDB config section
 o fixed freezing problem with bladeenc
 o new icons to show rip/encode progress and CDDB lookup in LCD panel
 o tooltips color selection now down through .rc file
 o ripping and encoding now run simultaneously for multi-track rips

v0.9 -- January 18th, 1999
--------------------------

 o track times are now displayed while looking up a disc in the CDDB
 o Grip now uses the new http-based libcdaudio interface
 o added support for proxy servers for CDDB lookup
 o added '%c' switch to specify cdrom device
 o the '%' switches can now be used in the output directory path
 o output files are no longer written as root

v0.8 -- January 11th, 1999
--------------------------

 o fixed a bug that kept the "previous track" button from working properly
   when audio was playing
 o fixed a bug that made the display keep updating after play hit the end
   of a disc
 o clicking on the "Rip" column heading will now select all tracks
 o added scrolled window for track display in gtk+ 1.1.x versions
 o selection of tracks to rip with right mouse should now work for
   gtk+ 1.1.x
 o selecting a track to rip no longer interacts with whether the track is
   selected

v0.7 -- January 5th, 1999
-------------------------

 o added a volume control
 o the eject button will now close the drive if it is open
 o gtk_clist_set_policy() not used if compiling with gtk 1.1.x
 o added support for ripping multiple tracks
 o re-organized the config page into multiple sub-pages
 o re-organized the rip page
 o added a button to toggle partial track ripping
 o added rip/encode status to the LCD display
 o added options to configure the format of ripped and encoded files
 o added option to configure output directory
 o added option to delete .wav files after MP3-encoding them

v0.6 -- December 22nd, 1998
---------------------------

 o made next/prev track buttons work a bit more sensibly
 o standard play now continues to subsequent tracks
 o Rip page track info now recognizes when no disc is present
 o added track number to track info display
 o cd status is no longer checked when idle with a disc in the drive
 o track names with a '/' can now be ripped
 o the track display now only has scrollbars if they are needed
 o fastfwd and rewind now continue if the button is held down

v0.5 -- December 18th, 1998
---------------------------

 o compressed the controls a bit
 o added support for MP3-encoding
 o added cute rounding effect on the "LCD" display

v0.4 -- December 16th, 1998
---------------------------

 o the play time indicator now resets to zero when a disc is ejected
 o changed the look of the CD controls
 o added "cd-only" mode
 o added "-s" command-line option to force cd-only mode
 o the main window now pops up all at once
 o added current track indicator in cd panel display
 o added fastforward and rewind (kind of)

v0.3 -- December 14th, 1998
---------------------------

 o fixed a bug that would cause a crash if no disc was present on startup
 o fixed a bug that would cause discs to be looked up in the CDDB even
   if a record was already stored locally
 o the display now reflects the situation when no disc is present
 o updating data when discs are changed is now much better
 o added a CDDB access indicator

v0.2 -- December 10th, 1998
---------------------------

 o ripping is now disabled if you are already ripping
 o fixed a memory allocation bug in the track list clist
 o CDDB lookup is now threaded

v0.1 -- December 8th, 1998
--------------------------

 o first public release


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

http://www.ling.ed.ac.uk/~oliphant/grip
