#
# @(#)README	6.106 96/04/05
#
# xmcd   - Motif(tm) CD Audio Player
# cda    - Command-line CD Audio Player
#
# by Ti Kan
#


INTRODUCTION
------------

These are the release notes for xmcd, an X11/Motif-based CD player
utility; and for cda, a command-line driven, non-graphical CD audio
player.  Please read through this file before building, installing, or
using xmcd/cda.  You should also read the INSTALL file if you will be
compiling these applications from the source code distribution.  After
installation, you can use the man(1) or xman(1) command to read the
on-line manual entry.  The CHANGES file contains a revision log.
If you encounter a problem, please read the FAQ file first, as it may
already document a solution.

This distribution is released as free software under the GNU General
Public License, except the sources under the libdi_d subdirectory,
which are under the GNU Library General Public License.  Please see
the misc_d/COPYING and misc_d/COPYING.LIB files for details.


SOFTWARE FEATURES
-----------------

This release of xmcd features the following:

    - Standard functions: Stop, Play, Pause, Next/Previous Track,
      Next/Previous Index, Fast forward/rewind with audio sample,
      Eject and On/off.
    - Direct track access keypad and track-warp slider controls.
    - Volume control with selectable taper characteristics.
    - Balance control.
    - Channel routing control: Select between normal stereo,
      reversed stereo, mono-L, mono-R, or mono-L+R.
    - Track/Index/Time display: Selectable to display elapsed time,
      remaining track time, or remaining disc time.
    - Status display: for current play status, A->B mode, program
      mode, CD database.
    - Shuffle (random) play function.
    - Repeat function with iteration counter.
    - Sample function: Play a few seconds of each track.
    - A->B function: Repeat from selectable point A and B.
    - Eject inhibit function: To prevent someone from ejecting the
      disc by pressing the button on the drive.
    - Automation options on CD load, eject, play completion and
      program exit.
    - Track Program function: Play tracks in custom order.
    - CD database function: Allows you to store CD title/track titles
      in database, and associate each disc with a play program.
      Displays the current playing disc title/track information.
      In addition, you can enter and display arbitrary text associated
      with the disc or each track, such as band information, lyrics,
      etc.
    - Remote CD database: Query CD entries on a remote network server.
      The server can be on the Internet or other TCP/IP networks.
    - CD database entry send: Contribute CD database entries to
      a central archive via Internet electronic mail.
    - Main window button face labels can be configured to display
      pictorial symbols, or text with hotkey mnemonics.
    - The complete application can be operated via the keyboard with
      full support for keyboard traversal and hotkeys.
    - All labels and messages can be customized to non-English
      languages via X resources.
    - All colors and many other functionality are user-customizable
      using X resource settings.
    - On-line feature-specific help information.
    - Attractive, intuitive-to-use Motif user interface.
    - Device-specific configuration files to make xmcd adaptable
      to most CD-ROM drives.

Xmcd uses the Motif toolkit to achieve a pleasing appearance, such that
it actually looks and feels like a real CD player for all basic
functions, yet takes advantage of the GUI and window system to make
programming and CD database functions easy.

Currently, the cda utility offers almost the same functionality as
xmcd except the FF, REW, Sample and A->B features are not available.
Also, the CD database is read-only via cda (no updates).  In addition,
a visual mode is available that turns cda into a screen-oriented
(curses-based) CD player.


SUPPORTED PLATFORMS
-------------------

