# The &kscd; Handbook

## Introduction

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

New: the `workman2cddb.pl` Perl script provided in order to facilitate transition for users of workman.

I hope you will enjoy this &CD; player.

&Bernd.Johannes.Wuebben;

&Bernd.Johannes.Wuebben.mail;

### Supported Platforms

&kscd; explicitly supports the following platforms:

- &Linux;

- FreeBSD

- NetBSD

- BSD386

- Sun

- &Solaris; (including cdda support)

- &HP-UX;

- &SGI; Irix (including cdda support)

- Sony NEWS

- OSF/1

- Ultrix

and should compile on many others with few modifications.

## Onscreen fundamentals

### Basic Operation

The &kscd; Interface The &kscd; Interface

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.

#### The Control Panel

The Control Panel The Control Panel

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.

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.

#### The Status Display

The Status Display The Status Display

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 CDDB (&CD; Data Base.)

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 ––:–– 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.

#### The Configuration button

The Extras button The Extras button

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 the configuring &kscd; section, for details about configuring &kscd;

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.

This menu also allows you to open this help document, report bugs, learn more about &kscd; and &kde; and to quit &kscd;.

#### The CDDB button

The CDDB button The CDDB button

This button opens the CDDB (Compact Disc Data Base) entry editor panel.

The CDDB can identify your &CD; and often download a list of tracks for that &CD; or load it from the filesystem. See the &CD; Database Editor section for more details about using this tool.

#### The Volume slider

The Volume slider The Volume slider

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.

#### The track selector

The track selector The Track selector

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

## Configuring &kscd;

### The primary configuration window

You configure &kscd; by clicking on the Extras button. This will bring up a menu, select Configure &kscd;.... This will open a new window.

The primary configuration window for &kscd; is divided into two major sections.

- CD Player to determine the look and behavior of &kscd;.

- CDDB which is used to configure the CDDB lookup features of &kscd;.

You can switch between these two sections using the icons on the left side of the dialog.

### The CD Player dialog

The CD Player dialog The KSCD Configuration dialog

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

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

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

Placing a mark in the checkbox labeled Show track announcement 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.

Sample track announcement Sample track announcement

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

Autoplay when CD inserted causes &kscd; to start playing the &CD; when the tray is closed, with no need to press the Play button.

Eject CD when finished playing causes the &CD; to be automatically ejected when playback ends.

Stop playing CD on exit causes &CD; playback to stop when &kscd; is closed.

The CD-ROM Device field contains the name of the &CD-ROM; device to be used to play audio &CD;s. The default value is `/dev/cdrom`. 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;.

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

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.

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.

The checkbox labeled Use direct digital playback 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.

If you have selected direct digital playback, a dropdown box labeled Select audio backend: 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 arts. You can also select the device the audio backend uses by entering the device location in the text box labeled Select audio device:. A full discussion of audio devices and audio backends is beyond the scope of this manual.

If a mark is placed in the checkbox labeled Allow encoding selection, you can select the text encoding for the results of a CDDB request.

The standard describes CDDB results as being strictly Latin 1. If you are not having problems with your CDDB information, leave this box unchecked.

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

### The freedb Lookup tab

The freedb Lookup tab of the configuration dialog The freedb Lookup tab of the configuration dialog

The freedb Lookup tab sets up the CDDB functions of &kscd;.

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

The CDDB Server: 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 Show Mirror List 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 OK.

The section labeled Cache locations 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 Add. 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 Remove. You can change the order that &kscd; searches the folders by clicking on the folder name and clicking on the Move Up and Move Down buttons.

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

### The freedb Submit tab

The freedb Submit tab

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

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

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.

First select either &HTTP; or SMTP (Email) to determine which protocol to use.

#### Using &HTTP; to send CDDB information

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.

#### Using SMTP (Email) to send CDDB information

To prepare to submit information using email, enter your email address in the textbox labeled Reply-To:, your email server in the textbox labeled SMTP-server: and select the port number in the dropdown box labeled Port:.

If you need to use a password to send email using the email server, place a mark in the checkbox labeled Server needs authentication and enter your username in the textbox labeled Username:.

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

## The CD Database Editor

The &CD; Database Editor The &CD; Database Editor

The &CD; Database Editor allows you to modify, download, save, annotate, and upload CDDB (Compact Disc Data Base) entries.

