CDTOOL 2.1.6, 20/07/2004, Max Vozeler <max@hinterhof.net>
=========================================================

    CDTOOL is a free software package to control the audio functions
of an attached CDROM drive from the command line in a quick, simple
and scriptable way.

    CDTOOL consists of several programs. Actually, most of them are
really one program that can be called with multiple different names.
These commands are included:

    cdplay    -- play the CDROM or resume from pause.
    cdstart   -- alternate name for cdplay (for those with cdp/cdplay).
    cdpause   -- pause play.
    cdstop    -- stop play.
    cdeject   -- eject the CDROM, if supported.
    cdclose   -- close the CDROM tray, if supported.
    cdir      -- list tracks on the CDROM.
    cdinfo    -- display information on the CDROM.
    cdreset   -- reset the CDROM device (2.1 experimental).
    cdshuffle -- play the tracks of the CDROM in random order.
    cdloop    -- endless-loop the CD
    cdctrl    -- interactive control of CDROM
    cdown     -- query CDDB database for CD info 
    cdadd     -- add to local CD database 

    cdctrl is designed to be used to establish a connection with a CDROM
and interactivly control it via standard input.  This binary returns status
in human- and machine-readable format, hence may be used to remotely control
a CDROM, e.g., as a daemon.  Note, cdctrl may also be automated via expect,
sh, TCL, perl or other scripting language.

    The cdir command supports a database of artist, title, and track names
in a simple format compatible with Workman, a nice OPEN LOOK based program
for controlling audio discs in a CDROM drive.  It first looks in the user's
~/.cdtooldb file.  Then, if the CDTOOLDBPATH environment variable is set to
a colon-delimited list of files, cdir will check them in order until it
finds the cd.  

    There is a shell script, "cdadd", which automates adding entries to the
file a bit, but Workman is better for this.  The program cdown may be used
to read a CDROM's track info and query the CDDB database on the Internet
from freedb.org.

    CDTOOL doesn't do anything fancy.  There is no scan, fast forward,
repeat, etc.  Maybe these functions are better performed by a full-screen
or graphical program, or simply noone has botherd to implemented them yet.
CDTOOL is designed to be a simple, elegant command line utility.  For more
specifics on how to use the program refer to the man page.  Note, CDTOOL
does include previous and next track access.

Download
========

    The newest released version of CDTOOL is always available from the
below URLs. CDTOOL is also included in the Mandrake, Gentoo and Debian
GNU/Linux distributions.

    http://hinterhof.net/cdtool/dist/
    ftp://ftp.ibiblio.org/pub/linux/apps/sound/cdrom/cli/

Installation
============

    See the INSTALL file.

CDROM device permissions
========================
   
    If you get an access problem with the CDROM device, you need to
give yourself permission to read and write to /dev/cdrom* or whatever
name your CDROM has. The preferred way of doing this is to make the
user(s) member of the cdrom group:

    # adduser <user> cdrom

    Don't forget to logout and login again to update group membership
of your session. If you are not using a cdrom group to control access
to the CDROM, you can simply make the device available to anyone:

    Eg:

    # chmod 666 /dev/hdb    -- IDE CDROM on /dev/hdb
 OR # chmod 666 /dev/scd0   -- SCSI CDROM on /dev/scd0

Mailinglist
===========

    There is a mailinglist for users and developers of cdtool named
cdtool-devel. If you have ideas about how cdtool could improve or what
features are missing, have code to contribute or problems using it, or
whatever really, feel free to send it along to this list.
    
    Post: cdtool-devel@lists.hinterhof.net
    Subscribe: http://lists.hinterhof.net/mailman/listinfo/cdtool-devel
    Archive: http://lists.hinterhof.net/pipermail/cdtool-devel/

Known Bugs
==========

    If cdtool doesn't detect your CDROM drive and the device node of
your CDROM drive has an unusual or unsupported location, you can change
it in config.h; If you think cdtool should detect this location, don't
forget to send us the change.

    When play begins on a track, the wrong track may be reported; this 