The source code of this version of xmcd and cda supports the following
operating systems environments:

    1.  Apple A/UX
	- A/UX version 3.0 or later (on Apple Macintosh m68k,
	  with devscsi module installed)

    2.  Berkeley Software Design, Inc. (BSDI) BSD/OS
	- BSD/OS version 2.0 or later (on Intel x86 PC-compatible)

    3.  Data General DG/UX
	- DG/UX version 5.4R3.00 or later (on DG AViiON m88k)

    4.  Digital Equipment Corporation Digital UNIX (OSF/1)
	- OSF/1 version 1.3 or later (on Digital Alpha AXP)

    5.  Digital Equipment Corporation Ultrix
	- Ultrix version 4.3 or later (on DECStations, with
	  SCSI CAM installed)

    6.  Digital Equipment Corporation OpenVMS
	(See notes in the INSTALL.VMS file)
	- OpenVMS version 6.1 or later (on Digital Alpha AXP)
	- OpenVMS version 5.2-2 or later (on Digital VAXstations)

    7.  FreeBSD
	- FreeBSD 2.0.5 or later (on Intel x86 PC-compatible)

    8.  Hewlett Packard HP-UX
	- HP-UX release 9.x (HP 9000 m68k Series 300, Series 400)
	- HP-UX release 9.x (HP 9000 PA-RISC Series 700)
	- HP-UX release 10.x (HP 9000 PA-RISC Series 700, Series 800)

    9.  IBM AIX
	- AIX version 3.2.x (on IBM RS/6000 Power and compatibles)
	- AIX version 4.x (on IBM RS/6000 Power/PowerPC and compatibles)

    10. Linux
	- Linux 1.0 or later (on Intel x86 PC-compatible and other
	  platforms)

    11. NetBSD
	- NetBSD 1.0A or later (on Intel x86 PC-compatible, Sun Sparc
	  and other platforms)

    12. SCO UNIX System V Release 3.2 (on Intel x86 PC-compatible)
	- SCO UNIX 3.2v4.x
	- Open Desktop version 2.x
	- Open Desktop version 3.x
	- Open Server release 5.x

    13. Siemens Nixdorf Informationssysteme SINIX System V Release 4
	- SINIX-N (on SNI RM200, RM400)
	- SINIX-P (on SNI RM600)

    14. Silicon Graphics Irix System V Release 4
	- Irix version 4.x (on SGI platforms)
	- Irix version 5.x (on SGI platforms)
	- Irix and Irix64 version 6.x (on SGI platforms)

    15. Sony NEWS-OS
	- NEWS-OS 4.1 or later (on Sony NEWS/m68k)

    16. Stratus FTX System V Release 4
	- FTX version 3.x (on Stratus Continuum PA-RISC platforms)

    17. SunOS
	- SunOS 4.1.x / Solaris 1.x (on Sun Sparc and compatibles)

    18. SunOS System V Release 4
	- SunOS 5.x / Solaris 2.x (on Sun Sparc and compatibles)
	- SunOS 5.x / Solaris 2.x (on Intel x86 PC-compatible)

    19. UNIX System V Release 4.0 (on Intel x86 PC-compatible)
	(Note: 4.0.3 or later recommended)
	- AT&T
	- Consensys
	- Dell
	- ESIX
	- ISC
	- Microport
	- Micro Station Technology
	- UHC
	- USL

    20. UNIX System V Release 4.0 (on Motorola m88k)
	- Motorola

    21. UNIX System V Release 4.2 (on Intel x86 PC-compatible)
	- Consensys
	- Information Foundation
	- Novell/Univel UnixWare 1.x
	- Onsite
	- USL

    22. UNIX System V Release 4.2MP (on Intel x86 PC-compatible)
	- Novell UnixWare 2.x

Pleasee see the "GENERAL SOFTWARE NOTES" and "PLATFORM-SPECIFIC NOTES"
sections below for important information about setting up and using
xmcd and cda.


SUPPORTED CD-ROM DRIVES
-----------------------

