path: root/doc/kscd/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kscd;">
  <!ENTITY package "kdemultimedia">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kscd; Handbook</title>

<authorgroup>

<author>
<firstname>Mike</firstname>
<surname>McBride</surname> 
<affiliation><address>&Mike.McBride.mail;</address></affiliation>
</author>

<author>
<firstname>Jonathan</firstname>
<surname>Singer</surname>
<affiliation><address>&Jonathan.Singer.mail;</address></affiliation>
</author>

<author>
<firstname>David</firstname>
<surname>White</surname>
<affiliation><address><email>a9403784@unet.univie.ac.at</email></address>
</affiliation>
</author>

<othercredit role="developer">
<firstname>Bernd</firstname>
<othername>Johannes</othername>
<surname>Wuebben</surname>
<affiliation><address>&Bernd.Johannes.Wuebben.mail;</address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Dirk</firstname>
<surname>Forsterling</surname>
<affiliation><address><email>milliByte@gmx.net</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Dirk</firstname>
<surname>Foersterling</surname>
<affiliation><address><email>milliByte@gmx.net</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address>&Lauri.Watts.mail;</address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2000</year><year>2004</year>
<holder>J Singer</holder>

</copyright>
<copyright>

<year>2005-2006</year>
<holder>Mike McBride</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>


<date>2005-12-22</date>
<releaseinfo>1.5</releaseinfo>

<abstract>
<para>&kscd; is a small, fast, <abbrev>CDDB</abbrev> enabled audio
<abbrev>&CD;</abbrev> player for &UNIX; platforms.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
<keyword>kscd</keyword>
<keyword>music</keyword>
<keyword>CD</keyword>
<keyword>audio</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kscd; is a fast, <acronym>CDDB</acronym> enabled &CD; player for the &UNIX;
platform. &kscd; stands for <quote>The KDE Project's small/simple &CD;
player</quote>.</para>

<para><emphasis>New</emphasis>: the <filename>workman2cddb.pl</filename> Perl
script provided in order to facilitate transition for users of workman.</para>

<para>I hope you will enjoy this &CD; player.</para>

<para>&Bernd.Johannes.Wuebben;</para>

<para>&Bernd.Johannes.Wuebben.mail;</para>

<sect1 id="supported-platforms">
<title>Supported Platforms</title>

<para>&kscd; explicitly supports the following platforms:</para>

<itemizedlist>
<listitem><para>&Linux;</para></listitem>
<listitem><para>FreeBSD</para></listitem>
<listitem><para>NetBSD</para></listitem>
<listitem><para>BSD386</para></listitem>
<listitem><para>Sun</para></listitem>
<listitem><para>&Solaris; (including <acronym>cdda</acronym>
support)</para></listitem>
<listitem><para>&HP-UX;</para></listitem>
<listitem><para>&SGI; Irix (including <abbrev>cdda</abbrev>
support)</para></listitem>
<listitem><para>Sony NEWS</para></listitem>
<listitem><para>OSF/1</para></listitem>
<listitem><para>Ultrix</para></listitem>
</itemizedlist>

<para>and should compile on many others with few modifications.</para>

</sect1>

</chapter>

<chapter id="onscreen-fundamentals">
<title>Onscreen fundamentals</title>

<sect1 id="basic-operation">
<title>Basic Operation</title>

<screenshot>
<screeninfo>The &kscd; Interface</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kscd.png" format="PNG"/></imageobject>
<textobject><phrase>The &kscd; Interface</phrase></textobject>
</mediaobject>
</screenshot>

<para>This is the main window of &kscd;. You should see something like this when
you start &kscd;. The controls in this window are explained below, in no
particular order.</para>

<sect2 id="control-panel">
<title>The Control Panel</title>

<screenshot>
<screeninfo>The Control Panel</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd2.png" format="PNG"/></imageobject>
<textobject><phrase>The Control Panel</phrase></textobject>
</mediaobject>
</screenshot>

<para> This is the main control panel for &kscd;. The function of these buttons
should be familiar to anyone who has ever used a &CD; player.</para>

<para>The uppermost button in the above diagram toggles between playing and
pausing the &CD;. The left button in the second row stops playing the &CD;. The
right button in the second row ejects the &CD;. The two buttons in the third row 
skip forward (right) or backward (left) to the beginning of the next or previous track. 
The left button in the bottom row toggles random play order on and off; the right button 
in the bottom row toggles looping, so that the &CD; will start
playing again from the beginning when the end of the last audio track is
reached.</para>
</sect2>


<sect2 id="status-display">
<title>The Status Display</title>

<screenshot>
<screeninfo>The Status Display</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd3.png" format="PNG"/></imageobject>
<textobject><phrase>The Status Display</phrase></textobject>
</mediaobject>
</screenshot>

<para>This is the status display. Starting at the top, from right to left, is
the main time display (see below for a discussion of the various possible time
display modes), the status of the &CD-ROM; drive, the total play time of the
audio &CD;, the current volume setting, and the current and maximum track
numbers (curr./max.). The bottommost two lines of text display the artist and
title of the &CD;, and then the title of the track, assuming that appropriate
entries exist in the local or network <acronym>CDDB</acronym> (&CD; Data
Base.)</para>