happens when the offset returned after the seek is a fraction of a second 
less than the start time for the track, with the result that the track is 
one less than it should be.  Any subsequent requests for i/cdinfo report 
the correct track.

    CDTOOL is known to have problems working with 2.2.16 and 2.2.17 Linux
kernels. cdplay exits with the error message "ioctl cdromplaytrkind" and
refuses to play CDs. The cause of this was a kernel bug that has been
fixed in >= 2.2.18 Linux kernels.

Development
===========

    CDTOOL development takes place in a public Subversion repository. The
latest development version is available in the directory /public/cdtool/trunk/
You can check it out using:
 
    $ export SVN=http://svn.hinterhof.net/public/cdtool
    $ svn ls $SVN
    $ svn co $SVN/trunk cdtool-current

    The latest Debian version of CDTOOL, which will at some point be going
into unstable, is developed in the directory /public/cdtool/trunk-debian
Check it out using:

    $ svn co $SVN/trunk-debian cdtool-debian

    CDTOOL development is discussed on the cdtool-devel mailinglist.
Feel free to send patches, comments, feature requests, bugs and other
things related to CDTOOL to this list.

CDCTRL (WARNING):
=================

    If you want to use cdctrl from inetd to have remote control of your
CDROM, you can edit /etc/services and /etc/inetd.conf per the instructions
below. WARNING:  Please note, this code may not be secure and could open
up security holes on your system.

 1. Add a CDROM to /etc/services with the 9000 being a port
    that you want to use (any one above 1024):

       cdrom    9000/tcp    # first CDROM drive

 2. Add a CDROM controller to /etc/inetd.conf (with anyuser being
    the name of a user who should run the program, /usr/local/bin/cdctrl
    being the name of the program to run, and /dev/cdrom being the name
    of your CDROM):

       cdrom stream tcp nowait anyuser /usr/sbin/tcpd \
        /usr/local/bin/cdctrl /dev/cdrom

COPYRIGHT AND LICENSE
=====================

    CDTOOL 1.0 is Copyright 1994 Thomas Insel.  It may be distributed 
freely under the terms of the GPL.  For more information, read the files 
"COPYING" and "main.c".  

    CDTOOL 1.0 contains some code from XPlaycd (mainly in hardware.c) which
is by Olav Woelfelschneider. Per the CREDITS file with XPlaycd, this code 
was originally from WdorkBone and/or WorkMan.  Thanks for OpenSource!

    CDTOOL 2.0 is Copyright 1995,96 Sven Oliver Moll.  Since it was GPL,
it still is GPL.

    CDTOOL 2.1 is Copyright 1997,98 Wade Hampton, Dan Risacher, 
Lin Zhe Min, Byron Ellacott, and the original authors.  Since it 
was GPL, it is still GPL.

    CDTOOL 2.1.6 is Copyright 2004 Max Vozeler and others. See PEOPLE
and CHANGES for detailed attributions.

EMAIL:
    Byron Ellacott              <rodent@homer.humbug.org.au>
    Wade Hampton                <whampton@staffnet.com>
    Thomas Insel                <tinsel@tinsel.org>
    Lin Zhe Min                 <ljm@ljm.wownet.net>
    Sven Oliver Moll            <smol0075@rz.uni-hildesheim.de>
    Daniel R. Risacher          <magnus@mit.edu>
    Olav Woelfelschneider       <wosch@rbg.informatik.th-darmstadt.de>
    Max Vozeler                 <max@hinterhof.net>

    See PEOPLE and CHANGES for detailed attributions.

    Please let me know if you make any useful modifications, successfully
run CDTOOL under an operating system besides Linux, are interested in
different licensing terms, find CDTOOL useful, or whatever.  Please
address all correspondance regarding CDTOOL to tinsel@tinsel.org, 
whampton@staffnet.com, or to Thomas Insel, 210 Parkview Drive, 
Bloomington, IL 61701-2038. 