If there is an entry in your local CDDB tree (see the CDDB subsection 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 Artist: and Title fields and a list of tracks with song titles in the Tracks selection box. Otherwise, you will see a list of tracks and play times without titles.

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

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

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

The Length: display shows the total play time of the &CD;.

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

## Using &kscd; in the &kde; Panel

Using &kscd; in the &kde; Panel Using &kscd; in the &kde; Panel

When the Show icon in system tray 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. Right click on the applet to pop up a menu to control &CD; playback. A left click on the applet hides the main &kscd; window. If the main window is hidden, a second left click on the applet restores it.

To be precise, the applet is displayed in the system tray in the panel. If no applet appears when &kscd; is minimized, you may have removed the tray. To add it, right click on an empty spot on the panel and select Add Applet System Tray

## CDDB Support

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 The freedb Tab subsection in the configuring &kscd; chapter for detailed instructions on how to configure this service, and the The CD Database Editor section for instructions on how to edit CDDB entries.

Use of the CDDB is free. Submissions from users are encouraged.

When preparing entries for the CDDB, please keep the following points in mind:

- Use standard latin characters in the entries. Some special characters are supported, but Cyrillic or Greek alphabet submissions, for example, cannot be accepted.

- Use only one / character in the Disc Artist / Title field in the &CD; Database Editor.

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

- If you send an entry that already exists in the database, any additional information you provide may be added to the existing entry.

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

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

## Troubleshooting the CD player

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;

### Begin troubleshooting

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.

When I pressed Play:

- An error box appeared

- No error box appeared

### I did not get an error box, but no sound is coming out of my speakers

First, we will check to make sure the volume is turned up in &kscd;.

Near the upper right corner of the &kscd; window, locate the volume slider. The volume slider looks like this:

The Volume slider The Volume slider

Click once on the vertical yellow bar and drag the bar all the way to the right end of the slider.

If you can hear music now, the problem is solved. If you still can not hear the music, click here to continue.

### Determining if the mixer volume levels are up

The next step is to determine if &kmix; volume levels are appropriate.

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

To start &kmix;, select K-Button Multimedia &kmix;.

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 Settings Configure &kmix;... 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 Show labels and click OK.

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.

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.

Click on the tab labeled Output.

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:

- Master

- Master Mono

- PC Speaker

- PCM

If you still do not hear the &CD;, click on the tab labeled Input

Now make sure the slider labeled CD is not muted (bright green light) and that the yellow bar is all the way at the top of the slider.

If you can hear the &CD; now, you can stop troubleshooting. If not, click here to continue

### Determine if other sounds are audible on my computer

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.

First we must locate an appropriate test file. This will be done using the command line.

Select K-Button System &konsole;. A new window will appear with a command prompt. At the prompt type:

    $ locate -n1 KDE_Window_Open.wav

When you press return, there will be a pause, and a single line with a file location will be printed below your typed command.

    $ locate -n1 KDE_Window_Open.wav
    /usr/local/kde/share/sounds/KDE_Window_Open.wav

Now you are going to ask &kde; to play this short sound file. Type the text `noatun` followed by a space. Then copy the full location of the file you just located with the previous command. For example:

    $ noatun /usr/local/kde/share/sounds/KDE_Window_Open.wav

If you heard a short sound, click here.

If you did not hear a short sound, your sound system is not configured correctly. Click here to proceed.

### The test sound failed to play

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.

Please make sure the &CD; is still playing in your CD drive.

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:

- Please make sure the speakers are connected to your computer appropriatly (see your user manual if necessary).

- If your speakers require batteries, please replace the batteries with fresh batteries.

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

- If your speakers have a power button, please make sure the power is turned on.

- If your speakers have a volume knob, please make sure the volume is turned half way between off and maximum.

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.

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:

- Linux Sound HOWTO.

- The website of your distribution will probably have a user forum for asking questions.

- Post a question to a Usenet newsgroup like comp.os.linux

- Use a search engine to locate others who have encountered similar problems as you.

### The test sound played, but I can not hear the &CD;

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

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

### Try using direct digital playback

There are two ways that personal computers can play a &CD;.

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.

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.

&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 Stop on the &kscd; window. This will stop any attempt to play the &CD; for now.

Now click on the button labeled Extras. This will open a small menu. Select Configure &kscd;.... This will open a new dialog box.

Click the icon labeled CD Player on the left side of the dialog box.

Place a mark in the checkbox labeled Use direct digital playback.

Click OK.

Now click Play in the &kscd; window and see if the &CD; begins to play correctly.

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:

- The website of your distribution will probably have a user forum for asking questions.

- Post a question to a Usenet newsgroup like comp.os.linux or an IRC channel for users of your operating system

- Use a search engine to locate others who have encountered similar problems as you.

### An error box appeared

Probably the most common error boxes seen is this one:

Error dialog Error dialog

Information about fixing this dialog box is available in the Questions and answers section of this manual.

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

## Questions and answers

I see this dialog when I start &kscd;. What's wrong?

Error dialog Error dialog

This means that &kscd; couldn't open your &CD-ROM; drive. The name of the device in the &CD-ROM; Devicecdrom field of the Kscd Configuration must actually refer to the block device associated with your &CD-ROM; drive. This will often be a hardlink to the appropriate IDE (`/dev/hdx`) or SCSI (`/dev/sdx`) device.

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 nothing to do with the SUID (Set User ID programs use the `setuid()` function in the standard Un*x library to assume the identity of another user) `mount` 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.

If you have the root password, you can fix this quickly and easily. Become root and type ``chmod` `a+r` ``/dev/cdrom``` to allow any user on your system to read from `/dev/cdrom`. 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.

See also the chapter on configuring KSCD

I can not get the CDDB to work. Can I get any detailed information about what may be going wrong?

If you experience trouble with the CDDB functionality try to starting &kscd; from the command line with the `-d` switch and observe the debug output.

## Credits and licenses

&kscd; Copyright 1997,1998 &Bernd.Johannes.Wuebben; &Bernd.Johannes.Wuebben.mail;

&kscd; contains code from:

- workman 1.4 beta 3 Copyright (c) Steven Grimm koreth@hyperion.com

Special thanks to Ti Kan and Steve Scherf, the inventors of the CDDB database concept. Visit http://ww.cddb.com for more information on CDDB.

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

Documentation updated for KDE 2.0, and copyright by &Jonathan.Singer; &Jonathan.Singer.mail;

Documentation updated for KDE 3.4, and copyright by &Mike.McBride; &Mike.McBride.mail;

&underFDL; &underGPL;

## Installation

### How to obtain &kscd;

&install.intro.documentation;

### Requirements

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

### Compilation and Installation

&install.compile.documentation;

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.

&documentation.index;