<para>Click the time display to toggle between the possible main time display modes. By
default, &kscd; displays the elapsed time of the current track, if the &CD; is
playing, or either &ndash;&ndash;:&ndash;&ndash; or 00:00 if the &CD; is not playing.
Clicking the display toggles in sequence between remaining track time, total
elapsed time, and total remaining time.</para>
</sect2>

<sect2 id="configuration-button">
<title>The <guibutton>Configuration</guibutton> button</title>

<screenshot>
<screeninfo>The Extras button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd5.png" format="PNG"/></imageobject>
<textobject><phrase>The Extras button</phrase></textobject>
</mediaobject>
</screenshot>

<para>This button brings up a menu with a number of options. You can choose to open the &kscd; 
configuration panel or configure keyboard shortcuts. These allow you to
configure &kscd; to work exactly to your tastes. See <link linkend="configuring-kscd">the configuring &kscd;</link> section, for details
about configuring &kscd;</para>
<para>The menu provides several tools to help you search for information about the artist on the
Internet. You can find out about performance dates, purchase information, and
other information by pressing this button and choosing the appropriate option in
the popup menu that appears.</para>
<para>This menu also allows you to open this help document, report bugs, learn more 
about &kscd; and &kde; and to quit &kscd;.</para>
</sect2>

<sect2 id="cddb-button">
<title>The <guibutton>CDDB</guibutton> button</title>

<screenshot>
<screeninfo>The <acronym>CDDB</acronym> button</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd6.png" format="PNG"/></imageobject>
<textobject><phrase>The <acronym>CDDB</acronym> button</phrase></textobject>
</mediaobject>
</screenshot>

<para> This button opens the <acronym>CDDB</acronym> (Compact Disc Data Base) entry
editor panel. </para>

<para>The <acronym>CDDB</acronym> can identify your &CD; and often download a
list of tracks for that &CD; or load it from the filesystem. See the <link
linkend="cddb-editor">&CD; Database Editor</link> section for more details about
using this tool.</para>
</sect2>




<sect2>
<title>The Volume slider</title>

<screenshot>
<screeninfo>The Volume slider</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd9.png" format="PNG"/></imageobject>
<textobject><phrase>The Volume slider</phrase></textobject>
</mediaobject>
</screenshot>

<para> This slider controls the volume of the audio output 
of the &CD;. Moving it to the right makes the music louder, left makes it quieter. If you are playing your &CD; through your sound card,
the sound card mixer will affect the playback volume as well.</para>
</sect2>


<sect2>
<title>The track selector</title>

<screenshot>
<screeninfo>The track selector</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd11.png" format="PNG"/></imageobject>
<textobject><phrase>The Track selector</phrase></textobject>
</mediaobject>
</screenshot>
	    
<para>This combo box shows you the current track number, the name of the track and the time (in minutes and seconds).  You can use this drop down box to directly select
any track on the &CD;.  </para>
</sect2>

</sect1>
</chapter>

<chapter id="configuring-kscd">
<title>Configuring &kscd;</title>
<sect1 id="configuration-intro">
<title>The primary configuration window</title>

<para>You configure &kscd; by clicking on the <guibutton>Extras</guibutton> button.  This will bring up a menu, select 
<guilabel>Configure &kscd;...</guilabel>.  This will open a new window.</para>
<para>The primary configuration window for &kscd; is divided into two 
major sections. </para>

<itemizedlist>
<listitem><para><link linkend="kscd-options-tab"><guilabel>CD
Player</guilabel></link> to determine the look and behavior of &kscd;.</para></listitem>
<listitem><para><guilabel>CDDB</guilabel> which is used to configure the CDDB lookup features of &kscd;.</para></listitem>
</itemizedlist>

<para>You can switch between these two sections using the icons on the left side of the dialog.</para>
</sect1>

<sect1 id="kscd-options-tab">
<title>The <guilabel>CD Player</guilabel> dialog</title>

<screenshot>
<screeninfo>The <guilabel>CD Player</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd12.png" format="PNG"/></imageobject>
<textobject><phrase>The <guilabel>KSCD Configuration</guilabel> dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para>The <guilabel>LCD font:</guilabel> text box lists the currently selected font to display all information in the &kscd; status display.  To change the font, click the <guibutton>Choose...</guibutton> button.</para>

<para>The <guilabel>LCD color:</guilabel> and <guilabel>Background
color:</guilabel> fields show the color selected for the foreground and
background of the status display. Press the color bars to change
these colors.</para>


