# Grip User's Guide

Mike Oliphant

                grip@nostatic.org

2004 Mike Oliphant

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is 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 program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of GNOME.

## Introduction

Grip is a cd-player and cd-ripper for the Gnome desktop. 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 (and other audio format) encoders, letting you take a disc and transform it easily straight into MP3s. Internet disc lookups are supported for retrieving track information from disc database servers. Grip works with DigitalDJ to provide a unified "computerized" version of your music collection.

## Playing CDs with Grip

Grip functions as a full-featured CD player, as can be seen in . Tracks can be selected by clicking on them with the left mouse button. Double-clicking will select the track, and begin playing it.

Grip as a CD Player

### CD Player Controls

Underneath the "LCD" display is a panel of buttons that allow you to control CD playing in Grip. These buttons function as follows:

- Play/Pause — Causes the selected track to play if it is stopped or paused. If a track is currently playing, it will go into pause mode.

- Rewind — While this button is held down, Grip will move backward in the currently playing track.

- FastForward — While this button is held down, Grip will more forward in the currently playing track.

- Previous track — If a track is currently playing near the beginning of a track, this will rewind to the beginning. Otherwise, it will skip to the previous track.

- Next track — This will skip to the next track.

- Track Mode — This brings up the track mode interface, described in .

- Stop — Stops track playback.

- Eject — Opens or closes the cdrom tray.

- Scan disc contents — Causes Grip to force a scan of the current CD as if it were just inserted (useful if you have polling for a new disc turned off).

- Volume — Toggles display of the volume control slider interface.

- Track Edit — This brings up the track editing interface described in ...

- DiscDB — This initiates lookup of the CD over the network, or aborts a disc lookup currently in progress.

- Min/Max — Toggles between the "full" and "cd-only" (shown in ) display modes.

  Grip in "cd-only" mode.

- Quit — Exits Grip.

### Track Mode Selector

The Play Mode Interface

The track mode selection interface (shown in ) allows you to control how Grip plays the tracks on a CD. The following options are available:

- Normal Mode — In this mode, tracks will be played in normal, numbered order.

- Random Mode — In this mode, tracks will be played in a random order.

- Playlist Mode — In this mode, track will be played in an order you specify. In the text entry box, entry a list of comma separated list of the tracks you wish to play.

- Loop Mode — In loop mode, when playback finishes it will then resume at the beginning again.

- Single Play Mode — In this mode, when playback finishes it will not begin again.

## Ripping CDs with Grip

Playing CDs is great, but what Grip is really designed for is ripping CDs and creating encoded versions of the tracks.

### Selecting Tracks To Rip

Before ripping, you need to select the tracks that you would like to rip. This can be done by right-clicking on tracks in the "Tracks" tab, or left clicking on a track when your mouse is under the "Rip" column. In addtion, you can quickly select/deselect all tracks for ripping by clicking on the "Rip" column label.

### Ripping CDs

The ripping interface

There are number of buttons in the interface under the "Rip" tab. They function as follows:

- Rip+Encode — This will cause Grip to rip and then encode all selected tracks.

- Rip Only — This will cause Grip to rip all selected tracks, but not encode them.

- Abort Rip and Encode — Clicking this button will abort all active rip and encode processes.

- Abort Ripping Only — Clicking this button will abort ripping, but will leave encoding running.

- DDJ Scan — Clicking this button will insert all track information for the current disc into DigitalDJ's database (if it is installed)

- Rip partial track — If selected, Grip will configured to rip a portion of a single track (as specified by the "Start sector" and "End sector" values). The "Play" button can be used preview the selected portion.

In the bottom portion of the interface, Grip displays progress bars for the rip and encode processes. It also computes the speed of the processes as a function of normal playback speed (so 2.0x, for example, means that processing is running twice as fast as normal playback, on average). In addition, if Grip is using builtin cdparanoia to rip, there will be a "smilie" indicator next to the progress bar that reflects how much trouble Grip is having ripping the CD. The meaning of the different smiles are as follows:

- Normal operation, low/no jitter

- Normal operation, considerable jitter

- Read drift

- Unreported loss of streaming in atomic read operation

- Finding read problems at same point during reread; hard to correct

- SCSI/ATAPI transport error

- Scratch detected

- Gave up trying to perform a correction

In addition to the individual track rip/encode progress bars, Grip displays overall progress bars that indicate the overall progress of a multi-track rip.

Grip also places an indicator for both ripping and encoding the the LCD display. They show progress in %25 intervals, as can be seen in this example of Grip in "small" mode. In this case, we are almost finished ripping a track, and have encoded about a quarter of a track.

