# The &kscd; Handbook

Jonathan
Singer

    jsinger@leeta.net

David
White

    a9403784@unet.univie.ac.at

Bernd
Johannes
Wuebben

    wuebben@kde.org

Developer
Dirk
Forsterling

    milliByte@gmx.net

Developer
Dirk
Foersterling

    milliByte@gmx.net

Developer
Lauri
Watts

    vampyr@atconnex.net

Reviewer
2000
J Singer
&FDLNotice;
08/02/2001
1.03.00

&kscd; is a small, fast, CDDB enabled audio CD player for Unix platforms.

KDE
kdemultimedia
kscd
music
CD
audio

## Introduction

&kscd; is a fast, CDDBcddb 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

wuebben@kde.org

### 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 toggles looping, so that the &CD; will start playing again from the beginning when the end of the last audio track is reached. The buttons in the third row advance the &CD; backward (left) or forward (right) 30 seconds. The buttons in the fourth row skip forward (right) or backward (left) to the beginning of the next or previous track.

#### The eject button

The eject button
The eject button

This button ejects the &CD;. Note that the eject button on your &CD-ROM; drive may not respond if an audio &CD; is in the drive and &kscd; is started. Some very old &CD-ROM; drives may not support software eject. You may also have to close the &CD-ROM; drive manually after inserting a new disc.

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

#### Time display modes

The time display toggle
The time display toggle

This button toggles 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. Pressing this button toggles in sequence between remaining track time, total elapsed time, and total remaining time.

#### The Configuration button

The configuration panel
The configuration panel

This button opens the &kscd; configuration panel. This allows you to configure &kscd; to work on your machine. See the configuring &kscd; section, for details about configuring &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 information button

The information button
The information button

This button will 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 pop-up menu that appears.

#### The exit button

The exit button
The exit button

This button closes &kscd;.

#### The volume slider

The volume slider
The volume slider

This slider controls the volume of the audio output of the &CD;. Right is louder, left is quieter. If you are playing your &CD; through your sound card, the sound card mixer will affect the playback volume as well.

#### The randomise button

The randomise button
The randomise button

This button plays the &CD; tracks in random order.

#### The track selector

The track selector
The track selector

This combo box lets you directly select a track to play.

## Configuring &kscd;

### The primary configuration window

The primary configuration window for &kscd; is a tabbed dialog with four major sections.

- CDDB

- SMTP Options

- KSCD options

- About

### The CDDB tab

The CDDB tab of the configuration dialog
The CDDB tab of the configuration dialog

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

The Enable Remote CDDB checkbox turns on or off CDDB lookups over the Internet. The time allowed before the lookup attempt times out can be set. To use an &HTTP; proxy, check the Use HTTP proxy to access CDDB and enter the &URL; in the field below.

The CDDB Base Directory text field lets you choose the directory where you want CDDB entries to be stored locally.

The CDDB Server list box shows a list of known CDDB servers. Select an entry from this list and it will appear in the text field above the selection box. Press the Update button to update the list of servers in the list box. Press the Defaults button to enter the default value, `freedb.freedb.org 888 -`, which will permit you to update the list with a fresh list of CDDB Servers listed with the master CDDB site at freedb.freedb.org. Hit the - button to delete the selected entry from the list.

The Send CDDB submissions to: field contains the e-mail address to submit CDDB entries to. The default address is freedb-submit@freedb.org. As of version 0.8, CDDB entries from &kscd; are accepted for inclusion in the database. Hit the - button to delete the selected entry from the list. The Defaults button restores all settings to the default values.The Help button opens the &kscd; help home page (this document).

OK saves the current settings and exits; Cancel exits without saving.

### The SMTP Options tab

The SMTP Options tab

The SMTP options tab sets up connection to a mail server to submit new CDDB entries. This is useful if you do not have your own system configured as a server. Check Enable submission via SMTP to use this feature. Enter the address of the SMTP server in the upper left text field and the port number (typically `25`) in the upper right field. Enter your own email address in the lower text field.

### The KSCD Options tab

The KSCD Options tab
The KSCD Options tab

The LED Color: and Background Color: fields show the color selected for the foreground and background of the status display. Press the Change button next to the color box to change these colors.

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

The Unix mail command field shows the command used to send new CDDB entries to the database. The default value is ``mail` `-s %s``. You will need to make sure this command will actually send mail to non-local systems if you want to submit CDDB 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 e-mail require only that you enter your mail host into the "Smart" relay host field in `/etc/sendmail.cf`. In addition, the CDDB site will want to be able to mail you back; it may therefore also be necessary to edit `/etc/sendmail.cf` to ensure that the return address on the submission is valid. Your mileage is likely to vary. If all else fails, use SMTP instead.

The WWW-Browser section lets you choose which web browser to use to access the web sites in the information button menus. You can choose either &konqueror; or a custom browser with the radio buttons. By default, the Use Custom Browser field contains ``netscape` `%s``, for use with Netscape Navigator or Communicator.

The Show Tool Tips checkbox turns tooltips (tiny windows that pop up when the mouse is parked briefly over a control) on or off.

Enable KPanel Docking causes a &kscd; control to appear in the &kicker; panel.

Play on Tray Close causes &CD; play to start when the tray is closed, with no need to press the Play button.

Stop Playing on Exit causes &CD; playback to stop when &kscd; is closed.

Eject on Finish causes the &CD; to be ejected when playback ends.

Random is Shuffle means that when random play is used, each track is played only once.

The Help button opens the &kscd; help contents page.

OK saves the current settings and exits; Cancel exits without saving.

### The About tab

The About tab displays information about the version of &kscd; you are using and some copyright information.

## 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 CDDB, you will see the name of the artist and the title of the &CD; in the Disc Artist / Title field and a list of tracks with song titles in the Track / Time / Title 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 Ext Info button next to the Disc Artist / Title field, or for a selected track in the Track / Time /Title selection box with the adjacent Ext Info button. If you select a track in the Track / Time / Title selection box, the title, if present, will appear in the Edit Track 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 Disc Artist / Title field has been filled out, you can press the Submit button to send your submission by e-mail to the CDDB.

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

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

The Play List Editor lets you change the play order of a disc. Enter a comma-separated list of track numbers to define a new play order.

The Save button writes the displayed record to disk. You will be prompted to select a category under which to save the record. Select a directory and press Ok to finish saving.

The Load button will prompt you for a location to look for a CDDB entry other than a remote CDDB server or the local CDDB entries in the file system. The Close 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 Enable KPanel Docking box is checked, a small &kscd; applet is also displayed in the KDE 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 left click on the applet takes you to the main &kscd; window. If the main window is minimized, a 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

The Compact Disc Data Base 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 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 subdirectories as you like. However, when uploading, only the offical CDDB categories are displayed. The default upload address is xmcd-cddb@amb.org. For more information about CDDB visit the CDDB homepage.

The local CDDB entry for a particular &CD; is stored in the file `category name/disc ID` under the CDDB Base Directory. 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 CDROM 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't 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 wuebben@kde.orgwuebben>

&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 jsinger@leeta.net.

&underFDL; &underGPL;

## Installation

### How to obtain &kscd;

&kscd; is part of the KDE Project. &kscd; can be found in the kdemultimedia package on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### 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, ftp://ftp.kde.org/pub/kde/.

### Compilation and Installation

In order to compile and install &kscd; on your system, type the following in the base directory of the &kscd; distribution:

    % ./configure
    % make
    Then as root:
    % make install

Please inform the current maintainer, Dirk Foersterling, at milliByte@gmlx.net of any modification you had to undertake in order to get &kscd; to compile on your platform.