<!--
<para>The <guilabel>Unix mail command</guilabel> field shows the
command used to send new <acronym>CDDB</acronym> entries to the
database. The default value is <userinput><command>mail</command>
<option>-s <replaceable>%s</replaceable></option></userinput>. You
will need to make sure this command will actually send mail to
non-local systems if you want to submit <acronym>CDDB</acronym>
entries, especially if you access the Internet through a dial-up
connection. Check the documentation for your &Linux; distribution for
details. Some Linux distributions that use sendmail to deliver email
require only that you enter your mail host into the
<option>&quot;Smart&quot; relay host</option> field in
<filename>/etc/sendmail.cf</filename>. In addition, the
<acronym>CDDB</acronym> site will want to be able to mail you back; it
may therefore also be necessary to edit
<filename>/etc/sendmail.cf</filename> to ensure that the return
address on the submission is valid. Your mileage is likely to vary. If
all else fails, use <link linkend="smtp-options">SMTP</link>
instead.</para>

<para>The <guilabel>WWW-Browser</guilabel> section lets you choose which web
browser to use to access the web sites in the <link linkend="information-button">information button</link> menus.  You can choose
either &konqueror; or a custom browser with the radio buttons. By default, the
<guilabel>Use Custom Browser</guilabel> field contains
<userinput><command>kfmclient</command>
<option><replaceable>openURL %s</replaceable></option></userinput>.</para>
-->

<para>Placing a mark in the checkbox labeled <guilabel>Show icon in system tray</guilabel> causes a &kscd; control to
appear in the &kicker; panel.</para>

<para>Placing a mark in the checkbox labeled <guilabel>Show track announcement</guilabel> causes a small information window to appear on 
top of the kicker window each time the &CD; track changes.  This window will automatically disappear in 5 seconds.</para>

<screenshot>
<screeninfo>Sample track announcement</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscdannounc.png" format="PNG"/></imageobject>
<textobject><phrase>Sample track announcement</phrase></textobject>
</mediaobject>
</screenshot>


<para>Set the <guilabel>Skip interval</guilabel> box to the desired number of 
seconds to move ahead or behind when the <guibutton>forward skip</guibutton> 
or <guibutton>reverse skip</guibutton> buttons in the Control Panel are pressed.</para>

<para><guilabel>Autoplay when CD inserted</guilabel> causes &kscd; to start playing the &CD; 
when the tray is closed, with no need to press the
<guibutton>Play</guibutton> button.</para>

<para><guilabel>Eject CD when finished playing</guilabel> causes the
&CD; to be automatically ejected when playback ends.</para>

<para><guilabel>Stop playing CD on exit</guilabel> causes &CD; playback to stop
when &kscd; is closed.</para>

<para>The <guilabel>CD-ROM Device</guilabel> field contains the name
of the &CD-ROM; device to be used to play audio &CD;s. The default
value is <filename>/dev/cdrom</filename>. The permissions on this
device must be set to allow opening this device read-only. Changing
the permissions on this device file will in almost all cases require
superuser privileges and can be done from the command line, or in the
Super User Mode of &konqueror;.</para>

<note><para>Before we discuss the options that follow, it is important to understand that there are two 
ways that personal computers can play a &CD;.</para>

<para>The first method (which &kscd; refers to as direct digital playback), is performed by reading the digital data from the 
&CD; using Digital Audio Extraction (DAE).  This data is sent to your machines CPU which converts the digital data to sound.  This method requires 
a &CD; drive that is capable of DAE (most new drives are) and it requires some CPU processing time to generate the sounds you hear.</para>

<para>The second method uses the internal circuitry available on most &CD; drives to read the data and generate the sounds you will hear 
without using your computers CPU.  This data is transmitted by a dedicated cable directly to the sound card in your computer.  This method requires 
less CPU proccessing time, but it does require that the dedicated cable be connected inside your computer.  Not all computers have this connection.</para></note>

<para>The checkbox labeled <guilabel>Use direct digital playback</guilabel> determines which method &kscd; uses to read the audio tracts.  If there is a mark in the checkbox, the first method is used.  If there is no mark in the checkbox, the second method is utilized.</para>

<para>If you have selected direct digital playback, a dropdown box labeled <guilabel>Select audio backend:</guilabel> will let you select which 
sound backend the digital information should be sent to.  The contents of the dropdown box will vary depending on your system. 
Most users should select <guilabel>arts</guilabel>.  You can also select the device the audio backend uses by entering the device location in 
the text box labeled <guilabel>Select audio device:</guilabel>.  A full discussion of audio devices and audio backends is beyond the scope of this manual.</para>

<para>If a mark is placed in the checkbox labeled <guilabel>Allow encoding selection</guilabel>, you can select the text encoding for the results of a CDDB request.</para>
<tip><para>The standard describes CDDB results as being strictly Latin 1.  If you are not having problems with your CDDB information, leave this box unchecked.</para></tip>


<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>
</sect1>

<sect1 id="freedb-tab">
<title>The <guilabel>freedb Lookup</guilabel> tab</title>
<screenshot>
<screeninfo>The <guilabel>freedb Lookup</guilabel> tab of the configuration dialog</screeninfo>
<mediaobject>
<imageobject> <imagedata fileref="kscd14.png" format="PNG"/> </imageobject>
<textobject><phrase>The <guilabel>freedb Lookup</guilabel> tab of the configuration
dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para> The <guilabel>freedb Lookup</guilabel> tab sets up the <acronym>CDDB</acronym> functions
of &kscd;.</para>

