General Information
-------------------

 cdcd takes a different approach from conventional console (or X)
 based CD players, in that it doesn't keep with the display-oriented
 paradigm.  Conventional computer-based CD players resemble
 traditional physical CD players.  This is fine, if your user
 interface consists of 10 buttons.  However, computers have keyboards,
 so why not use them?  Besides, it's certainly a waste of a console or
 an xterm to have a traditional CD player open anyway.

 cdcd works in two ways, accepting commands directly off the command
 line or in a query mode similar to other UNIX programs.  To pass a
 command to cdcd, simply run cdcd with the command as the arguement
 (e.g. cdcd play).  This is great for using cron and cdcd together to
 make a CD alarm clock.  Or, you can run cdcd without arguments and
 you will be given the cdcd command prompt.

 For information regarding cdcd and new releases, visit
 http://libcdaudio.sourceforge.net/ .

Installation
------------

 For help with installation, please see the file INSTALL.

Usage
-----

 Preliminary note: this file is less often updated than the source
 files, so you may see some changes between the outputs shown here and
 the outputs you get. 

 After cdcd is installed, type 'cdcd'.  You should receive a prompt
 like this:

 cdcd x.x.x, Copyright (C)1998-99 Tony Arcieri, 2001 Fabrice Bauzac
 Distributed under the GNU General Public License. See file COPYING
 for details.
 Using libcdaudio x.x.x
 Enter ? for help.
 cdcd>

 Enter a command, for example, help:

 cdcd> help
 Available commands: 
 !, ?, access, close, debug, device, edit, eject, exit, ext, ff,
 getvol, help, info, list, next, open, pause, play, prev, quit,
 refresh, resume, rew, rndplay, setvol, sites, slot, status, stop,
 submit, tracks, verbose, and version.
 For more specific help, type `help <command>'.
 cdcd> 

 As you can see, the command will perform its function, and then
 return you to the command prompt.

 You can receive help on specific items by passing an argument to the
 help function:

 cdcd> help play
 Usage: play [starttrackname/track #] [endtrackname/track #] [min:sec]
 By default, starts at the beginning of the CD.  You may specify
 tracks using either the number of the track or a section of the
 track's name.  The disc will play from where it starts to the end of
 the disc or a track you specify.  You may also specify a position
 within the first track to start.
 cdcd> 

 By default, play starts at the beginning of the CD.  You may specify
 tracks using either the number of the track or a section of the
 track's name.  The disc will play from where it starts to the end of
 the disc or a track you specify.  You may also specify a position
 within the first track to start.

 To play a CD, you can simply type 'play', or if you prefer, 'play
 <trackname>', or 'play track#.'  You may also specify a track at
 which to end play, and also a time within the track to start.  Here
 are a few examples:
 
 cdcd> play 5
	This would play track #5 and stop at the end of the disc.

 cdcd> play Time
 	This would play the first song on the disc with "Time" as a
	part of its name and stop at the end of the disc.

 cdcd> play Time 5
	This would play the first song on the disc with "Time" as part
	of its name and stop at track #5.

 cdcd> play Time 3:30
	This would play the first song on the disc with "Time" as part
	of its name and start 3 minutes and 30 seconds into the song
	and stop at the end of the disc.

 cdcd> play 3 5 3:30
	This would play from track 3 to track 5 and start 3:30 into
	track 3.

 cdcd> play 3 "Us and Them" 5:
	This would play from track 3 to the first song on the disc
	with "Us and Them" as part of its title and start 5:00 into
	track 3.

 cdcd> play 5 5
 	This would play track 5 and stop at the end of track 5; an
	easy way to play only a single track.

 cdcd> play 3:30
	This would set the postition within the current song to 3:30.

 Some commands put you into a cdcd subshell.  For example, type:

 cdcd> sites
 cdcd/sites>

 Then you can ask for some help to see the available commands:

 cdcd/sites> ?
 Available commands: 
 .., ?, add, del, display, exit, help, move, quit, and refresh.
 For more specific help, type `help <command>'.
 cdcd/sites>

 You can use the special command `..' to return one level up in the
 shells hierarchy.

 cdcd/sites> ..
 cdcd>

 If you are in interactive mode and are finished, simply type `quit'
 and RETURN, or C-d (^D, Control + D).  The CD will continue playing:
 
 cdcd> quit
 $

 You can also pass commands to cdcd right off the command line:

 $ cdcd info
 Album name:     The Dark Side Of The Moon
 Album artist:   Pink Floyd
 Total tracks:   9       Disc playing:   07:37 of 42:59
 Playing:        Time 03 00:01 of 07:05
 $

