#
# @(#)README	6.140 97/01/02
#
# 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 and CD-R 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.x (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. QNX
	- QNX version 4.22 or later (on Intel x86 PC-compatible)

    13. 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

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

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

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

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

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

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

    20. 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

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

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

    23. UNIX System V Release 4.2MP (on Intel x86 PC-compatible)
	- Novell/SCO 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 AND CD-R DRIVES
--------------------------------

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

    Acer
	610A (#)
    Apple
	CD SC+, CD-150, CD-300, CD-300i, CD-300e, CD-600e
    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,
	CDR-7830 (#), CDR-7930 (#)
    IBM
	7210-001, 7210-005, 7201-010, CRMC-FX400C (#), Ext-ISA (#)
    Longshine
	LCS-7260 (#)
    Media Vision
	CDR-H93RMV, Reno
    Micro Design International
	600CD4X, SE6CDI
    Mitsumi
	FT-810T (#), FX-001S (#). FX-001D (#), FX-001DE (#),
	FX-120T (#), FX-400B (#), FX-600B (#), LU-005S (#)
    Nakamichi
	MBR-7
    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-272 (#), CDR-273 (#),
	CDR-400, CDR-401, CDR-500, CDR-501, CDR-502, CDR-510, CDR-511,
	CDR-512, CDR-600, CDR-601, CDR-602, CDR-900, CDR-1410, CDR-1450,
	CDR-1460, CDR-3460
    Optics Storage
	8000AT (#)
    Kotobuki/Matsushita/Panasonic
	CR-501B, CR-502B, CR-503B, CR-504B, CR-506B, CR-521 (#),
	CR-522 (#), CR-523 (#), CR-562 (#), CR-563 (#), CR-574 (#),
	CR-581 (#), CR-583 (#), CR-8005, CW-7501
    Okano/Wearnes
	CDD110 (#)
    Orchid
	CD-3110 (#)
    Philips/LMS
	CM206 (#), PCA80SC
    Pioneer
	DRM-600, DRM-600A, DRM-610, DRM-602X, DRM-604X (*), DRM-624X,
	DRM-1804X, DR-411 (#), DR-433, DR-U104X, DR-U124X, DR-UA124X (#)
    Plextor/Texel
	DM-3024, DM-5024, DM-3028, DM-5028, PX-43C, PX-45C,
	PX-63C, PX-65C, PX-83C, PX-85C, PX-12C, PX-12T
    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 (#), CRD-254S, CDR-H93RMV
    Silicon Graphics
	XM-3301, XM-3401, XM-3501
    Sony
	CDR-111 (#), CDU-31A (#), CDU-33A (#), CDU-55E (#), CDU-55S,
	CDU-76E (#), CDU-76S, CDU-311 (#), 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, CSD-76S,
	CSD-880E (#)
    Stratus
	D850
    Sun
	CD-ROM (Sony OEM), CD-ROM (Toshiba OEM)
    Teac
	CD-55A (#), CD-56E (#), CD-56S
    Toshiba
	XM-3101, XM-3201, XM-3301, XM-3401, XM-3501, XM-3601, XM-3701,
	XM-4101, XM-5201, XM-5301, XM-5302 (#), XM-5401, XM-5402 (#),
	XM-5601, XM-5602 (#), XM-5701, XM-5702 (#), XM-5901, XM-8100
    Yamaha
	CDE-100, CDR-100, CDE-102, CDR-102

    Other SCSI-2 compliant CD-ROM and CD-R 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 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 or CD-R.
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.

Extra care has been taken to make xmcd/cda secure while running with
root privilege.  If you feel uncomfortable about the setuid aspect
of xmcd/cda then please do not use this application.

Exceptions to the setuid-root requirement:  If you configure xmcd
and cda to operate the drive via the "SunOS/Solaris/Linux ioctl
method" the "FreeBSD ioctl method" or the "AIX IDE 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.  Lastly, Setuid-root privilege is required on QNX.

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 Sun Solaris 2.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 "xmcd@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 2.x 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 xmcd@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:

    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 xmcd@amb.org for
    information.

QNX:

    Under QNX, xmcd must be configured to run under the "QNX ioctl method"
    to operate all CD-ROM drive types.  The "SCSI pass-through" method
    is not available.

    You must have the Fsys driver to create /dev/cd0, and the Iso9660fsys
    driver is required.  If the Audio driver is installed, /dev/dsp will
    automatically be used.  Note: A stable, post-beta Audio driver is
    present only on QNX 4.23 and later.

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:

    IBM AIX 4.x
    Linux
    FreeBSD
    QNX
    SCO Open Server release 5.x
    Sun Solaris/x86 2.x

On the AIX, Linux, FreeBSD, QNX and Solaris/x86 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 AIX, SCO OSR5 and Solaris/x86, only ATAPI-compliant CD-ROM drives
can be used.  For SCO OSR5, you must use the ATAPI BTLD from SCO for
these drives.

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.

Some CD-ROM drive/controller and OS driver combinations may not work
reliably.  Please refer to your OS documentation for the currently
supported list of drives and controllers.

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/Solaris/Linux ioctl method will also work with many
SCSI CD-ROM drives on the Linux, SunOS 4.1.x (Solaris 1.x) and
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.

On QNX, the QNX ioctl method should be used for all CD-ROM drives
(including SCSI drives) due to the lack of the SCSI pass-through
method.

The AIX IDE ioctl method is normally disabled.  You must explicitly
define -DAIX_IDE in the libdi_d directory when compiling xmcd/cda
to enable it.


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
    smurfy.tcimet.net			East Lansing, MI, USA
    cddb.schoneal.com			Austin, TX, USA
    cddb.dartmouth.edu			Hanover, NH, USA
    sunsite.unc.edu			Chapel Hill, NC, USA
    cddb.shu.ac.uk			United Kingdom
    cddb.ton.tut.fi			Finland
    cddb.westel.hu			Hungary
    cddb.sai.msu.su			Moscow, Russia
    cddb.ieo.nctu.edu.tw		Taiwan

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

If a problem occurs with one of the public CD database servers
(e.g., cannot connect to it), do not send complaints unless the
problem lasts for more than a couple of days.  It is not unusual
for network or system interruptions to occur, but they usually
clear up shortly.  If you suspect a real, persistent problem then
please notify xmcd@amb.org.

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


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

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

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

    (gzip'd tar archive)
    ftp://ftp.x.org/contrib/applications/xmcd/xmcd-2.1.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/cda 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 via the xmcd/cda web page
(see below).  If you don't have web access then send e-mail to
xmcd@amb.org for more information.


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

The xmcd/cda web page is at:

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

This 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 web 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
-----------------

I have written an X11/Motif audio mixer utility "xmmix" which
works with the "Open Sound System" package from 4Front Technologies.
Linux systems comes with a free version known as OSS/Free (formerly
"Unix Sound System/Lite" and "VoxWare").  The OSS package is also
available for a number of other platforms.  OSS provides the necessary
driver and tools to take advantage of the sound card/audio hardware
on your system.  Xmmix operates the audio mixer portion of your audio
hardware.

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 computer system.
You are invited to give xmmix a try.  Visit the xmmix web page:

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

Information about the Open Sound System package is at:

    http://www.4front-tech.com/
    http://personal.eunet.fi/pp/voxware

For further information please refer to the Open Sound System
documentation or contact 4Front Technologies.

On platforms that are not supported by OSS, 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 2.x 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>

    QNX port:
	D. J. Hawkey Jr. <hawkeyd@visi.com>
	(hints provided by W. A. Flowers)

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

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

    The SunOS/Solaris/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>

    The IBM AIX IDE ioctl method code to support IDE CD-ROM
    drives is contributed by Cloyce D. Spradling
    <cloyce@mail.utexas.edu>

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

    The xmcd remote CD database server code is by Steve Scherf
    <steve@moonsoft.com>.

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!