<para>The <guilabel>Mode</guilabel> option determines how <acronym>CDDB</acronym> lookups 
are performed. Setting <guilabel>Cache only</guilabel> means that only information already 
on your computer will be used. <guilabel>Cache and remote</guilabel> will look up 
information you do not already have while <guilabel>Remote only</guilabel> looks up 
every disc over the Internet.</para>


<para>The <guilabel>CDDB Server:</guilabel> section determines which CDDB mirror site is used by &kscd; to 
get album information.  You can enter a server name, port number and protocol using the text boxes and drop 
down boxes or you can click the <guibutton>Show Mirror List</guibutton> button.  Clicking this button will 
open a new window with a list of CDDB mirrors and their locations.  Simply select the server you want from 
the list and click <guibutton>OK</guibutton>.</para>

<para>The section labeled <guilabel>Cache locations</guilabel> lets you determine where &kscd; saves CDDB information 
on your computer.  To add a folder, enter the folder location in the text box at the top of the section and click 
<guibutton>Add</guibutton>.  You can also select a 
folder by clicking on the blue file folder to the right of the text box. To delete a folder, click on the folder name 
once with the &LMB; and click <guibutton>Remove</guibutton>. You can change the order that &kscd; searches the folders by 
clicking on the folder name and clicking on the <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons.</para>

<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>

</sect1>

<sect1 id="smtp-options">
<title>The <guilabel>freedb Submit</guilabel> tab</title>

<screenshot>
<screeninfo>The freedb Submit tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd16.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>The freedb Submit tab sets up connection to a mail
server or a web server to submit new <acronym>CDDB</acronym> entries. This is useful
if you do not have your own system configured as a server. </para>

<para>If you plan to submit a CDDB entry, first you must decide between submitting between HTTP 
and submitting the entry as an email (via SMTP).  </para>

<tip><para>It is simpler to submit new entries using &HTTP;.  Some firewalls block this traffic.  If your 
firewall prevents you from sending new entries using &HTTP;, you can use SMTP.</para></tip>

<para>First select either <guilabel>&HTTP;</guilabel> or <guilabel>SMTP (Email)</guilabel> to determine which 
protocol to use.</para>

<sect2 id="http-options">
<title>Using &HTTP; to send CDDB information</title>
<para>You can enter a server name or port number in the text boxes provided.  If 
you want to send this information to the international servers, you do not need to 
change anything.</para>
</sect2>

<sect2 id="smtp2-options">
<title>Using SMTP (Email) to send CDDB information</title>
<para>To prepare to submit information using email, enter your email address in the 
textbox labeled <guilabel>Reply-To:</guilabel>, your email server in the textbox 
labeled <guilabel>SMTP-server:</guilabel> and select the port number in the dropdown box 
labeled <guilabel>Port:</guilabel>.</para>
<para>If you need to use a password to send email using the email server, place a mark in the 
checkbox labeled <guilabel>Server needs authentication</guilabel> and enter your 
username in the textbox labeled <guilabel>Username:</guilabel>.</para>

<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents
page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits;
<guibutton>Apply</guibutton> saves the current settings without exiting;
<guibutton>Cancel</guibutton> exits without saving. </para>
</sect2>
</sect1>


</chapter>

<chapter id="cddb-editor">
<title>The <guilabel>CD Database Editor</guilabel></title>

<screenshot>
<screeninfo>The &CD; Database Editor</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd13.png" format="PNG"/></imageobject>
<textobject><phrase>The &CD; Database Editor</phrase></textobject>
</mediaobject>
</screenshot>

<para>The &CD; Database Editor allows you to modify, download, save, annotate,
and upload <link linkend="cddb-support"><acronym>CDDB</acronym> (Compact Disc
Data Base)</link> entries.</para>

<para>If there is an entry in your local <acronym>CDDB</acronym> tree
(see the <link linkend="freedb-tab">CDDB subsection</link> in the
Configuration chapter) for the &CD; in your &CD-ROM; drive, or if the
disc could be found in the freedb, you will see the name of the artist
and the title of the &CD; in the <guilabel>Artist:</guilabel> and
<guilabel>Title</guilabel> fields and a list of tracks with song
titles in the <interface>Tracks</interface> selection box. Otherwise,
you will see a list of tracks and play times without titles.</para>

<para>You can make an annotation for the entire disc with the
<guibutton>Comment</guibutton> button under the
<guilabel>Title</guilabel> field, or for a selected track in the
<guilabel>Tracks</guilabel> selection box with the adjacent
<guibutton>Comment</guibutton> button. If you select a track in the
<guilabel>Tracks</guilabel> selection box, the title, if present, will
appear in the <guilabel>Title</guilabel> field below. You can type a
title for the track in the box, or edit the entry to suit your
needs. Press the <keycap>Return</keycap> key on your keyboard, and the
text will appear in the proper line in the selection box.</para>