CDDB Interface
--------------

 As of libcdaudio-0.4.2 (and cdcd-0.3.2), cdcd supports the CD
 Database system, which allows retrieval of CD information off of the
 Internet.  The CDDB interface is on by default.  Whenever a command
 is invoked that uses CD database information (e.g. play, ext, info,
 infoall) libcdaudio will search in the local cache (located under
 ~/.cddb) first, and if it is unable to locate information for the
 current CD, it will connect to a CDDB server and attempt to retrieve
 it.  If this is the first time you've used a particular CD with cdcd,
 you may notice a 5-10 second delay with the previously mentioned
 commands.  This is because cdcd is connecting to the CDDB server and
 retrieving disc information.  As soon as this has been completed, the
 command will no longer block, and you will be given the shell prompt
 or cdcd command prompt again.

 Perhaps you don't like automated CDDB operation.  You can enable or
 disable verbose, manual CDDB operation using the verbose command:

 cdcd> verbose on
 cdcd>

 From now on, any command that uses the CDDB code will tell you
 exactly what it is doing:

 cdcd> info
 Trying cddbp://www.cddb.com:8880/
 Connection established.
 Retrieving information on 770f0d19.
 Inexact match for 770f0d19.
 Please choose from the following inexact matches:
 1: The Beach Boys / Made In U.S.A.
 2: None of the above.
 > 1
 Downloading data...
 Album name:     Made In U.S.A.
 Album artist:   The Beach Boys
 Total tracks:   25      Disc length:    64:15
 Stopped
 cdcd>
 
 Of course, all of that will only happen the first time you use the
 disc with cdcd.  Normally the CDDB information will simply stay
 cached in ~/.cddb.

 As of libcdaudio-0.4.3, a caching system compatible with XFreeCD and
 other CD players is used.  This allows you to read CD information
 from discs played using these other players.

 As of libcdaudio-0.4.4, extended information is supported.  In cdcd,
 you can display extended information (if it is available) using the
 ext command.
 
CD-ROM Changer Support
----------------------

 Linux 2.1 and 2.2 users with CD-ROM changers may take advantage of
 the CD-ROM changer functions within cdcd.

 To use your CD-ROM changer with cdcd, there are only two functions
 you must know, list and seldisc:

 cdcd> list
 Disc 1:	42:59 Pink Floyd / The Dark Side of the Moon
 Disc 2:	44:28 Pink Floyd / Wish You Were Here
 Disc 3:	42:39 Led Zeppelin / IV
 cdcd>

 The list command displays the contents of your CD-ROM changer.  To
 choose a particular disc from the CD-ROM changer, use the slot
 command:

 cdcd> slot 1

Controlling CDDB Operation
--------------------------

 As of libcdaudio 0.6.1, cdcd uses a radically different CDDB
 interface.  If you previously generated a ~/.cddbrc you should delete
 it.

 All CDDB operations use specific URLs for the server.  To use the
 CDDB server cddb.cddb.com that operates on port 8880, you should use
 the following URL:

 cddbp://cddb.cddb.com:8880

 If instead, you wished to use the HTTP server www.cddb.com port 80,
 use:

 http://www.cddb.com:80/~cddb/cddb.cgi

 Notice /~cddb/cddb.cgi on the end.  This is the path to the actual
 CDDB CGI, and must be used with any HTTP URL.

 To automatically update the CDDB server list, use the 'sites/refresh'
 command.  Any further CDDB operations will pull entries from this
 list.  If the first server fails, it will automatically go on to the
 next one, until it has exhausted the whole list.

Tuning Readline
---------------

 You can easily add shortcuts for usual commands, by tweaking your
 ~/.inputrc file.  Here is an example:

 ~/.inputrc: -----
  $if cdcd
  "\e[[A": "open\n"    # F1 will open the CD tray
  "\e[[B": "close\n"
  "\e[[C": "play\n"
  "\e[[D": "prev\n"
  "\e[[E": "next\n"
  "\C-xw": "prev\n"    # C-x w will select the previous track
  "\C-xx": "play\n"
  "\C-xc": "pause\n"
  "\C-xC": "resume\n"
  "\C-xv": "stop\n"
  "\C-xb": "next\n"
  $endif
  -----

  Remember: to type C-x w, hold down Control, then type x once, then
  release the Control key, and type w once.

Bugs
----

 All bug reports should be sent to noon@users.sourceforge.net.
  
 cdcd has been tested under many versions of Linux, and FreeBSD 3.0.
 If you do experience problems either compiling or while operating
 cdcd, please send the following:
 
 * The version of cdcd you are using.

 * The version of libcdaudio you are using.

 * Your platform type and release.

 * A complete list of errors that occurred either during the compile
   (make >& errors) or a detailed description of what happened while
   cdcd was in operation.

 * Any other information you believe is relevant.

Patches
-------

 If you think you can do something better than the existing code, by
 all means, send me the patch!  Send all patches to
 noon@users.sourceforge.net.  Be sure to include your name so I can
 credit your code.  If the patch fixes a bug, it would be nice if you
 send the patch along with the bug report.

A few final words
-----------------

 cdcd is distributed under the GNU General Public License, included in
 this package under the top level directory in the file COPYING.

 libcdaudio is distributed under the GNU Library General Public
 License, either included in this package as libcdaudio/COPYING.LIB or
 if obtained seperately, under the top level directory of libcdaudio
 in the file COPYING.LIB.