This release of xmcd and cda should work with the following CD-ROM
drives:

    Apple
	CD SC+, CD-150, CD-300, CD-300i, CD-300e
    Aztech
	CDA268-01A (#)
    Chinon
	CDS-431, CDX-431, CDS-435, CDX-435, CDS-525, CDX-525, CDS-535,
	CDX-535, CDS-545, CDX-545
    Compaq
	CDU-561, CR-503BCQ
    Creative Labs
	CD-ROM (#)
    Digital Equipment Corporation
	RRD42, RRD43, RRD44, RRD45
    Hewlett Packard
	XM-3301, XM-3401, XM-3501
    Hitachi
	CDR-1650S, CDR-1750S, CDR-1950S, CDR-3650, CDR-3750, CDR-6750
    IBM
	7210-001, 7210-005, 7201-010, Ext-ISA (#)
    Longshine
	LCS-7260 (#)
    Media Vision
	CDR-H93RMV, Reno
    Micro Design International
	600CD4X, SE6CDI
    Mitsumi
	FX-001S (#). FX-001D (#), FX-001DE (#), FX-400B (#), LU-005S (#)
    NEC
	CDR-25, CDR-37, CDR-38 (*), CDR-55, CDR-72, CDR-74, CDR-77,
	CDR-80, CDR-82, CDR-84, CDR-74-1 (*), CDR-84-1 (*), CDR-210P,
	CDR-222S, CDR-260 (#), CDR-260R (#), CDR-400, CDR-401, CDR-500,
	CDR-501, CDR-502, CDR-510, CDR-511, CDR-512, CDR-600, CDR-601,
	CDR-602, CDR-900
    Optics Storage
	8000AT (#)
    Kotobuki/Matsushita/Panasonic
	CR-501B, CR-502B, CR-503B, CR-504B, CR-521 (#), CR-522 (#),
	CR-523 (#), CR-562 (#), CR-563 (#), CR-574 (#), CR-581 (#)
    Okano/Wearnes
	CDD110 (#)
    Orchid
	CD-3110 (#)
    Philips/LMS
	CM206 (#)
    Pioneer
	DRM-600, DRM-600A, DRM-610, DRM-602X, DRM-604X (*), DRM-624X,
	DRM-1804X, DR-U104X, DR-U124X, DR-UA124X (#)
    Plextor/Texel
	DM-3024, DM-5024, DM-3028, DM-5028, PX-43C, PX-45C,
	PX-63C, PX-65C
    Procom
	CDT4-3X, CDT4-DS, CDT4-MX, CDT7-3X, CDT7-DS, DSP-DR0020,
	ICD-MX, MCD-DS, MCDN-3X, SICD-DS, SICDN-3X, SXCD-DS, SXCDN-3X
    Sanyo
	CRD-254P (#), CDR-H93RMV
    Silicon Graphics
	XM-3301, XM-3401, XM-3501
    Sony
	CDU-31A (#), CDU-33A (#), CDU-55E (#), CDU-55S, CDU-76E (#),
	CDU-76S, CDU-531 (#), CDU-535 (#), CDU-541, CDU-561, CDU-6111,
	CDU-6211, CDU-7205N (#), CDU-7211, CDU-7811, CDU-8002, CDU-8003,
	CDU-8003A, CDU-8012
    Stratus
	D850
    Sun
	CD-ROM (Sony OEM), CD-ROM (Toshiba OEM)
    Teac
	CD-55A (#)
    Toshiba
	XM-3101, XM-3201, XM-3301, XM-3401, XM-3501, XM-3601, XM-3701,
	XM-4101, XM-5201, XM-5301, XM-5302 (#), XM-5402 (#), XM-5901,
	XM-8100

    Other SCSI-2 compliant CD-ROM drives
    Other non-SCSI CD-ROM drives (#) (driver support required)

Units denoted with a hash symbol (#) are currently supported only on
certain OS platforms that contain the proper device driver for the
CD-ROM drive.  These drives are either typically used with an ATAPI
or proprietary interface card or a sound card.  See the "NON-SCSI
CD-ROM DRIVES" section below for details.

Units denoted with an asterisk (*) can be configured to operate in the
SCSI-1 or SCSI-2 mode (via jumpers or DIP switch).  You must configure
the xmcd software accordingly (with the LIBDIR/xmcd/config/config.sh
program).  Depending upon the specific model, you may find that xmcd/cda
supports more features while operating in SCSI-2 mode.  See the CD-ROM
drive owner's manual for details about setting the mode.

The author cannot personally test all these drives, therefore much
of this information relies on user feedback.

See the "CD-ROM NOTES" section below for information specific to
some of the CD-ROM drives.


GENERAL SOFTWARE NOTES
----------------------

This distribution now comes with several 32x32 pixmap files
suitable for use as an xmcd desktop icon.  These are installed
in LIBDIR/xmcd/pixmaps:

    xmcd.icon - for Novell UnixWare
    xmcd_a.px - for SCO Open Desktop (XPM2 format)
    xmcd_b.px - for SCO Open Desktop (XPM2 C format)
    xmcd.xpm  - for other systems that use XPM format

You can use the appropriate icon setup utilities under each of
these environments to create an xmcd icon (with which you can use to
launch xmcd).

Xmcd and cda must be installed as a setuid-root program on virtually
all platforms.  This is because these utilities use the SCSI
pass-through mechanism to control the CD-ROM drive, which requires root
privilege on most systems.  Security issues have been addressed,
however, since neither application will send read/write commands to a
device.  They will also refuse to send any more command to a device if
the initial inquiry shows that the device is not a CD-ROM.  Also, xmcd
changes the uid and gid to that of the real user before reading/writing
CD database files or executing external programs.

On systems that do not require super-user privilege for SCSI
pass-through, it is actually more secure to turn off the user and group
permissions of the SCSI device nodes, and make xmcd and cda setuid-root.
This prevents malicious users from writing programs that send arbitrary
commands to the devices.

Exceptions to the setuid-root requirement:  If you configure xmcd
and cda to operate the drive via the "SunOS/Linux ioctl method"
or the "FreeBSD ioctl method" (see the NON-SCSI CD-ROM DRIVES
section below), setuid-root privilege is not required.  Also, the
setuid requirement does not apply on the Digital OpenVMS platform.

If you have a $HOME/.xmcdcfg directory and your home directory
is over an NFS mount, be sure to set the execute permission on
your home directory and the $HOME/.xmcdcfg directory.  This is
necessary because xmcd and cda runs as root on most systems, and
root privilege becomes the equivalent of "other" over NFS.
Likewise, all personal configuration files in your $HOME/.xmcdcfg
directory should be publically readable.

Your xmcd/cda binary should only be run on the same OS platform group
that it was compiled on.  For example, UNIX SVR4.0 binaries must
not be run on a UNIX SVR4.2 system.  Likewise, a binary compiled
on a SunOS 4.x platform cannot be used on a SunOS 5.x system.

The XMcd.ad file contains several long lines broken into separate lines
using the "\" continuation marker (in particular, the
"XMcd*someWidgetName.fontList" lines).  This has been known to cause
error messages on some Motif implementations.  To remedy this, remove
the "\" continuation markers and join the multiple lines back into a
single line.

Do not use xmcd/cda if the CD-ROM drive contains a mounted filesystem
data disc (ISO-9660, High Sierra or other formats).  Always use the
"df" or "mount" command to check if such a filesystem is mounted
before invoking the application.

Certain OS platforms will print console error messages or record error
messages in a log file if the CD device is accessed without a CD loaded
in the drive.  If you encounter this situation, the workaround is to
load a CD in the drive before starting xmcd or cda, and refrain from
leaving xmcd in the "no disc" state for an extended period of time.

Unless otherwise instructed by your OS or system hardware vendor,
it is generally a bad idea to turn off the power of the CD-ROM drive
while the operating system is running.  Cycling the power may
cause the CD-ROM drive to assert a SCSI bus reset, which is not always
gracefully handled by your system's SCSI device driver (i.e., possible
system hang or crash).  Thus, it is best to turn on the CD-ROM drive
before booting the OS, and do not turn it off until after OS shutdown.

Although xmcd and cda should run reliably on the supported platforms
and CD hardware as noted, if you encounter a problem, please send a
report to "ti@amb.org" with detailed descriptions of the configuration
and problem symptoms.  It would also be helpful to reproduce the
problem while running either application with the -debug option, and
capture the diagnostic output.  Send the output to the author for
examination.  Please also include detailed information about your
software and hardware configuration.

Better yet, send bug fixes!

The modular design of xmcd and cda is such that support for other UNIX
environments and CD-ROM drives can be readily added.  See the "PORTING"
file for details if you are interested in contributing to the development
effort.  Before you start a porting effort or add significant code,
contact the author to ensure that this effort isn't being duplicated
by others.


PLATFORM-SPECIFIC NOTES
-----------------------

BSDI BSD/OS:

    On the BSDI BSD/OS platform, the xmcd and cda volume, balance and
    channel routing controls will not work unless you apply a minor
    patch to the disk device driver.

    In the /sys/dev/scsi/sd.c file, find the sdopen() function, and
    look for code similar to the following:

	if ((sc->sc_type & TYPE_TYPE_MASK) == TYPE_ROM && flags & FWRITE)
		return (EROFS);

    Comment-out or remove these two lines of code.

    This code was intended to prevent an application from opening a
    CD-ROM drive for writing (since the CD-ROM media is read-only).
    This restriction is not necessary, as a write operation to the
    CD-ROM would fail anyway.  However, due to the design of the SCSI
    pass-through mechanism in BSD/OS, xmcd/cda needs to "write" out
    SCSI mode data in order to implement the volume, balance and
    channel routing controls.  This patch allows xmcd/cda to open the
    CD-ROM device with the write attribute enabled.

    After applying this patch, you must then build a new kernel and
    reboot.  You should also set the CD-ROM device node to enable
    both read and write permissions.

    If you decide not to patch the disk driver, then you should
    set the following parameters to "False" in the
    LIBDIR/xmcd/config/DEVICE configuration file:

	volumeControlSupport:	False
	balanceControlSupport:	False
	channelRouteSupport:	False

    The Hitachi SCSI-1 CD-ROM drives will not work on the BSD/OS
    platform without some changes to the SCSI driver.  The specific
    changes necessary are beyond the scope of these notes.  If you
    must use the Hitachi SCSI-1 drives please e-mail ti@amb.org for
    information.

Digital UNIX (OSF/1) and Ultrix:

    The minimum Ultrix and OSF/1 OS version listed above should be
    heeded.  Running xmcd and cda on earlier releases of either OS may
    cause the system to crash, due to bugs in the OS.  You must create
    the /dev/cam device before using xmcd/cda under Ultrix.  To do so,
    type the following commands while logged in as root:

	cd /dev
	MAKEDEV cam

Data General DG/UX:

    For DG/UX, you must configure the CD-ROM to be a user SCSI device
    instead of a SCSI disk.  To do so, follow these steps:

    1) Find the line in the file /var/Build/system.<hostname> which
       represents your CD-ROM drive and change the prefix "sd" to
       "scsi".
    2) Rebuild and reboot your kernel.

FreeBSD:

    You should set the CD-ROM device node to enable both read and
    write permissions.

    Release and snap versions of FreeBSD 2.0.5R needs a patch in the
    SCSI driver in order to work with xmcd (otherwise, the kernel may
    panic).  In /sys/scsi/scsi_ioctl.c, around line 323:

    Original code:
			/* if no data, no need to translate it.. */
			bp->b_un.b_addr = 0;
			bp->b_dev = dev;
			bp->b_flags = 0;

			scsistrategy(bp);
			ret =  bp->b_error;

    Fixed code:
			/* if no data, no need to translate it.. */
			bp->b_un.b_addr = 0;
			bp->b_dev = dev;
			bp->b_flags = B_BUSY;

			scsistrategy(bp);
			ret =  bp->b_error;

HP-UX:

    On the m68k systems, you should set the CD-ROM device node to enable
    both read and write permissions.

Linux:

    If you are running an early version of Linux (1.0.x or before)
    with a SCSI CD-ROM, and you experience problems after ejecting a
    CD via xmcd, setting the "closeOnEject" device-specific parameter
    to "True" may alleviate the problem.  See the LIBDIR/xmcd/config/DEVICE
    file (where DEVICE is the basename of the CD-ROM special file).

    The Hitachi SCSI-1 CD-ROM drives will not work on the Linux
    platform without some changes to the SCSI driver.  The specific
    changes necessary are beyond the scope of these notes.  If you
    must use the Hitachi SCSI-1 drives please e-mail ti@amb.org for
    information.

Sun SunOS 4.1.x:

    The current SunOS 4.1.x run-time support is limited to systems
    running the sun4c and sun4m kernels.  To find out which kernel you
    have, use the "arch -k" command.

    The Hitachi SCSI-1 CD-ROM drives will not work on the SunOS 4.1.x
    platform as an audio CD player.  These drives were provided as
    standard equipment with some Sparc-compatible workstations.
    There is no way to make them work with xmcd and cda under SunOS
    4.1.x.  The only solution is to upgrade to a SCSI-2, Sun-compatible
    CD-ROM drive.

Sun Solaris 2.x:

    On Solaris 2.x platforms, you should use the virtual CD-ROM device
    (such as /vol/dev/aliases/cdrom0) if the Solaris Volume Manager
    (/usr/sbin/vold) is also running. You should set xmcd's
    "solaris2VolumeManager" common parameter and either the
    "closeOnEject" or "exitOnEject" device-specific parameter to True
    when operating under the Volume Manager.  If you want the Volume
    Manager to automatically start xmcd when a CD is inserted, you can
    specify the action_workman.so start-up program in the
    /etc/rmmount.conf file:

    action cdrom action_workman.so /usr/local/bin/X11/xmcd

    Substitute /usr/local/bin/X11 with the actual path to your xmcd
    binary.  See rmmount(1M) and rmmount.conf(4) for more information.

    If the Solaris Volume Manager is running, you should only use the
    Eject button on the xmcd main window to eject the CD.  Do not use
    the eject button on the CD-ROM drive itself.


CD-ROM NOTES
------------

The Chinon CDx-431 and CDx-435 drives do not support commands to
implement audio pause and resume operations.  Thus, these features
are non-functional when these drives are used with xmcd/cda.  The
CDx-525, CDx-535 and CDx-545 units do not have this limitation.

To avoid possible SCSI bus lock-up, never eject the disc using the
eject button on the front panel of the Hitachi SCSI-1 CD-ROM drives
while the unit is playing audio.  Use the software eject function of
xmcd/cda instead.  Also, you may wish to adjust the searchSkipBlocks
and searchPauseInterval configuration parameters to achieve the best
audio sampling effect during xmcd's REW and FF search operations.

This release of xmcd/cda supports operating only the first disc on the
Pioneer multi-disc CD-ROM changers.  Pioneer DRM-604X units with
revisions of the firmware prior to 2403 must be configured to operate
in the SCSI-1 mode (DRM-600 emulation, via back panel DIP switches),
and xmcd/cda must be configured as if it's operating a DRM-600.  Newer
DRM-604X units (firmware version 2403 and later) can be set up to
run in SCSI-2 mode, and xmcd/cda must be set up accordingly.

The Plextor/Texel DM-x024 drive firmware should be version 1.10 or
later to avoid system lockups.  The DM-x028 drives do not have these
restrictions.

Some of the Sun CD-ROM drives (Sony OEM CDU-8012) have a firmware
problem that can lead to a temporary SCSI bus hang after ejecting
a CD with xmcd.  The workaround is to increase xmcd's
insertPollInterval configuration parameter to 4000 milliseconds or
more.  See the LIBDIR/xmcd/config/common.cfg file.

Note that even if a CD-ROM drive is marketed as SCSI-2 compliant, it
still may not implement the full set of audio-related commands that
xmcd/cda requires.

The supported SCSI drives listed above will work only when connected
via a proper SCSI host adapter board.  Some x86 PC platforms use SCSI
CD-ROM drives but they are connected to sound cards that use a
proprietary interface.  These may work if xmcd/cda is configured
to operate the unit as a non-SCSI drive (see below).

If you have a SCSI CD-ROM drive not listed above, I would appreciate
a note from you regarding whether it works with xmcd/cda or not.  If
it works, please send me your xmcd device-specific configuration file
for this drive (usually /usr/lib/X11/xmcd/config/NAME, where NAME is
the name of the device node name of the CD-ROM drive).  I will then
add your drive to the supported list.

Some CD-ROM drives do not function well when the SCSI host adapter
board is configured to "synchronous negotiation" mode.  Examples
of these include certain NEC and Hitachi units.  If you experience
malfunctions with xmcd/cda, check the host adapter board configuration
and try disabling the synchronous mode.  On the Adaptec AHA-1542B,
there is a single jumper that controls whether synchronous negotiation
is enabled for all devices on the SCSI bus.  On the AHA-1542C/CF,
synchronous negotiation is configurable via the SCSISelect setup
program, and is settable on a per-ID basis.  Please consult your SCSI
host adapter board owner's manual for information.


NON-SCSI CD-ROM DRIVES
----------------------

This release of xmcd and cda supports non-SCSI CD-ROM drives on
certain OS platform only.  These platforms currently consists of
the following:

    Linux
    FreeBSD
    SCO Open Server release 5.x

On the Linux and FreeBSD platforms, xmcd/cda must be configured to
operate in the appropriate "ioctl method" when used with these drives
(rather than the "SCSI pass-through method").  See the
"deviceInterfaceMethod" parameter in the LIBDIR/xmcd/config/DEVICE
file (where DEVICE is the basename of the CD-ROM special file).

On SCO OSR5, only ATAPI-compliant CD-ROM drives can be used.
you must use the ATAPI BTLD from SCO for these drives.  You should
configure xmcd/cda for a "generic SCSI-2 CD-ROM drive", this is
because the ATAPI BTLD driver emulates the SCSI pass-through
interface.  Some xmcd/cda features for SCSI-2 drives may be
non-functional, however.

The specific list of non-SCSI drives supported depends upon the
configuration of the OS host CD-ROM driver.  You should make sure
that a driver for your non-SCSI CD-ROM drive is present in your
kernel (or can be added to your kernel).  Without the appropriate
driver, xmcd/cda will not work.

On Linux, refer to the /usr/src/linux/drivers/block/README.xxx
files for details about the drivers in your version of the kernel.

Not all CD-ROM drivers are present in all versions of your OS.
Older versions may lack some of these.  Also, the specific CD-ROM
drives  and features supported by these drivers are also version-
dependent.

Future releases of your OS will likely add new drivers for other
non-SCSI CD-ROM drives.  As long as new drivers conform to the
existing ioctl interface, xmcd/cda should work without modifications.

See your OS documentation about configuring a kernel to use these
drivers.

All features which are defined for the ioctl interfaces are enabled
in xmcd/cda regardless whether the drivers can handle it or not,
because enhancements are ongoing.

Although the SunOS/Linux ioctl method will also work with many
SCSI CD-ROM drives on the Linux, SunOS 4.1.x (Solaris 1.x) and
SunOS 5.x (Solaris 2.x) platforms, it offers less features than
the SCSI pass-through method and is thus not recommended for SCSI
drives.  Likewise, the FreeBSD ioctl method should only be
used with non-SCSI drives.


CD DATABASE SERVERS
-------------------

This version of xmcd/cda supports remote CD database servers.  With
this feature, you do not have to have a local copy of the entire xmcd
public CD database on your local system, thus saving disk space and
filesystem inode consumption.

You can use this feature only if your system is connected to a TCP/IP
network and a CD database server is accessible by you.  Some networks
use security firewalls that disables such access.  To test this, you
can try the following command (substitute xmcdserver.xyz.com with the
actual host name to use):

    telnet xmcdserver.xyz.com 888

If you see a sign-on banner similar to the following then all is fine:

    201 xmcdserver CDDBP server v1.0PL0 ready at Mon Jan 08 09:07:56 1996

Type "quit" to disconnect from the server.

The recommended configuration is to make xmcd/cda search your local
CD database for a match first (when a CD is inserted), and if a match
is not found, then query the remote server.  The order of the
search is determined by the "cddbPath" parameter which is set
in the LIBDIR/xmcd/config/common.cfg file.  When you install xmcd
(using "make install" or "install.sh"), you will be asked whether
remote CD database servers are to be used, and enter a list of server
hosts.  That will set up the default cddbPath parameter for you.
Each user can override the default cddbPath settings in their own
$HOME/.xmcdcfg/common.cfg file.

The LIBDIR/xmcd/config/common.cfg file contains comments about
the syntax of the cddbPath parameter, should you wish to change
the default configuration or set up your own private settings.

Currently these xmcd public CD database servers are in operation on
the Internet.  Please use hosts that are closest to you for best
response time.

    Host name				Location
    ---------------------		-----------------------
    cddb.celestial.com			Mercer Island, WA, USA
    cddb.sonic.net			Santa Rosa, CA, USA
    cddb.schoneal.com			Austin, TX, USA
    sunsite.unc.edu			Chapel Hill, NC, USA
    cddb.delphi.com			Lowell, MA, USA
    cddb.shu.ac.uk			United Kingdom
    cddb.ton.tut.fi			Finland
    cddb.sai.msu.su			Moscow, Russia
    cddb.ieo.nctu.edu.tw		Taiwan
    cddb.dentistry.adelaide.edu.au	Australia

The public CD database server sites may change over time.  A current
list can be obtained from the xmcd World Wide Web page (see below),
or write to ti@amb.org.

If you wish to operate your own xmcd CD database server on a private
network, send e-mail to ti@amb.org to inquire about the CD database
server software.


WHERE TO GET XMCD
-----------------

The source code release of xmcd/cda version 2.0 is available via
Internet anonymous FTP:

    (Instructions)
    ftp://ftp.x.org/contrib/applications/xmcd/xmcd-2.0.README

    (gzip'd tar archive)
    ftp://ftp.x.org/contrib/applications/xmcd/xmcd-2.0.tar.gz

A public CD database for xmcd is also available (you need to get
this only if you want a copy of the full xmcd CD database on
your local system.  See the "CD DATABASE SERVERS" section above):

    (Instructions)
    ftp://ftp.x.org/contrib/applications/xmcd/xmcd-cddb.README

    (gzip'd tar archive)
    ftp://ftp.x.org/contrib/applications/xmcd/xmcd-cddb.tar.gz

Some ftp sites are not secure, as it is commonly allowed for anyone
to anonymously post to them. The xmcd web page (see below) lists the
checksum of all xmcd-related packages, so you can check that your
copy is genuine.

Both packages require the "gunzip" (GNU unzip) utility to uncompress.
If your system does not have gunzip, you can build it from the
source code.  Gzip/gunzip can be found on various FTP sites
(such as prep.ai.mit.edu:/pub/gnu).

This CD database is periodically updated with more entries, and you are
encouraged to contribute to this database by using the "Send" feature
in xmcd.  Please read the xmcd-cddb.README file in the public CD
database archive before sending entries to the public database.

Pre-compiled binary releases of xmcd and cda for certain OS
environments are also available from the author.   Please send
e-mail to ti@amb.org for more information.


XMCD/CDA WORLD WIDE WEB HOME PAGE
---------------------------------

For those of you with access to the WWW (via Netscape, NCSA Mosaic
or other WWW browser), there is now a Home Page for xmcd and cda.
The location is:

    http://sunsite.unc.edu/~cddb/xmcd/

This home page provides up-to-date information about the
current release version, online README file, FTP service to get
the software, an interactive form to send comments and
suggestions, and late breaking announcement, if any.

Also available on the xmcd/cda WWW Home Page is the Online CD
Database Search feature.  This is based on the public xmcd CD
database and allows you to find entries in the database quickly.

You are invited to visit this space and make use of its services.


OTHER INFORMATION
-----------------

FreeBSD, Linux, SCO, UnixWare or other System V variant UNIX users
on an x86 PC-compatible platform:  If you have a sound card such as
the Adlib, Sound Blaster series, Pro Audio Spectrum, Gravis
Ultrasound, Roland MPU-401, Microsoft Sound System, etc., you
may want to look into the sound card driver package called
"VoxWare" by Hannu Savolainen (hannu@voxware.pp.fi).  This package
allows you to operate the sound card's mixer settings, amongst
many other capabilities.

I have written an X11/Motif audio mixer utility "xmmix" which
works with the VoxWare package.  Slider controls are provided
in xmmix to set the Synth, PCM, Line, CD and Microphone
input levels, the Rec Out, Rec Monitor, Speaker, and Master
output levels, and Bass/Treble settings, where applicable.
You can also use the Mute, Loudness and Stereo Enhance features
of the sound card if so equipped.

Xmcd and xmmix makes an ideal pair in your multimedia PC system.
You are invited to give xmmix a try.  Xmmix can be obtained via
anonymous FTP from the following location:

    ftp://ftp.x.org/contrib/applications/xmmix

VoxWare anonymous FTP location:

    ftp://sunsite.unc.edu/pub/Linux/kernel/sound

For further information please refer to the VoxWare documentation
or contact the author of the VoxWare software.

On other platforms, please refer to your OS/platform vendor
documentation about controlling your audio hardware, if applicable.


ACKNOWLEDGEMENTS
----------------

Several portions of xmcd and cda were contributed by these dedicated
individuals:

    Apple A/UX port:
	Eric Rosen

    BSDI BSD/OS port:
	Danny Braniss <danny@cs.huji.ac.il>

    Data General DG/UX port:
	Karl Owen <owen@dg-rtp.dg.com>

    Digital UNIX (OSF/1) and Ultrix port:
	Matt Thomas <thomas@lkg.dec.com>
    	Anthony Baxter <anthony@aaii.oz.au>

    Digital OpenVMS port:
	Rick Jones <rjones@zko.dec.com>

    FreeBSD and NetBSD port:
	Gennady B. Sorokopud <gena@netvision.net.il>

    HP-UX (m68k portion) port:
	Avi Cohen Stuart <avi@baan.nl>

    IBM AIX port:
	Kurt Brunton <kbrunton@ccs.harris.com>
        Tom Crawley <tomc@osi.curtin.edu.au>

    Motorola SVR4/88K port:
	Mark Scott <mscott@urbana.mot.com>

    SNI SINIX port:
	Eckhard Einert <einert.pad@sni.de>

    Sony NEWS-OS port:
	Joerg Anslik <josch@leibniz.cologne.de>

    The SunOS/Linux ioctl method code to support non-SCSI CD-ROM
    drives is based on code contributed by Peter Bauer
    <100136.3530@compuserve.com>.

    The FreeBSD ioctl method code to support non-SCSI CD-ROM
    drives is contributed by Gennady B. Sorokopud
    <gena@netvision.net.il>

    Several Solaris 2.x enhancements were contributed by
    Lee Duncan <Lee.Duncan@sun.com>.

    The visual mode support in cda is based on code contributed
    by Philip Le Riche <pleriche@uk03.bull.co.uk>.

Companies names and product names appearing in this file are each
trademarks of the respective company.  The names are for identification
purposes only.  This software and its author are not affiliated with any
of these companies.

I wish to express my appreciation for all the people who participated
in the extensive xmcd beta test program, who have contributed a great
deal to the user-friendliness, robustness and device support.
Many thanks also goes out to those that have contributed code,
suggestions, ideas, criticisms and notes of encouragement!