<para>Once all tracks have been given titles and the
<guilabel>Artist:</guilabel> and <guilabel>Title</guilabel> fields have
been filled out, you can press the <guibutton>Upload</guibutton>
button to send your submission by e-mail to freedb.</para>

<para>You will be prompted to select a category for the
submission. The <guilabel>Disc ID</guilabel> section displays the 32
bit <acronym>ID</acronym> code used by freedb to identify a compact
disc. Above the <acronym>ID</acronym> code is the category of the
<guilabel>freedb</guilabel> entry. These categories correspond to the
subfolders tree of the folder chosen in the <guilabel>freedb
Base Folder:</guilabel> in the <link
linkend="freedb-tab"><guilabel>freedb</guilabel> tab</link> of the &kscd;
Configuration window.</para>

<para>The <guilabel>Length:</guilabel> display shows the total play time of
the &CD;.</para>

<para>Press the <guibutton>Fetch Info</guibutton> button to download 
<acronym>CDDB</acronym> data.
Press the <guibutton>OK</guibutton> button to save your changes locally.
The <guibutton>Cancel</guibutton> button closes the &CD;
Database Editor without saving.</para>

</chapter>

<chapter id="using-kscd-in-the-panel">
<title>Using &kscd; in the &kde; Panel</title>

<screenshot>
<screeninfo>Using &kscd; in the &kde; Panel</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd18.png" format="PNG"/></imageobject>
<textobject><phrase>Using &kscd; in the &kde; Panel</phrase></textobject>
</mediaobject>
</screenshot>

<para>When the <guilabel>Show icon in system tray</guilabel> box is checked, a
small &kscd; applet is also displayed in the &kicker;. Unlike the main &kscd; window, this applet is available on
any desktop. <mousebutton>Right</mousebutton> click on the applet to pop up a
menu to control &CD; playback. A <mousebutton>left</mousebutton> click on the
applet hides the main &kscd; window. If the main window is hidden, a second
<mousebutton>left</mousebutton> click on the applet restores it. </para>

<note><para>To be precise, the applet is displayed in the <application>system
tray</application> in the panel. If no applet appears when &kscd; is minimized,
you may have removed the tray. To add it, <mousebutton>right</mousebutton> click
on an empty spot on the panel and select <menuchoice><guisubmenu>Add</guisubmenu>
<guisubmenu>Applet</guisubmenu> <guimenuitem>System Tray</guimenuitem>
</menuchoice></para></note>

</chapter>

<chapter id="cddb-support">
<title><acronym>CDDB</acronym> Support</title>

<para>freedb is a distributed network database accessible
over the Internet that contains information about most audio &CD;s in
circulation. If you have Internet access, you will likely never have to manually
enter track information for your &CD;s if you have this set up properly. See
<link linkend="freedb-tab">The freedb Tab</link> subsection in the configuring
&kscd; chapter for detailed instructions on how to configure this service, and
the <link linkend="cddb-editor">The CD Database Editor</link> section for
instructions on how to edit <acronym>CDDB</acronym> entries.</para>

<para>Use of the <acronym>CDDB</acronym> is free. Submissions from users are
encouraged.</para>

<para>When preparing entries for the <acronym>CDDB</acronym>, please keep the
following points in mind:</para>

<itemizedlist>
<listitem><para>Use <quote>standard</quote> latin characters in the entries. Some
special characters are supported, but Cyrillic or Greek alphabet submissions,
for example, cannot be accepted.</para></listitem>
<listitem><para>Use only one <keysym>/</keysym> character in the
<guilabel>Disc Artist / Title</guilabel> field in the &CD; Database
Editor.</para>

<para>For classical &CD;s, it is standard practice to put the composer's name in
the Artist section (before the slash) and the performer's name in the Title
section (after the slash).</para></listitem> 
<listitem><para>If you send an entry that already exists in the database, any
additional information you provide may be added to the existing entry.</para>
</listitem>
</itemizedlist>

<para>By default, &kscd; installs the standard <acronym>CDDB</acronym>
categories in <filename class="directory">$KDEDIR/share/apps/kscd/cddb</filename>. You can create as
many category subfolders as you like. However, when uploading, only the
official <acronym>CDDB</acronym> categories are displayed. The default upload
address is <email>freedb-submit@freedb.org</email>. For more information about
<abbrev>freedb</abbrev> visit the <abbrev>freedb</abbrev> homepage.</para>

<para>The local <acronym>CDDB</acronym> entry for a particular &CD; is stored in
the file <filename><replaceable>category name</replaceable>/<replaceable>disc
ID</replaceable></filename> under the <acronym>CDDB</acronym> Base
Folder. These files can be edited with any text editor if you have nothing
better to do with your spare time.</para>

</chapter>

<chapter id="troubleshooting">
<title>Troubleshooting the CD player</title>

<para>This section of the manual provides a step by step guide to troubleshooting your CD drive if the CD player will not play an audio &CD;</para>