Ripping in "small" mode

### Increasing Ripping Performance

If you are using an IDE CDrom drive, using SCSI emulation can give a significant performance increase. Apparently, dma is not used by the IDE driver (at least in 2.4 kernels). To enable SCSI emulation, add "hdx=ide-scsi" (where the "x" in "hdx" is is replaced with the appropriate letter for your CDRom device) to end of the "kernel" line in /etc/grub.conf (if you are using grub), or as a line after "root=/dev/something" in /etc/lilo.conf (if you are using lilo)

You can also disable paranoia to get approximately a 2x speedup. This is not recommended, however, unless you are very confident in the ability of your drive to do rock-solid CDDA extraction (or unles you enjoy having pops in your audio)

### Using a SCSI drive

If you are using a SCSI drive, or an IDE drive under SCSI emulation, Grip needs to access the generic scsi device in addition to the cdrom device. On most systems, the generic scsi device will be /dev/sgx, where 'x' is a number. Unless you have multiple scsi devices, the device would be /dev/sg0. Ensure that your user account has access to this device, and that this device is specified in your rip configuration (see ).

## Configuring Grip

The "Config" tab gives you access to a series of sub-tabs that allow you to configure the various functions of Grip. Each of these sub-tabs is described in detail in the following sections.

### The "CD" config tab

The "CD" config tab

This tab allows to you configure options associated with your cdrom device and CD playback. The options are:

- CDRom device — Specifies the CDRom device to be used for CD playback.

- Don't interrupt playback on exit/startup — If this option is checked, Grip will not stop a playing track when it is shut down. Also, if a CD is already playing when Grip starts, it will keep playing.

- Rewind when stopped — If this option is checked, Grip will rewind to the beginning of the disc whenever playback is stopped.

- Startup with first track if not playing — If this option is checked, Grip will always make the first track on the CD the current track if the CD is not currently playing. Otherwise, Grip will start with whatever track is currently set with the CDRom device.

- Reshuffle before each playback — If this option is checked, randomized playback will be re-randomized each time playback is restarted. Otherwise, the same random sequence will be reused.

- Work around faulty eject — If this option is set, Grip will not rely on querying the open/closed status of the CDRom tray.

- Poll disc drive for new disc — If this option is set, Grip will poll the disc drive to check if a new disc has been inserted.

- Poll interval — This specifies the number of seconds Grip waits between checks for a new disc.

### The "Rip" config tab

This tab allows to you configure Grip's ripping capabilities.

The "Rip" config tab

- Ripper — This allows you to select from various presets configured for various Rippers. By default, "grip (cdparanoia)" is used, which rips with Grip's builtin version of cdparanoia.

- Disable paranoia — If this option is checked, Grip will disable cdparanoia's verification system. This will make ripping approximately twice as fast, but can result in errors. Unless you are very confident that your drive is rock solid, it is recommended that you do not select this option.

- Disable extra paranoia — If this option is selected, Grip will only do overlap checking to ensure proper alignment of reads. It will not verify reads for errors.

- Disable scratch detection / repair — These options allow you to determine whether Grip attempts to detect scratches on the CD, and whether or not it attempts to repair the scratches it detects.

- Calculate gain adjustment — If this option is checked, Grip will calculate a suggested gain adjustment for tracks as it rips. Computed values can then be passed to external programs via the '%r' and '%R' switches.

- Rip file format — This allows to you configure the filename and path that Grip rips files to. The list of available switches can be found in .

- Generic SCSI device — If you are using a SCSI drive, or an IDE drive under SCSI emulation, you need to specify the generic SCSI device to be used. Form more information on using a SCSI drive, see

If you select a ripper other than Grip's builtin cdparanoia, the configuration dialog will look slightly different:

Configuring an external ripper

- Ripping executable — This is the full path to the executable to be used for ripping

- Rip command-line — This is the command-line to be passed to the ripping program. The list of available switches can be found in .

The second sub-tab contains addition options that you can specify to configure the ripping process.

Additional ripping options

- Rip 'nice' value — This allows you to set the 'nice' level to run the ripping process at. This changes the scheduling priorty of the process. The range goes from -20 (highest priority) to 19 (lowest).

- Max non-encoded .wav's — This allows you to specify the maximum number of ripped wave files that can accumulate if ripping is proceding faster than encoding can keep up. It is useful to keep unencoded .wav files from taking up too much disk space.

- Auto-rip on insert — If this option is checked, Grip will automatically begin ripping all tracks on a disc when it is inserted.

