# The &kscd; Handbook

## Introduction

&kscd; is a fast, CDDB enabled &CD; player for &UNIX;, &Windows; and &MacOS; platforms. &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

- &Windows;

- &MacOS;

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 Extras 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 drop down 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;... to 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 CD Player 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 check box labeled Show icon in system tray causes a &kscd; control to appear in the &kicker; panel.

Placing a mark in the check box 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

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 check box labeled Use direct digital playback determines which method &kscd; uses to read the audio tracts. If there is a mark in the check box, the first method is used. If there is no mark in the check box, the second method is utilized.

If you have selected direct digital playback, a drop down box labeled Select audio backend will let you select which sound backend the digital information should be sent to. The contents of the drop down box will vary depending on your system. Most users should select phonon. 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 check box 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 CDDB Page

The CDDB page is divided in the Lookup tab and the Submit tab.

#### The Lookup Tab

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

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

You can select the options Enable MusicBrainz lookup or Enable freedb lookup.

The Freedb 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 Submit Tab

The Submit tab

The 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, enter your email address into the first textbox, then 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 text box labeled Reply-To:, your email server in the text box labeled SMTP server: and select the port number in the spinbox labeled Port:.

If you need to use a password to send email using the email server, place a mark in the check box labeled Server needs authentication and enter your username in the text box 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 field 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 email 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 CDDB page 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 panel. 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 &LMB; click on the applet hides the main &kscd; window. If the main window is hidden, a second &LMB; 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 Widgets.... In the upcoming dialog, choose 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 CDDB Page 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.

## 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; Device 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 cannot 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://www.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;