<sect1 id="ts-begin">
<title>Begin troubleshooting</title>
<para>To begin, place an audio CD in your CD drive.  Close the CD drive door and press play on the &kscd; window.  Watch the CD drive on your computer and select the link below that best describes the problem.</para>
<para>When I pressed <guilabel>Play</guilabel>:</para>
<itemizedlist>
<listitem><para><link linkend="ts-errorbox">An error box appeared</link></para></listitem>
<listitem><para><link linkend="ts-playing">No error box appeared</link></para></listitem>
</itemizedlist>
</sect1>
<sect1 id="ts-playing">
<title>I did not get an error box, but no sound is coming out of my speakers</title>
<para>First, we will check to make sure the volume is turned up in &kscd;.</para>
<para>Near the upper right corner of the &kscd; window, locate the volume slider.  The volume slider looks like this:</para>
<screenshot>
<screeninfo>The Volume slider</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd9.png" format="PNG"/></imageobject>
<textobject><phrase>The Volume slider</phrase></textobject>
</mediaobject>
</screenshot>
<para>Click once on the vertical yellow bar and drag the bar all the way to the right end of the slider.</para>
<para>If you can hear music now, the problem is solved.  If you still can not hear the music, click 
<link linkend="ts-kmixlevels">here</link> to continue.</para>
</sect1>
<sect1 id="ts-kmixlevels">
<title>Determining if the mixer volume levels are up</title>
<para>The next step is to determine if &kmix; volume levels are appropriate.</para>
<note><para>&kmix; is a sound mixer panel that is included in &kde;.  This mixer allows you to adjust the relative volume levels of many sound components.</para></note>
<para>To start &kmix;, select 
<menuchoice><guimenu>K-Button</guimenu><guimenuitem>Multimedia</guimenuitem>
<guimenuitem>&kmix;</guimenuitem></menuchoice>.</para>
<para>Once &kmix; has started, you will be presented with a new window with a number of volume sliders.  Depending on the configuration, the sliders may have lables, or the labels may be hidden.  If you do not see any labels for the sliders, you should make the labels visible before continuing.  To make the labels visible, select 
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmix;...</guimenuitem></menuchoice> from the &kmix; window.  This will open a small window with a few check boxes. To 
turn the labels on, place a mark in the checkbox labeld <guilabel>Show labels</guilabel> and click <guibutton>OK</guibutton>.</para>
<para>Each slider controls the volume of a different audio device.  There are two parts to each device that may need to be altered.  If you look at a slider, there is a green 
light above each slider.  If you click on this light you can toggle between bright green and dark green.  If the light is dark green, that audio device is muted and will not produce any sound.  If the light is light green, the device is not muted.  Once you have verified that the device is not muted, you increase the volume of the device by draging the yellow bar up the slider.  The volume of an audio device is decreased by dragging the yellow bar down the slider.</para>
<note><para>Some sliders will have a red light as well.  This light is not important for playback of compact discs so you can ignore them for now.</para></note>
<para>Click on the tab labeled <guilabel>Output</guilabel>.</para>
<para>Please make sure the sliders are not muted (bright green light) and that the yellow bar is all the way at the top of the slider for the following audio devices:</para>
<itemizedlist>
<listitem><para><guilabel>Master</guilabel></para></listitem>
<listitem><para><guilabel>Master Mono</guilabel></para></listitem>
<listitem><para><guilabel>PC Speaker</guilabel></para></listitem>
<listitem><para><guilabel>PCM</guilabel></para></listitem>
</itemizedlist>

<para>If you still do not hear the &CD;, click on the tab labeled <guilabel>Input</guilabel></para>
<para>Now make sure the slider labeled <guilabel>CD</guilabel> is not muted (bright green light) and that the yellow bar is all the way at the top of the slider.</para>
<para>If you can hear the &CD; now, you can stop troubleshooting.  If not, click <link linkend="ts-othersounds">here</link> to continue</para>
</sect1>
<sect1 id="ts-othersounds">
<title>Determine if other sounds are audible on my computer</title>
<para>In this section, we are going to test to see if other types of sounds are audible on your computer. We will do this by playing a sound over the speakers that is stored on your hard drive.  </para>
<para>First we must locate an appropriate test file.  This will be done using the command line.</para>
<para>Select <menuchoice><guimenu>K-Button</guimenu><guimenuitem>System</guimenuitem>
<guimenuitem>&konsole;</guimenuitem></menuchoice>.  A new window will appear with a command prompt.  At the prompt type:</para>
<para><screen><prompt>$</prompt> <userinput><command>locate -n1 KDE_Window_Open.wav</command></userinput></screen></para>
<para>When you press return, there will be a pause, and a single line with a file location will be printed below your typed command.</para>
<para><screen><prompt>$</prompt> <userinput><command>locate -n1 KDE_Window_Open.wav</command></userinput>
/usr/local/kde/share/sounds/KDE_Window_Open.wav</screen></para>