- Beep after rip — If this option is checked, Grip will emit a beep when ripping is finished.

- Auto-eject after rip — If this option is checked, Grip will eject the disc after ripping is finished.

- Auto-eject delay — This allows you to specify a delay (in seconds) before auto-ejection will happen. This is useful on some drives that need time to spin down before ejection can occur.

- Delay before ripping — If this is selected, grip will delay 5 seconds before starting to rip. This can help with some drives (particularly some dvd drives) that take a while to spin up.

- Stop cdrom drive between tracks — If this is selected, grip will spin down the cdrom drive between ripping tracks.

- Wav filter command — This allows you to specify a program (full path to executable, followed by the command-line) to run after a file has been ripped, but before it is encoded. This is useful for such tasks as normalization. The list of available switches can be found in .

- Disc filter command — This operates much like the Wav filter command, except that it is run once after an entire disc has finished ripping.

### The "Encode" config tab

This tab allows to you configure Grip's encoding capabilities.

The "Encode" config tab

- Encoder — This allows you to select an encoder preset.

- Encoder executable — This specifies the full path to the executable program you wish to use for encoding.

- Encoder command-line — This is the command-line to be passed to the encoding program. The list of available switches can be found in .

- Encode file format — This allows to you configure the filename and path that Grip encodes to. The list of available switches can be found in .

The second sub-tab contains addition options that you can specify to configure the encoding process.

Additional encoding options

- Delete .wav after encoding — If this option is checked, Grip will delete wav files after it has finished encoding them.

- Insert info into SQL database — If this option is checked, Grip will insert track meta-data into the DigitalDJ database (if it is installed).

- Create .m3u files — If this option is checked, Grip will create .m3u playlist listing the tracks on a CD when it is ripped.

- Use relative paths in .m3u files — If this option is checked, filename is .m3u files will be relative to the directory the .m3u file is in (otherwise, full paths will be used).

- M3U file format — This specifies the filename format to be used when writing .m3u files. The list of available switches can be found in .

- Encoding bitrate — This is the encoding bitrate (kilobits per second) to be used. This value is passed to the encoder using the '%b' switch.

- Number of CPUs to use — On SMP systems, Grip can encode using multiple processors. This value specifies the number of simultaneous encode processes to run. Grip needs to be restarted for a change to take effect.

- Encode 'nice' value — This allows you to set the 'nice' level to run encoding at. This changes the scheduling priorty of the process. The range goes from -20 (highest priority) to 19 (lowest).

- Encode filter command — This allows you to specify a program (full path to executable, followed by the command-line) to run after a file has been encoded. The list of available switches can be found in .

### The "ID3" config tab

This tab allows to you customize Grip's use of ID3 tags.

The "ID3" config tab

- Add ID3 tags to encoded files — If this option is checked, Grip will add ID3v1 tags to the files it encodes. ID3 tags are used to put song meta-data into an encoded file. You will want to disable this if you are encoding with a format other than MP3.

- Add ID3v2 tags to encoded files — This option is only displayed if Grip has been compiled with ID3v2 support. If it is checked, Grip will add ID3v2 tags to the files it encodes. ID3v2 tags remove the 20-character field length limitation imposed by ID3v1.

- ID3 comment field — This allows you to specify the format of the ID3 comment field. The list of available switches can be found in .

- ID3v1 Character set encoding — The character encoding to be used for ID3v1 tags. ISO_8859_1 is recommended.

- ID3v2 Character set encoding — The character encoding to be used for ID3v1 tags. ISO_8859_1 or UTF-8 are the most likely options.

### The "DiscDB" config tab

This tab allows to you customize how Grip talks to disc information servers (such as freedb) to obtain disc meta-data.

The "DiscDB" config tab

- Primary/Secondary Server — Grip allows you to configure a primary and secondary disc database server. If information cannot be found using the primary server, Grip will then try using the secondary server.

- DB server — This is the http address of the disc database server.

- DB server — This is the path to the CGI to be used on the disc database server. It is generally "~cddb/cddb.cgi".

- DB Character set encoding — The character encoding to use when tranferring data to/from the server. This should generally be set to UTF-8.

- DB Submit email — This allows you to specify the email address to send disc database submissions to.

- Use freedb extensions — If checked, Grip will make use of extensions to the disc database format used by freedb. Otherwise, it will use an older format.

- Perform disc lookups automatically — If this option is checked, Grip will automatically query the disc database server when a disc is inserted that does not already have meta-data stored.

### The "Proxy" config tab

