<?xml version="1.0" encoding="UTF-8"?><!-- -*- indent-tabs-mode: nil -*- -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY app "Sound Juicer">
  <!ENTITY application "<application>&app;</application>">
  <!ENTITY appversion "2.22.0">
  <!ENTITY manrevision "2.22.0">
  <!ENTITY musicbrainz "<ulink url='http://www.musicbrainz.org/'>MusicBrainz</ulink>">
]>

<?gnome-doc-status
Version: 2.12
Status: Draft
?>

<article id="index" lang="en">
  <articleinfo>
    <title>&application; Manual</title>
    
    <copyright>
      <year>2003</year>
      <holder>Mike Hearn (mike@theoretic.com)</holder>
    </copyright>
    <copyright>
      <year>2005</year>
      <holder>Shaun McCance</holder>
    </copyright>
    <copyright>
      <year>2008</year>
      <holder>Andreas Freund</holder>
    </copyright>
    
    <publisher>
      <publishername>GNOME Documentation Project</publishername>
    </publisher>

    <xi:include href="legal.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

    <authorgroup>
      <author>
        <firstname>Andreas</firstname>
        <surname>Freund</surname>
        <affiliation>
          <orgname>Google Highly Open Participation Contest</orgname>
        </affiliation>
      </author>
      <author>
        <firstname>Mike</firstname>
        <surname>Hearn</surname>
        <email>mike@theoretic.com</email>
      </author>
      <author role="maintainer">
        <firstname>Shaun</firstname>
        <surname>McCance</surname>
        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
        </affiliation>
        <email>shaunm@gnome.org</email>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>&manrevision;</revnumber>
        <date>2008-01-12</date>
        <revdescription>
          <para role="author">Andreas Freund</para>
          <para role="publisher">GNOME Documentation Project</para>
        </revdescription>
      </revision>
      <revision>
        <revnumber>2.10</revnumber>
        <date>2005-03-06</date>
        <revdescription>
          <para role="author">Shaun McCance</para>
          <para role="publisher">GNOME Documentation Project</para>
        </revdescription>
      </revision>
      <revision>
        <revnumber>2.0</revnumber>
        <date>2003-07-06</date>
        <revdescription>
          <para role="author">Mike Hearn
            <email>mike@theoretic.com</email>
          </para>
          <para role="publisher">GNOME Documentation Project</para>
        </revdescription>
      </revision>
    </revhistory>
    <!-- Translators may also add here feedback address for translations -->

    <abstract role="description">
      <para>&application; is a simple and clean CD ripping tool. It allows you
      to extract the audio from audio compact discs and convert them into audio
      files that your computer can understand and play.</para>
    </abstract>
  </articleinfo>

  <section id="intro">
    <title>Introduction</title>
    <anchor id="aboutex"/>
    <anchor id="notice"/>
    <indexterm>
      <primary>Sound Juicer</primary>
      <secondary>Manual</secondary>
      <tertiary>sound-juicer</tertiary>
    </indexterm>

    <para>&application; is a simple and clean CD ripping tool. It allows you
    to extract the audio from audio compact discs and convert them into audio
    files that your computer can understand and play.  &application; can also
    play the audio tracks directly from the CD, allowing you to preview the
    CD before ripping it.</para>

    <para>&application; is designed to be easy to use, and to work with little
    user intervention.  When you start &application;, it will examine the CD in
    the drive and try to locate information about the audio tracks using the
    freely-available &musicbrainz; service.</para>

    <informalfigure>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/startup.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>&application; on startup</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </informalfigure>
  </section>

  <section id="track-data">
    <title>Entering Track Data</title>

    <para>When you insert an audio CD, &application; will automatically retrieve
    the track data from &musicbrainz;.  &musicbrainz; is a free service that provides
    a database of data for most published CDs.  &application; uses the CD's serial
    number and the positions and lengths of the tracks to match against CD in the
    &musicbrainz; database.</para>

    <para>Occasionally, more than one CD will have the same layout.  If more than
    one CD is found, &application; will present a dialog allowing you to choose
    which CD data to use.  If the wrong CD is detected, or if &musicbrainz; does
    not contain any matching CDs, you will have to enter the track information
    manually.  Also, if you choose, you can add the information for the CD to
    &musicbrainz; database with a banner that will appear.</para>

    <para>The top of the window contains text boxes for the title, artist, year,
    and genre of the CD.  Below that is a list of the audio tracks on the CD.  You
    can set the track title and artist for each track.  &application; uses this
    information to name the files and folders where your music is stored.  The
    track and album information is also encoded directly into the audio files.
    Many music players, including portable devices, use this information to
    organize and display the audio files.</para>

    <para>To edit the title of a track, first select the track, then click
    on the title.  When you have finished entering the title, press the
    <keycap>Enter</keycap> key on your keyboard, or click outside the
    title.</para>

    <para>When you edit the artist for the CD, the artist for each track is
    automatically updated, but only if they also matched before the change (so that
    changling the album artist of a compilation doesn't change all of the track
    artists too).  Most CDs are by a single artist, and this feature saves you the time 
    of entering the artist for each track.</para>

    <para>Some CDs, however, are compilations of songs by different artists.
    For these CDs, you will have to enter the artist for each track.  To set
    the artist for a track, first select the track, then click on the artist.
    You can set the artist for the CD to a value like "Various" or simply
    leave it blank, depending on how you prefer to organize your music.</para>

    <tip>
      <title>Entering Track Data With the Keyboard Only</title>
      <para>You can enter track data without using the mouse.  Use the up and
      down arrow keys to select a track, and the left and right arrow keys to
      focus the title or artist.  Press the space bar to begin editing the
      title or artist, and press <keycap>Enter</keycap> when finished.</para>
    </tip>

    <para>&musicbrainz; unfortunately does not provide genre data, but
    &application; includes several stock genres:
    </para>

    <anchor id="genres"/>
    <itemizedlist>
      <listitem><para>Ambient    </para></listitem>
      <listitem><para>Blues      </para></listitem>
      <listitem><para>Classical  </para></listitem>
      <listitem><para>Country    </para></listitem>
      <listitem><para>Dance      </para></listitem>
      <listitem><para>Electronica</para></listitem>
      <listitem><para>Folk       </para></listitem>
      <listitem><para>Funk       </para></listitem>
      <listitem><para>Jazz       </para></listitem>
      <listitem><para>Latin      </para></listitem>
      <listitem><para>Pop        </para></listitem>
      <listitem><para>Rap        </para></listitem>
      <listitem><para>Reggae     </para></listitem>
      <listitem><para>Rock       </para></listitem>
      <listitem><para>Soul       </para></listitem>
      <listitem><para>Spoken Word</para></listitem>
    </itemizedlist>

    <tip><para>If you choose to make a custom genre, it will be remembered in the future.</para></tip>

  </section>

  <section id="extracting">
    <title>Extracting</title>
    <anchor id="using"/>

    <para>By default, &application; will extract all of the tracks on the CD
    to audio files.  If you do not wish to extract all of the tracks, you can
    control which tracks are extracted using the check boxes in the first column
    of the track listing.  Only the tracks you have selected will be extracted.
    </para>

    <para>You can also use the <menuchoice><guimenu>Edit</guimenu>
    <guimenuitem>Select All</guimenuitem></menuchoice> and <menuchoice>
    <guimenu>Edit</guimenu><guimenuitem>Deselect All</guimenuitem>
    </menuchoice> menu items to select all or none of the tracks to
    be extracted.</para>

    <para>When you have entered all the information you need, click on the
    <guibutton>Extract</guibutton> button, or press <keycombo><keycap>Ctrl</keycap>
    <keycap>Enter</keycap></keycombo>.  &application; will begin reading the audio
    from the CD and saving it to files on your computer.  By default, the audio
    files are stored under the <filename>Music</filename> folder in your home
    folder.</para>

    <para>When you begin extracting, the <guibutton>Extract</guibutton> button
    will change to a <guibutton>Stop</guibutton> button.  You can click this
    button at any time to stop extracting.</para>

    <para>&application; indicates which track it is currently extracting by
    displaying an icon next to the track number.  You can also see the total
    progress and estimated time left in the status bar at the bottom of the
    window.</para>

    <para>Extracting a CD can take a long time, depending on the speed of your
    computer.  You can safely minimize &application; or move to another workspace
    to continue using your computer while the audio is being extracted.</para>
  </section>

  <section id="playing">
    <title>Playing</title>

    <para>&application; allows you to play the tracks on your CD directly.
    To begin playing the CD, simply click the <guibutton>Play</guibutton>
    button, or press <keycombo><keycap>Ctrl</keycap><keycap>P</keycap>
    </keycombo>.  To play a particular track, select that track and click
    <guibutton>Play</guibutton>, or simple double-click the track.</para>

    <para>When &application; is playing a CD, the <guibutton>Play</guibutton>
    button changes to a <guibutton>Pause</guibutton> button.  You can click
    this at any time to pause the playing, and click <guibutton>Play</guibutton>
    again to continue playing where you left off.</para>

    <para>While playing, &application; displays a slider showing the position 
    on the current track.  To seek to another part of the track, drag the handle
    along the slider and release.</para>
  </section>

  <section id="preferences">
    <title>Preferences</title>

    <para>The preferences window allows you to control:</para>

    <itemizedlist>
      <listitem><para>Which CD drive &application; uses, if you have more than
      one drive,</para></listitem>
      <listitem><para>Whether or not to eject the CD when &application; is
      finished extracting,</para></listitem>
      <listitem><para>Whether or not to open the music folder when &application;
      is finished extracting,</para></listitem>
      <listitem><para>Where the extracted audio files are placed on your
      computer,</para></listitem>
      <listitem><para>Which system to use for the folder hierarchy in the music
      folder,</para></listitem>
      <listitem><para>Which format to use for the track names of the extracted
      audio files, and</para></listitem>
      <listitem><para>Which file format and codec are used for the extracted
      audio files.</para></listitem>
    </itemizedlist>

    <informalfigure>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/prefs.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Preferences window</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </informalfigure>

    <section id="prefs-drive">
      <title>Selecting a CD Drive</title>

      <para>If you have multiple CD drives in your computer, the drop-down list
      labelled <guilabel>CD drive</guilabel> under <guilabel>Device</guilabel>
      allows you to select which drive to use.  The check boxes <guibutton>Eject
      when finished</guibutton> and <guibutton>Open music folder when finished
      </guibutton>allow you to control whether &application; will eject the CD 
      from the drive, and whether it will open your music folder respectively, 
      when it has finished extracting the audio files.</para>
    </section>

    <section id="prefs-naming">
      <title>Naming Audio Files</title>

      <para>The <guilabel>Music Folder</guilabel> drop-down list allows you to
      select which folder to store your audio files in.  Select one of the
      folders from the list, or choose <guilabel>Other</guilabel> to select
      another folder with the file chooser.  By default, files are placed
      under the <filename>Music</filename> folder in your home folder.</para>

      <para>The <guilabel>Track Names</guilabel> section allows you to control
      how the files and folders are named.  &application; can store audio files
      in seperate folders, helping you keep your music organized.  You can
      choose how these folders are created and named using the <guilabel>Folder
      hierarchy</guilabel> drop-down list.  By default,  &application; creates
      a folder for the album artist and a subfolder for the album.</para>

      <para>Use the <guilabel>File name</guilabel> drop-down list to select
      how the audio files are named.  By default, &application; uses the track
      number followed by a hyphen and the track title.</para>

      <para>Select the <guibutton>Strip special characters</guibutton> check
      box to make &application; remove or replace characters such as spaces and
      punctuation in the filenames.  This is useful if you plan to put the audio
      files onto a portable device or another computer which has more limitations
      on file names.</para>

      <note><para>Even when <guibutton>Strip special characters</guibutton>
      is not selected, &application; will remove the <literal>/</literal>
      character from filenames.  This character cannot be used in any
      filenames on UNIX, Linux, and similar systems.</para></note>

      <tip><para>At the bottom of the <guilabel>Track Names</guilabel> section,
      an example path is shown.  This lets you know what a file name might look
      like and where it is placed, according to your settings for <guilabel>Folder
      hierarchy</guilabel>, <guilabel>File name</guilabel>, and <guibutton>Strip
      special characters</guibutton>.</para></tip>
    </section>

    <section id="prefs-format">
      <title>Selecting a Format</title>

      <para>You can select which audio file format &application; uses to store
      your tracks on your computer.  There are a number of available formats,
      each with its own advantages.  The available formats on your computer
      may vary, but the following choices are usually available:</para>

      <variablelist>
        <varlistentry>
          <term>CD Quality, Lossy (Ogg multimedia)</term>
          <listitem>
            <para>This option is selected by default.
            <ulink url="http://www.vorbis.org/">Ogg Vorbis</ulink>, like other
            lossy audio formats (such as MP3 and AAC) discards some information
            from the original audio data.  Although the audio file is not a
            perfect replica of the CD audio, the differences are often not
            distinguishable to most listeners.  As a result, lossy formats
            tend to have very small file sizes.</para>

            <para>The Ogg Vorbis format is the default lossy format used in
            &application;.  Ogg Vorbis is an open format, developed by the
            <ulink url="http://xiph.org/">Xiph.Org Foundation</ulink>, which
            tends to produce smaller file sizes and higher quality audio than
            many other lossy formats.  While it is not as widespread as the
            older MP3 format, most music software can play Ogg Vorbis files,
            and many hardware players have incorporated support.</para>

            <para>Xiph.Org maintains lists of <ulink
            url="http://wiki.xiph.org/index.php/VorbisSoftwarePlayers">software
            players</ulink>, <ulink
            url="http://wiki.xiph.org/index.php/PortablePlayers">portable
            hardware players</ulink>, and <ulink
            url="http://wiki.xiph.org/index.php/StaticPlayers">static hardware
            players</ulink> which support Ogg Vorbis.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>CD Quality, Lossless (FLAC audio)</term>
          <listitem>
            <para>The <ulink url="http://flac.sourceforge.net/">FLAC</ulink>
            audio format is a lossless format.  No audio data is lost when
            converting to FLAC, even though it compresses audio files by as
            much as 70%.  FLAC and other lossless formats are popular in
            cases where high fidelity audio is needed, but files need to be
            compressed to save disk space and network transfer times.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>CD Quality, AAC (MPEG-4 audio)</term>
          <listitem>
            <para>The AAC (short for Advanced Audio Coding) audio format is a
            standardized lossy format. It is a successor to the MP3 format and
            it achieves better sound quality than the MP3 format. Many software
            players and hardware players support the AAC format.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Voice, Lossless (WAV audio)</term>
          <listitem>
            <para>The Voice output profile produces low-quality mono audio
            files.  You may wish to select this for lectures, books on tape,
            and other spoken word CDs, where the loss in audio quality is
            less important.</para>
          </listitem>
        </varlistentry>
        
<varlistentry>
          <term>MP3</term>
          <listitem>
            <para>The MP3 audio format is a lossy format. It is widely supported
            and popular, especially because of its use for portable media
            players.</para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>You can click the <guibutton>Edit Profiles</guibutton> button to
      edit the available audio formats.  The profile editor dialog provides
      direct access to the audio conversion.  Profiles are defined with
      <application>GStreamer</application> pipelines.
      <application>GStreamer</application> is the underlying multimedia
      library used by &application; and other multimedia applications.
      A full explanation of audio profiles is outside the scope of this
      document.</para>
    </section>
  </section>

</article>