<para>Now you are going to ask &kde; to play this short sound file. Type the text <command>noatun</command> followed by a space. Then copy the full location of the file you just located with the previous command.  For example: </para>
<para><screen><prompt>$</prompt> <userinput><command>noatun /usr/local/kde/share/sounds/KDE_Window_Open.wav</command></userinput></screen></para>
<para>If you heard a short sound, <link linkend="ts-othersoundsplay">click here</link>.</para>
<para>If you did not hear a short sound, your sound system is not configured correctly.  Click <link linkend="ts-noothersounds">here</link> to proceed.</para>
</sect1>

<sect1 id="ts-noothersounds">
<title>The test sound failed to play</title>
<para>So far, we have verified that the volume on &kscd; and all the mixer levels in &kmix; are set correctly.  We have also sent a test sound and you could not hear the sound played.  This suggests the trouble is not with &kscd; but rather with your sound configuration.</para>
<note><para>Please make sure the &CD; is still playing in your CD drive.</para></note>
<para>First, we need to make sure your speakers are plugged in and that the volume of your speakers is set appropriately.  If you are using external speakers, please check the following:</para>
<itemizedlist>
<listitem><para>Please make sure the speakers are connected to your computer appropriatly (see your user manual if necessary).</para></listitem>
<listitem><para>If your speakers require batteries, please replace the batteries with fresh batteries.</para></listitem>
<listitem><para>If your external speakers plug into the wall, please make sure they are plugged in to the socket, the power cord is securly plugged into the back of the speakers and the wall outlet is working.</para></listitem>
<listitem><para>If your speakers have a power button, please make sure the power is turned on.</para></listitem>
<listitem><para>If your speakers have a volume knob, please make sure the volume is turned half way between off and maximum.</para></listitem>
</itemizedlist>

<para>If your speakers are part of you computers case, please check to see if your speakers have a volume knob. If they do make sure the volume is turned half way between off and maximum.</para>

<para>If you have checked all of this, you probably need detailed help on getting the sound working on your computer. A full discussion of troubleshooting the sound system is beyond the scope of this manual and the user is referred to other internet sources. Some potential sources of information are:</para>

<itemizedlist>
<listitem><para><ulink url="http://www.tldp.org/HOWTO/Sound-HOWTO/index.html">Linux Sound HOWTO</ulink>.</para></listitem>
<listitem><para>The website of your distribution will probably have a user forum for asking questions.</para></listitem>
<listitem><para>Post a question to a Usenet newsgroup like comp.os.linux</para></listitem>
<listitem><para>Use a search engine to locate others who have encountered similar problems as you.</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="ts-othersoundsplay">
<title>The test sound played, but I can not hear the &CD;</title>
<para>So far, we have verified that the volume on &kscd; and all the mixer levels in &kmix; are set correctly.  We have also played a test sound and you were able to  hear the sound played.  This suggests the trouble is limited to &kscd; or the &CD;.</para>
<para>Check to make sure the &CD; is playable.  If this is a new &CD;, put it in another CD player (preferrably not located in a computer) and make sure the &CD; is playable in that device.  If it is playable in another device, continue <link linkend="ts-ddpback">here</link>.</para>
</sect1>

<sect1 id="ts-ddpback">
<title>Try using direct digital playback</title>
<para>There are two 
ways that personal computers can play a &CD;.</para>

<para>The first method (which &kscd; refers to as direct digital playback), is performed by reading the digital data from the 
&CD; using Digital Audio Extraction (DAE).  This data is sent to your machines CPU which converts the digital data to sound.  This method requires 
a &CD; drive that is capable of DAE (most new drives are) and it requires some CPU processing time to generate the sounds you hear.</para>

<para>The second method uses the internal circuitry available on many &CD; drives to read the data and generate the sounds you will hear 
without using your computers CPU.  This data is transmitted by a dedicated cable directly to the sound card in your computer.  This method requires 
less CPU proccessing time, but it does require that the dedicated cable be connected inside your computer.  Not all computers have this connection.</para>

<para>&kscd; defaults to the second method of playback.  The next step in troubleshooting your &CD; problems is to enable direct digital playback. To do this begin by clicking on the button labeled <guibutton>Stop</guibutton> on the &kscd; window. This will stop any attempt to play the &CD; for now.</para>

<para>Now click on the button labeled <guibutton>Extras</guibutton>.  This will open a small menu.  Select <guilabel>Configure &kscd;...</guilabel>.  This will open a new dialog box.</para>
<para>Click the icon labeled <guilabel>CD Player</guilabel> on the left side of the dialog box.</para>
<para>Place a mark in the checkbox labeled <guilabel>Use direct digital playback</guilabel>.</para>
<para>Click <guibutton>OK</guibutton>.  </para>
<para>Now click <guibutton>Play</guibutton> in the &kscd; window and see if the &CD; begins to play correctly.</para>

<para>If you still can not hear the music on the &CD;, your problem requires specific knowledge of your system and the problems you encounter.  The reader is referred to many good internet resources for this information.  Please consider finding help in one of the following ways:</para>