This tab allows to you configure Grip to communicate through a proxy server.

The "Proxy" config tab

- Use proxy server — Indicates whether or not Grip should do disc lookups via a proxy server.

- Get server from 'http_proxy' env. var — If this option is checked, Grip will check the 'http_proxy' environment variable, and use its value as the name of the proxy server.

- Proxy server — The name of the proxy server to use.

- Proxy port — The port to use on the proxy server (usually 8000).

- Proxy username — Some proxies require user authentication. This field is the username you wish to authenticte with.

- Proxy password — This is the password that goes along with the username for proxy authentication.

### The "Misc" config tab

This tab allows contains various additional configuration options.

The "Misc" config tab

- Email address — A valid email addres where you can be reached. This is used with disc database submissions to allow the disc database server to contact you if there are problems with a submission.

- CD update program — This allows you to specify a program (full path to executable, followed by the command-line) to run when a new disc is inserted. This is useful for such tasks as normalization. The list of available switches can be found in .

- Do not lowercase filenames — By default, Grip lowercases the strings used when translating the '%' switches. If this option is checked, it will not do this.

- Allow high bits in filename — By default, Grip strips high-bit characters in the strings used when translating the '%' switches. If this option is checked, it will not do this.

- Do not change spaces to underscores — By default, Grip replaces spaces with underscores in the strings used when translating the '%' switches. If this option is checked, it will not do this.

- Characters to not strip in filenames — Grip strips all non-alphanumeric characters in the strings used when translating the '%' switches. Any characters entered here will explicity not be stripped.

### Configuration (%) switches

Here is a list of the '%' switches used in command-lines.

- b — The bitrate that files are being encoded at.

- c — The CDrom device being used.

- C — The generic scsi device being used (note that this will be substituted with the CDrom device if no generic scsi device has been specified).

- w — The filename of the wave file being ripped.

- m — The filename of the file being encoded.

- t — The track number,beginning at 1, and zero-filled (ie: '03' for the third track).

- s — The start sector of the track.

- e — The end sector of the track.

- n — The name of the track.

- a — The artist name for the track.

- A — The artist name for the disc.

- d — The name of the disc.

- i — The disc database id (in hex) for the disc.

- y — The year of the disc.

- g — The ID3 genre id of the disc.

- G — The ID3 genre string of the disc.

- r — The recommended replay gain for the track (in dB). Note that this is only applicable if you have enabled gain calculation. You can find more information on this gain adjustment at www.replaygain.org

- R — The recommended replay gain for the entire album (in dB). This value is only valide after an entire disc has been ripped (it is designed to be used with the disc filter command).

- x — The encoded file extension (ie "mp3")

Any of the '%' switches can optionally be preceded by a '*' or '!' modifier (for example, '%*a'). '*' prevents Grip from doing any stripping of characters from the string. '!' forces Grip to strip characters from the string. If neither modifier is used, Grip will do what it thinks is best (generally, it will only munge strings if it knows they are part of a filename).

## FAQ

- 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 cdrom device.

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

  A: On scsi systems, rippers (cdparanoia, at least) need access to the generic scsi device as well.

- Q: The progress bar doesn't seem to be completely accurate when encoding. 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 try to rip, Grip skips some of the tracks I have selected. That's not nice -- how can I make it stop?

  A: Some drives (particularly some dvd drives) take a while to spin up, and get confused if ripping starts before they are ready. Try enabling the "Delay before ripping" setting in .

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

  A: If your 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 encoded 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/DiscDB 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...

## Getting More Help

If you need more help with Grip, your best resource is the Grip mailing list. You will find it here. Be sure to check the mailing list archives for answers to any questions you may have.

## Reporting Bugs / Sumitting Patches

To report a bug with Grip, or to submit a patch. Please do so at the Grip section on sourceforge.net.

## 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.org.

## License and Disclaimer

Grip is Copyright &copy 2002 by Mike Oliphant. Grip 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:

- Everyone involved in GTK development for a wonderful GUI

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

- Monty, for cdparanoia and the paranoia library

- Heiko Eissfeldt for cdda2wav

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

- Tord Jansson for BladeEnc

- Michael Kaiser and everyone else who has helped out with freedb

- Ti Kan, for the xmcd button bitmaps, many of which I use in modified form (shame on you for the cddb fiasco, however)

- mp3.com for hosting nostatic.org

- David Robinson and Glen Sawyer for ReplayGain

- Everyone else who has given me feedback, contributed code, and helped test Grip (see the ChangeLog and CREDITS for specific contributions)