CDTOOL 2.1.8, 2006-08-09, 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 and 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.

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

    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.

SCSI/non-SCSI
=============

    If CDTOOL doesn't work with your CDROM or controller, there is a slim
chance that building the "non-SCSI" version will fix it. (Note: That name
is a bit misleading. The default "SCSI" version should actually work with
all kinds of non-SCSI drives, too)

    $ ./configure --disable-scsi

    Should this code work better for you than the default, please send a
quick message with details about your operating system and hardware to the
cdtool-devel mailinglist. 

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

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:
 
    $ svn co http://svn.hinterhof.net/public/cdtool 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 http://svn.hinterhof.net/public/cdtool/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

Copyrights and License
======================

    This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation; version 2 dated June, 1991.

    This package is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

    The following copyright statements are incremental, that is all
copyright statements added together give the copyrights that apply to
the most recent version:

    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, Copyright 2003 Josh Buhl,
Copyright 1999 Roland Rosenfeld, Copyright 1999 Mike Coleman and Copyright
2001 Richard Kettlewell.

    CDTOOL 2.1.7 is Copyright 2004 Max Vozeler and Copyright 2000
Peter Samuelson.

EMAIL:
    Byron Ellacott              <rodent@homer.humbug.org.au>
    Daniel R. Risacher          <magnus@mit.edu>
    Josh Buhl                   <jbuhl@gmx.net>
    Lin Zhe Min                 <ljm@ljm.wownet.net>
    Max Vozeler                 <max@hinterhof.net>
    Mike Coleman                <mkc@kc.net>
    Olav Woelfelschneider       <wosch@rbg.informatik.th-darmstadt.de>
    Peter Samuelson             <peter@p12n.org>
    Richard Kettlewell          <rjk@greenend.org.uk>
    Roland Rosenfeld            <roland@debian.org>
    Sven Oliver Moll            <smol0075@rz.uni-hildesheim.de>
    Thomas Insel                <tinsel@tinsel.org>
    Wade Hampton                <whampton@staffnet.com>

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