<itemizedlist>
<listitem><para>The website of your distribution will probably have a user forum for asking questions.</para></listitem>
<listitem><para>Post a question to a Usenet newsgroup like comp.os.linux or an IRC channel for users of your operating system</para></listitem>
<listitem><para>Use a search engine to locate others who have encountered similar problems as you.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="ts-errorbox">
<title>An error box appeared</title>
<para>Probably the most common error boxes seen is this one:</para>
<screenshot>
<screeninfo>Error dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd19.png" format ="PNG"/></imageobject>
<textobject><phrase>Error dialog</phrase></textobject>
</mediaobject>
</screenshot>

<para>Information about fixing this dialog box is available in the <link linkend="questions-and-answers">Questions and 
answers</link> section of this manual.</para>

<para>If you recieve another error box, you should post the text from the error box on a forum for your distribution or enter this text in a search engine such 
as <ulink url="http://www.google.com">Google</ulink>.</para>
</sect1>
</chapter>

<chapter id="questions-and-answers">
<title>Questions and answers</title>

<qandaset>
<qandaentry>
<question><para>I see this dialog when I start &kscd;.  What's wrong?</para>
<screenshot>
<screeninfo>Error dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kscd19.png" format ="PNG"/></imageobject>
<textobject><phrase>Error dialog</phrase></textobject>
</mediaobject>
</screenshot>
</question>
<answer><para>This means that &kscd; couldn't open your &CD-ROM; drive. The name of
the device in the <guilabel>&CD-ROM; Device</guilabel>cdrom field of the
<guilabel>Kscd Configuration</guilabel> must actually refer to the block device
associated with your &CD-ROM; drive. This will often be a hardlink to the
appropriate <acronym>IDE</acronym> (<filename>/dev/hdx</filename>) or
<acronym>SCSI</acronym> (<filename>/dev/sdx</filename>) device.</para>

<para> The device file normally belongs to user root in group root, and does not
allow normal users to open it for reading, writing, or execution directly. This
has <emphasis>nothing</emphasis> to do with the <application>SUID</application>
(Set User <acronym>ID</acronym> programs use the <function>setuid()</function>
function in the standard Un*x library to assume the identity of another user)
<command>mount</command> command, which has no problems with permissions; &kscd;
must be able to get a read-only file descriptor referring to the &CD; device to
control the &CD-ROM; drive and read raw data off the disk.</para>

<para> If you have the root password, you can fix this quickly and easily.
Become root and type <userinput><command>chmod</command> <option>a+r</option>
<filename><replaceable>/dev/cdrom</replaceable></filename></userinput> to allow
any user on your system to read from <filename>/dev/cdrom</filename>.  If your
&CD-ROM; device is called something else, change the permissions on that device
with the same procedure. If you don't have the root password, ask your system
administrator nicely to give you read permission for the &CD-ROM; device.</para>

<para>See also the chapter on <link linkend="configuring-kscd">configuring KSCD
</link></para></answer>
</qandaentry>

<qandaentry> 
<question><para>I can not get the <acronym>CDDB</acronym> to work. Can I get any
detailed information about what may be going wrong?</para></question> 
<answer><para>If you experience trouble with the <acronym>CDDB</acronym>
functionality try to starting &kscd; from the command line with the
<option>-d</option> switch and observe the debug output.</para></answer> 
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits-and-license">
<title>Credits and licenses</title>

<para>&kscd; Copyright 1997,1998 &Bernd.Johannes.Wuebben; 
&Bernd.Johannes.Wuebben.mail;</para>

<para>&kscd; contains code from: </para>
<itemizedlist>
<listitem><para><application>workman</application> 1.4 beta 3 Copyright (c)
Steven Grimm <email>koreth@hyperion.com</email></para></listitem>
</itemizedlist>


<para>Special thanks to Ti Kan and Steve Scherf, the inventors of the
<acronym>CDDB</acronym> database concept. Visit <ulink
url="http://www.cddb.com/">http://ww.cddb.com</ulink> for more information on
<acronym>CDDB</acronym>.</para>

<para>A very special thank you also to David White who wrote the original &kscd;
help documention. Great Job David!</para>

<para>Documentation updated for KDE 2.0, and copyright by &Jonathan.Singer; 
&Jonathan.Singer.mail;</para>

<para>Documentation updated for KDE 3.4, and copyright by &Mike.McBride; 
&Mike.McBride.mail;</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="how-to-obtain-kscd">
<title>How to obtain &kscd;</title>

&install.intro.documentation;

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile &kscd;, you need the latest versions of
the KDE libraries as well as the &Qt; C++ library.  All required libraries as
well as &kscd; itself can be found at the &kde; &FTP; site, &kde-ftp;.</para>

</sect1> 

<sect1 id="compilation-and-installation"> 
<title>Compilation and Installation</title> 

&install.compile.documentation;
	
<para>Please inform the current maintainer, Aaron Seigo, at
&Aaron.J.Seigo.mail; of any modification you had to undertake in
order to get &kscd; to compile on your platform.</para>

</sect1>

</appendix>

&documentation.index; 
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->