--- /dev/null
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+ <article id="grip" lang="en">
+ <articleinfo>
+ <title>Grip User's Guide</title>
+ <authorgroup>
+ <author>
+ <firstname>Mike</firstname> <surname>Oliphant</surname>
+ <affiliation>
+ <address>
+ <email>grip@nostatic.org</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ <copyright>
+ <year>2004</year> <holder>Mike Oliphant</holder>
+ </copyright>
+ <legalnotice>
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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</para>
+
+ <para>For more details see the file COPYING in the source
+ distribution of GNOME.</para>
+ </legalnotice>
+ </articleinfo>
+
+ <sect1 id="intro">
+ <title>Introduction</title>
+
+ <mediaobject>
+ <imageobject><imagedata
+ format="PNG" fileref="images/grip-logo.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>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.</para>
+ </sect1>
+
+ <sect1 id="cdplayer">
+ <title>Playing CDs with Grip</title>
+ <para>Grip functions as a full-featured CD player, as can be seen in
+ <xref linkend="cdplayerfull"/>. Tracks can be selected by clicking on
+ them with the left mouse button. Double-clicking will select the track,
+ and begin playing it.</para>
+
+ <figure id="cdplayerfull">
+ <title>Grip as a CD Player</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/cdplayer.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <sect2>
+ <title>CD Player Controls</title>
+
+ <para>Underneath the "LCD" display is a panel of buttons that allow
+ you to control CD playing in Grip. These buttons function as
+ follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playpause.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Play/Pause</guilabel> — Causes the selected track
+ to play if it is stopped or paused. If a track is currently
+ playing, it will go into pause mode.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/rewind.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Rewind</guilabel> — While this button is held
+ down, Grip will move backward in the currently playing track.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ffwd.png"/>
+ </imageobject></mediaobject>
+ <guilabel>FastForward</guilabel> — While this button is
+ held down, Grip will more forward in the currently playing
+ track.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/prevtrk.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Previous track</guilabel> — 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/nexttrk.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Next track</guilabel> — This will skip to the next
+ track.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/progtrack.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Track Mode</guilabel> — This brings up the track
+ mode interface, described in <xref linkend="sect-trackmode"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/stop.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Stop</guilabel> — Stops track playback.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/eject.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Eject</guilabel> — Opens or closes the cdrom
+ tray.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/cdscan.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Scan disc contents</guilabel> — 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).</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/volume.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Volume</guilabel> — Toggles display of the
+ volume control slider interface.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/trkedit.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Track Edit</guilabel> — This brings up the track
+ editing interface described in ...</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/discdb.png"/>
+ </imageobject></mediaobject>
+ <guilabel>DiscDB</guilabel> — This initiates lookup of the
+ CD over the network, or aborts a disc lookup currently in
+ progress.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/minmax.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Min/Max</guilabel> — Toggles between the "full"
+ and "cd-only" (shown in <xref linkend="cdplayersmall"/>) display
+ modes.</para>
+
+ <para>
+ <figure id="cdplayersmall">
+ <title>Grip in "cd-only" mode.</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/cdplayersmall.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/quit.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Quit</guilabel> — Exits Grip.</para>
+ </listitem>
+
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="sect-trackmode">
+ <title>Track Mode Selector</title>
+ <para>
+ <figure id="modeinterface">
+ <title>The Play Mode Interface</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/modeinterface.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+ </para>
+
+ <para>The track mode selection interface (shown in <xref
+ linkend="modeinterface"/>) allows you to control how Grip plays the
+ tracks on a CD. The following options are available:</para>
+ <itemizedlist>
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playnormal.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Normal Mode</guilabel> — In this mode,
+ tracks will be played in normal, numbered order.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playrandom.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Random Mode</guilabel> — In this mode,
+ tracks will be played in a random order.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playplaylist.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Playlist Mode</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playloop.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Loop Mode</guilabel> — In loop mode, when
+ playback finishes it will then resume at the beginning
+ again.</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/playonce.png"/>
+ </imageobject></mediaobject>
+ <guilabel>Single Play Mode</guilabel> — In this mode,
+ when playback finishes it will not begin again.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="ripping">
+ <title>Ripping CDs with Grip</title>
+
+ <para>Playing CDs is great, but what Grip is really designed for is
+ ripping CDs and creating encoded versions of the tracks.</para>
+
+ <sect2>
+ <title>Selecting Tracks To Rip</title>
+ <para>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.</para>
+ </sect2>
+
+ <sect2>
+ <title>Ripping CDs</title>
+ <figure id="rip-interface">
+ <title>The ripping interface</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ripping.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>There are number of buttons in the interface under the "Rip"
+ tab. They function as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Rip+Encode</guilabel> — This will cause Grip
+ to rip and then encode all selected tracks.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Rip Only</guilabel> — This will cause Grip
+ to rip all selected tracks, but not encode them.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Abort Rip and Encode</guilabel> — Clicking
+ this button will abort all active rip and encode
+ processes.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Abort Ripping Only</guilabel> — Clicking
+ this button will abort ripping, but will leave encoding
+ running.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>DDJ Scan</guilabel> — Clicking this button
+ will insert all track information for the current disc into
+ DigitalDJ's database (if it is installed)</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Rip partial track</guilabel> — 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.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>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:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile1.png"/>
+ </imageobject></mediaobject>Normal operation, low/no jitter</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile2.png"/>
+ </imageobject></mediaobject>Normal operation, considerable jitter</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile3.png"/>
+ </imageobject></mediaobject>Read drift</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile4.png"/>
+ </imageobject></mediaobject>Unreported
+ loss of streaming in atomic read operation</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile5.png"/>
+ </imageobject></mediaobject>Finding
+ read problems at same point during reread; hard to correct</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile6.png"/>
+ </imageobject></mediaobject>SCSI/ATAPI transport error</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile7.png"/>
+ </imageobject></mediaobject>Scratch detected</para>
+ </listitem>
+
+ <listitem>
+ <para><mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/smile8.png"/>
+ </imageobject></mediaobject>Gave up trying to perform a correction</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+
+ <figure id="rip-small">
+ <title>Ripping in "small" mode</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ripsmall.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+ </sect2>
+
+ <sect2 id="rip-perform">
+ <title>Increasing Ripping Performance</title>
+
+ <para>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)</para>
+
+ <para>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)</para>
+ </sect2>
+
+ <sect2 id="sect-scsi">
+ <title>Using a SCSI drive</title>
+
+ <para>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 <xref
+ linkend="ripconfig"/>).</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="configure">
+ <title>Configuring Grip</title>
+
+ <para>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.</para>
+
+ <sect2 id="cdconfig">
+ <title>The "CD" config tab</title>
+ <figure id="cdconfig-image">
+ <title>The "CD" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/cdconfig.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>This tab allows to you configure options associated with your
+ cdrom device and CD playback. The options are:</para>
+
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>CDRom device</guilabel> — Specifies the
+ CDRom device to be used for CD playback.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Don't interrupt playback on
+ exit/startup</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Rewind when stopped</guilabel> — If this
+ option is checked, Grip will rewind to the beginning of the disc
+ whenever playback is stopped.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Startup with first track if not playing</guilabel>
+ — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Reshuffle before each playback</guilabel> —
+ If this option is checked, randomized playback will be
+ re-randomized each time playback is restarted. Otherwise, the same
+ random sequence will be reused.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Work around faulty eject</guilabel> — If
+ this option is set, Grip will not rely on querying the open/closed
+ status of the CDRom tray.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Poll disc drive for new disc</guilabel> — If
+ this option is set, Grip will poll the disc drive to check if a
+ new disc has been inserted.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Poll interval</guilabel> — This specifies
+ the number of seconds Grip waits between checks for a new
+ disc.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="ripconfig">
+ <title>The "Rip" config tab</title>
+
+ <para>This tab allows to you configure Grip's ripping
+ capabilities.</para>
+
+ <figure id="ripconfig-image">
+ <title>The "Rip" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ripconfig.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Ripper</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Disable paranoia</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Disable extra paranoia</guilabel> — If this
+ option is selected, Grip will only do overlap checking to ensure
+ proper alignment of reads. It will not verify reads for
+ errors.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Disable scratch detection / repair</guilabel>
+ — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Calculate gain adjustment</guilabel>
+ — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Rip file format</guilabel> — This allows to
+ you configure the filename and path that Grip rips files to. The
+ list of available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Generic SCSI device</guilabel> — 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 <xref linkend="sect-scsi"/>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>If you select a ripper other than Grip's builtin cdparanoia, the
+ configuration dialog will look slightly different:</para>
+
+ <figure id="ripconfig2-image">
+ <title>Configuring an external ripper</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ripconfig2.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Ripping executable</guilabel> — This is the
+ full path to the executable to be used for ripping</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Rip command-line</guilabel> — This is the
+ command-line to be passed to the ripping program. The list of
+ available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>The second sub-tab contains addition options that you can
+ specify to configure the ripping process.</para>
+
+ <figure id="ripconfig3-image">
+ <title>Additional ripping options</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/ripconfig3.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Rip 'nice' value</guilabel> — 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).</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Max non-encoded .wav's</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Auto-rip on insert</guilabel> — If this
+ option is checked, Grip will automatically begin ripping all
+ tracks on a disc when it is inserted.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Beep after rip</guilabel> — If this option
+ is checked, Grip will emit a beep when ripping is finished.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Auto-eject after rip</guilabel> — If this
+ option is checked, Grip will eject the disc after ripping is
+ finished.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Auto-eject delay</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Delay before ripping</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Stop cdrom drive between tracks</guilabel> —
+ If this is selected, grip will spin down the cdrom drive between
+ ripping tracks.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Wav filter command</guilabel> — 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
+ <xref linkend="gripswitches"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Disc filter command</guilabel> — This
+ operates much like the Wav filter command, except that it is run
+ once after an entire disc has finished ripping.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="mp3config">
+ <title>The "Encode" config tab</title>
+
+ <para>This tab allows to you configure Grip's encoding
+ capabilities.</para>
+
+ <figure id="mp3config-image">
+ <title>The "Encode" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/mp3config.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Encoder</guilabel> — This allows
+ you to select an encoder preset.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encoder executable</guilabel> — This specifies
+ the full path to the executable program you wish to use for
+ encoding.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encoder command-line</guilabel> — This is the
+ command-line to be passed to the encoding program. The list of
+ available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encode file format</guilabel> — This allows to
+ you configure the filename and path that Grip encodes to. The
+ list of available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The second sub-tab contains addition options that you can
+ specify to configure the encoding process.</para>
+
+ <figure id="mp3config2-image">
+ <title>Additional encoding options</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/mp3config2.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Delete .wav after encoding</guilabel> — If
+ this option is checked, Grip will delete wav files after it has
+ finished encoding them.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Insert info into SQL database</guilabel> — If
+ this option is checked, Grip will insert track meta-data into the
+ DigitalDJ database (if it is installed).</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Create .m3u files</guilabel> — If
+ this option is checked, Grip will create .m3u playlist listing the
+ tracks on a CD when it is ripped.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Use relative paths in .m3u files</guilabel>
+ — 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).</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>M3U file format</guilabel> — This specifies
+ the filename format to be used when writing .m3u files. The list
+ of available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encoding bitrate</guilabel> — This is the
+ encoding bitrate (kilobits per second) to be used. This value is
+ passed to the encoder using the '%b' switch.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Number of CPUs to use</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encode 'nice' value</guilabel> — 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).</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Encode filter command</guilabel> — 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 <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="id3config">
+ <title>The "ID3" config tab</title>
+
+ <para>This tab allows to you customize Grip's use of ID3 tags.</para>
+
+ <figure id="id3config-image">
+ <title>The "ID3" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/id3config.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Add ID3 tags to encoded files</guilabel> —
+ 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Add ID3v2 tags to encoded files</guilabel> —
+ 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>ID3 comment field</guilabel> — This allows
+ you to specify the format of the ID3 comment field. The list of
+ available switches can be found in <xref
+ linkend="gripswitches"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>ID3v1 Character set encoding</guilabel> —
+ The character encoding to be used for ID3v1 tags. ISO_8859_1 is
+ recommended.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>ID3v2 Character set encoding</guilabel> —
+ The character encoding to be used for ID3v1 tags. ISO_8859_1 or UTF-8
+ are the most likely options.</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="discdbconfig">
+ <title>The "DiscDB" config tab</title>
+
+ <para>This tab allows to you customize how Grip talks to disc
+ information servers (such as freedb) to obtain disc meta-data.</para>
+
+ <figure id="discdbconfig-image">
+ <title>The "DiscDB" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/discdbconfig.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Primary/Secondary Server</guilabel> — 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>DB server</guilabel> — This is the http
+ address of the disc database server.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>DB server</guilabel> — This is the path to
+ the CGI to be used on the disc database server. It is generally
+ "~cddb/cddb.cgi".</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>DB Character set encoding</guilabel> — The
+ character encoding to use when tranferring data to/from the
+ server. This should generally be set to UTF-8.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>DB Submit email</guilabel> — This allows you
+ to specify the email address to send disc database submissions
+ to.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Use freedb extensions</guilabel> — If
+ checked, Grip will make use of extensions to the disc database
+ format used by freedb. Otherwise, it will use an older
+ format.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Perform disc lookups automatically</guilabel>
+ — 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.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="proxyconfig">
+ <title>The "Proxy" config tab</title>
+
+ <para>This tab allows to you configure Grip to communicate through a
+ proxy server.</para>
+
+ <figure id="proxyconfig-image">
+ <title>The "Proxy" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/proxyconfig.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Use proxy server</guilabel> — Indicates
+ whether or not Grip should do disc lookups via a proxy server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Get server from 'http_proxy' env. var</guilabel>
+ — If this option is checked, Grip will check the
+ 'http_proxy' environment variable, and use its value as the name
+ of the proxy server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Proxy server</guilabel> — The name of the
+ proxy server to use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Proxy port</guilabel> — The port to use on
+ the proxy server (usually 8000).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Proxy username</guilabel> — Some proxies
+ require user authentication. This field is the username you wish
+ to authenticte with.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Proxy password</guilabel> — This is the
+ password that goes along with the username for proxy
+ authentication.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="miscconfig">
+ <title>The "Misc" config tab</title>
+
+ <para>This tab allows contains various additional configuration
+ options.</para>
+
+ <figure id="msicconfig-image">
+ <title>The "Misc" config tab</title>
+ <screenshot>
+ <mediaobject><imageobject><imagedata format="PNG"
+ fileref="images/miscconfig.png"/>
+ </imageobject></mediaobject>
+ </screenshot>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Email address</guilabel> — 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>CD update program</guilabel> — 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 <xref linkend="gripswitches"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Do not lowercase filenames</guilabel> — By
+ default, Grip lowercases the strings used when translating the '%'
+ switches. If this option is checked, it will not do this.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Allow high bits in filename</guilabel> — 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Do not change spaces to underscores</guilabel>
+ — 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Characters to not strip in filenames</guilabel>
+ — Grip strips all non-alphanumeric characters in the
+ strings used when translating the '%' switches. Any characters
+ entered here will explicity not be stripped.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="gripswitches">
+ <title>Configuration (%) switches</title>
+
+ <para>Here is a list of the '%' switches used in command-lines.</para>
+
+ <itemizedlist>
+ <listitem><para><guilabel>b</guilabel> — The bitrate that files
+ are being encoded at. </para></listitem>
+
+ <listitem><para><guilabel>c</guilabel> — The CDrom device
+ being used. </para></listitem>
+
+ <listitem><para><guilabel>C</guilabel> — The generic scsi
+ device being used (note that this will be substituted with the
+ CDrom device if no generic scsi device has been
+ specified).</para></listitem>
+
+ <listitem><para><guilabel>w</guilabel> — The filename of the
+ wave file being ripped. </para></listitem>
+
+ <listitem><para><guilabel>m</guilabel> — The filename of the
+ file being encoded. </para></listitem>
+
+ <listitem><para><guilabel>t</guilabel> — The track
+ number,beginning at 1, and zero-filled (ie: '03' for the third
+ track). </para></listitem>
+
+ <listitem><para><guilabel>s</guilabel> — The start sector of
+ the track. </para></listitem>
+
+ <listitem><para><guilabel>e</guilabel> — The end sector of the
+ track. </para></listitem>
+
+ <listitem><para><guilabel>n</guilabel> — The name of the
+ track. </para></listitem>
+
+ <listitem><para><guilabel>a</guilabel> — The artist name for
+ the track. </para></listitem>
+
+ <listitem><para><guilabel>A</guilabel> — The artist name for
+ the disc. </para></listitem>
+
+
+ <listitem><para><guilabel>d</guilabel> — The name of the disc.
+ </para></listitem>
+
+ <listitem><para><guilabel>i</guilabel> — The disc database id
+ (in hex) for the disc. </para></listitem>
+
+ <listitem><para><guilabel>y</guilabel> — The year of the disc.
+ </para></listitem>
+
+ <listitem><para><guilabel>g</guilabel> — The ID3 genre id of
+ the disc. </para></listitem>
+
+ <listitem><para><guilabel>G</guilabel> — The ID3 genre string
+ of the disc. </para></listitem>
+
+ <listitem><para><guilabel>r</guilabel> — 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 <ulink
+ url="http://www.replaygain.org">www.replaygain.org</ulink></para>
+ </listitem>
+
+ <listitem><para><guilabel>R</guilabel> — 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).</para>
+ </listitem>
+
+ <listitem><para><guilabel>x</guilabel> — The encoded file
+ extension (ie "mp3")</para></listitem>
+
+ </itemizedlist>
+
+ <para>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).</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="faq">
+ <title>FAQ</title>
+
+ <itemizedlist>
+ <listitem><para>Q: When I try to rip a track, I get X I/O errors. What
+ gives?</para>
+
+ <para>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.</para></listitem>
+
+
+ <listitem><para>Q: I just get a message saying that the program can't
+ access my drive. This makes it hard to do much. Help!</para>
+
+ <para>A: Your user account must have access to the cdrom device.
+ </para></listitem>
+
+
+ <listitem><para>Q: I can play cd's fine, but my ripper can't access
+ the drive. Why not?</para>
+
+ <para>A: On scsi systems, rippers (cdparanoia, at least) need access
+ to the generic scsi device as well.</para></listitem>
+
+
+ <listitem><para>Q: The progress bar doesn't seem to be completely
+ accurate when encoding. Why can't it get it right?</para>
+
+ <para>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.</para></listitem>
+
+ <listitem><para>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?</para>
+
+ <para>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 <xref
+ linkend="ripconfig"/>.</para></listitem>
+
+ <listitem><para>Q: When I encode tracks, the progress bar never
+ does anything. What happened to progress?</para>
+
+ <para>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.</para></listitem>
+
+
+ <listitem><para>Q: When Grip looks up disc information, it works, but
+ says "Error saving disc data". Why?</para>
+
+ <para>A: Grip saves local copies of disc track information in the
+ directory "~/.cddb". It must be able to create or access this
+ directory.</para></listitem>
+
+
+ <listitem><para>Q: How come I don't get any scrollbars in the track
+ display?</para>
+
+ <para>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.</para></listitem>
+
+
+ <listitem><para>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?</para>
+
+ <para>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+!</para></listitem>
+
+
+ <listitem><para>Q: I can't get Grip to rip any tracks! This makes it
+ less than useful...</para>
+
+ <para>A: Grip won't rip tracks unless you tell it what to rip. Use
+ the right mouse button to select tracks for
+ ripping.</para></listitem>
+
+
+ <listitem><para>Q: I was listening to a CD in Grip and it sounded
+ horrible! What's up?</para>
+
+ <para>A: Perhaps you are listening to country
+ music...</para></listitem>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id="morehelp">
+ <title>Getting More Help</title> <para>If you need more help with Grip,
+ your best resource is the Grip mailing list. You will find it <ulink
+ url="http://lists.sourceforge.net/mailman/listinfo/grip-users">
+ here</ulink>. Be sure to check the mailing list archives for answers to
+ any questions you may have.</para>
+ </sect1>
+
+ <sect1 id="bugs">
+ <title>Reporting Bugs / Sumitting Patches</title>
+
+ <para>To report a bug with Grip, or to submit a patch. Please do so at
+ the <ulink url="http://sourceforge.net/projects/grip">Grip
+ section</ulink> on sourceforge.net.</para>
+ </sect1>
+
+ <sect1 id="cddb">
+ <title>CDDB notes</title> <para>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.</para>
+ </sect1>
+
+ <sect1 id="license">
+ <title>License and Disclaimer</title> <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+ </sect1>
+
+ <sect1 id="acknowledge">
+ <title>Acknowledgments</title>
+
+ <para>Thanks go to:</para>
+
+ <itemizedlist>
+
+ <listitem><para>Everyone involved in GTK development for a wonderful
+ GUI</para></listitem>
+
+ <listitem><para>Tony Arcieri, for libcdaudio, which formed the basis
+ of Grip's low-level cd control and disc database access
+ routines</para></listitem>
+
+ <listitem><para>Monty, for cdparanoia and the paranoia
+ library</para></listitem>
+
+ <listitem><para>Heiko Eissfeldt for cdda2wav</para></listitem>
+
+ <listitem><para>Mike Cheng, Mark Taylor and all the others who have
+ worked on LAME</para></listitem>
+
+ <listitem><para>Tord Jansson for BladeEnc</para></listitem>
+
+ <listitem><para>Michael Kaiser and everyone else who has helped out
+ with freedb</para></listitem>
+
+ <listitem><para>Ti Kan, for the xmcd button bitmaps, many of which I
+ use in modified form (shame on you for the cddb fiasco,
+ however)</para></listitem>
+
+ <listitem><para>mp3.com for hosting nostatic.org</para></listitem>
+
+ <listitem><para>David Robinson and Glen Sawyer for
+ ReplayGain</para></listitem>
+
+ <listitem><para>Everyone else who has given me feedback, contributed
+ code, and helped test Grip (see the ChangeLog and CREDITS for
+ specific contributions)</para></listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ </article>
+
+
+
+
+