
=head1 NAME

grip - A gtk-based cd-player and cd-ripper.

gcd - A gtk-based cd-player (used as part of grip, or alone).

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

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.


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

=head1 OPTIONS

These are the command-line options for grip:

=over 5

=item C<-d E<lt>deviceE<gt>>

Use E<lt>deviceE<gt> as the cd-rom device (default: C</dev/cdrom>).

=item C<-s>

Launch grip in a "small" (cd-only) mode.

=item C<-l>

"local" mode -- don't try to use CDDB.

=item C<-v>

Verbose (debug) mode.

=back

These are gcd's command-line options:

=over 5

=item C<-d E<lt>deviceE<gt>>

Use E<lt>deviceE<gt> as the cd-rom device (default: C</dev/cdrom>).

=item C<-f>

Launch gcd in "full" (track-display) mode.

=item C<-l>

"local" mode -- Don't try to use CDDB.

=item C<-v>

Verbose (debug) mode.

=back

=head1 USAGE

The most handy way to launch Grip/GCD is from your window manager's doc. A
dock icon (C<gripicon.tif>/C<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 account 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 C</dev/sg>E<lt>somethingE<gt>). 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.

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

B<IMPORTANT!>

=head1 CONFIGURATION

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:

=head2 CD options:

=over 5

=item Don't interrupt playback on exit/startup

If this is not selected, Grip
will stop play when it starts
and when it stops.

=item Rewind when stopped

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

=item Startup with first track if not playing

If this is not selected, Grip
will begin with whatever track
the cd-player played last.

=item Reshuffle before each playback

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

=back

Rip Options:

=over 5

=item B<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:

=item Disable paranoia

Disables all paranoia checking.

=item Disable extra paranoia

Only cdda2wav-style overlap checking will be done.

=item Disable scratch detection

Do not look for scratches.

=item Disable scratch repair

Disable scratch repair (still detect)

=item Ripping executable

This should be the full path to the program you want to use to rip tracks with.

=item Ripping command-line

These are the arguments that will be passed to the ripping program. The
'C<%>' switches are translated as follows:

=over 5

=item C<%t>

Track to be ripped

=item C<%b>

Begin sector to be ripped (0 is start of track) 

=item C<%e>

End sector of track

=item C<%f>

Filename to put C<.wav> data to

=back

=item Rip file format

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

=over 5

=item C<%n>

Name of track being ripped

=item C<%t>

Number of track being ripped

=item C<%a>

Artist of current track

=item C<%A>

Artist of the current disc

=item C<%d>

Name of current disc

=item C<%b>

Begin sector to be ripped (0 is start of track) 

=item C<%e>

End sector of track

=item C<%c>

cdrom device

=item C<%i>

CDDB discid in hex format

=item C<%g>

ID3 genre tag as a number

=item C<%G>

ID3 genre tag as a word

=for html <!-- fix -->

=back

=for html <!-- fix -->

Adding a '*' between the '%' and the switch will cause
underscoring of the field to be skipped.

=for html <!-- fix --> 

=item Rip 'nice' value

The 'nice' (priority) level to run the rip at.

=item Max non-encoded C<.wav>'s

The maximum number of non-encoded C<.wav> files grip will keep around before
pausing ripping.

=item 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.

=item Auto-eject after rip

If selected, Grip will automatically eject the disc
when ripping is finished.

=item Wav filter command

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

=back

=head2 MP3 options:

=over 5

=item Encoder

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

=item MP3 executable

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

=item MP3 command-line

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

=over 5

=item C<%b>

Encode bitrate (kbits/sec)

=item C<%f>

Filename of the .wav data to be encoded

=item C<%o>

Filename to save mp3 data to

=back

=item 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.

=item Delete C<.wav> after encoding?

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

=item Insert into SQL database

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

=item 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.

=item MP3 'nice' value

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

=back

=head2 ID3 options:

=over 5

=item ID3 Executable

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

=item ID3 Command-line

The arguments to be passed to the ID3 program. The %
switches are translated as:

=over 5

=item C<%n>

Name of track

=item C<%t>

Number of track

=item C<%a>

Artist of current track

=item C<%A>

Artist of the current disc

=item C<%d>

Name of current disc

=item C<%g>

ID3 genre tag as a number

=item C<%G>

ID3 genre tag as a word

=item C<%y>

Year of track

=item C<%f>

Name of the MP3 file

=back

=item Add ID3 tags

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

=for html <!-- fix -->

=back

=head2 CDDB options:

=over 5

=item 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.

=item DB server

The address of the CDDB server you wish to use.

=item DB CGI path

The path to the script on the server that handles HTTP
requests. This is generally "C<~cddb/cddb.cgi>" or
"C<cgi-bin/cddb.cgi>".

=item Perform CDDB lookup automatically

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

=back

=head2 Proxy options:

=over 5

=item Use proxy server

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

=item Get server from 'http_proxy' env. var:

If set, Grip will try to read the http server/port information from
the environment variable "C<http_proxy>", which should take the form
"C<http://server:port>".

=item Proxy server

The address of the HTTP proxy server to be used.

=item Proxy port

The port to talk to the proxy on.

=back

=head2 Misc options:

=over 5

=item Output directory

The directory to place WAV and MP3 files in. The same 'C<%>'
switches as in the rip/encode filenames can be used.

=item Convert spaces to underscores

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

=item Also underscore

A list of characters to replace with underscores when
constructing filenames.

=item Email address

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

=item  CD update program

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

=item  Keep application minimum size

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

=back

=head1 Common Questions

=item Q:

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

=item 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.

=for html <hr>

=item Q:

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

=item A:

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

=for html <hr>

=item Q:

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

=item 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.

=for html <hr>

=item Q:

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

=item 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.


=for html <hr>

=item Q:

I can't get lame to work. How lame is that?

=item A:

Lame has trouble with long filenames. If you increase MAX_NAME_SIZE in
the common.h file of the lame source distribution, it works fine.


=for html <hr>

=item Q:

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

=item 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.


=for html <hr>

=item Q:

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

=item A:

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


=for html <hr>

=item Q:

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

=item 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.


=for html <hr>

=item 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?

=item 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+!


=for html <hr>

=item Q:

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

=item A:

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


=for html <hr>

=item Q:

Grip just hangs when doing a CDDB lookup. Why?

=item A:

If you are using Linux kernel 2.2.x, you need to compile Grip from
source. Installing the RPM results in network problems.


=for html <hr>

=item Q:

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

=item A:

Perhaps you are listening to country music...

=back

=head1 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
"freecddb.freecddb.org".

=head1 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.

=head1 Acknowledgments

Thanks go to:

=over 5


=item *

Everyone involved in GTK development for a wonderful GUI

=item *

Tony Arcieri, for libcdaudio, which formed the basis of Grip's low-level
cd control and CDDB access routines

=item *

Monty, for cdparanoia and the paranoia library

=item *

Heiko Eissfeldt for cdda2wav

=item *

Tord Jansson for BladeEnc

=item *

Mike Cheng, Mark Taylor and all the others who have worked on LAME

=item *

Ti Kan, for the xmcd button bitmaps, many of which I use in modified form

=item *

Everyone has contributed code to Grip (see the CREDITS file)

=item *

Everyone else who has given me feedback and helped test Grip

=back

=head1 CHANGES

See the README file that came with the source code.

=head1 AUTHOR

Grip and GCD written by Mike Oliphant (C<oliphant@gtk.org>)

Documentation formatting by Aaron Sherman (C<ajs@ajs.com>)

  http://www.nostatic.org/grip

=cut
