#
# @(#)README	6.157 97/11/30
#
# 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.

The following notes refer to the XMCDLIB directory, which is the
directory under which all the xmcd/cda support files are installed.
This is configured when you install the xmcd package.


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

This release of xmcd features the following:

    - Standard functions
      * Play/Pause
      * Stop
      * Next/Previous Disc
      * Next/Previous Track
      * Next/Previous Index
      * Fast forward/rewind with audio scanning
      * Eject
      * On/Off
    - Multi-disc changer support
      * Disc change
      * Multi-disc playback
      * Reverse multi-disc playback
    - Direct access keypad
      * Disc and track change
      * track-warp slider controls
    - Volume control
      * Selectable volume taper characteristics
        > Linear
        > Square
        > Inverse square
    - Balance control
      * left/right slider control and centering button
    - Channel routing control
      * Normal stereo
      * Reversed stereo
      * Mono-L
      * Mono-R
      * Mono-L+R.
    - Main display
      * Disc number
      * Track number
      * Index number
      * Elapsed time, remaining track time, or remaining disc time
    - Status display
      * Current play status
      * A->B mode
      * Program mode
      * CD database indicator - local or remote
    - Shuffle play function
      * Play all tracks on the CD in random order
    - Repeat function with iteration counter
      * Repeat track
      * Repeat program
      * Repeat disc
      * Repeat all discs (multi-disc changer)
    - Sample function
      * Play a few seconds of each track
    - A->B function
      * Repeat from selectable point A and B
    - Eject inhibit option
      * Prevent someone from ejecting the disc by pressing the button
        on the drive
    - Automation options
      * On CD load
        > Auto caddy lock
        > Spin down
        > Auto-play
      * On play completion
        > Auto-eject
      * On CD eject
        > Auto-exit
      * On program exit
        > Auto-stop
        > Auto-eject
    - Track Program function
      * Play tracks in custom order
    - CD database function:
      * Store CD title/track titles in database
      * Display the current playing disc title/track information
      * Disc ID and music category classification
      * Enter and display arbitrary text associated with the disc
        or each track, such as band information, lyrics, etc.
      * Associate each disc with a play program
    - Remote CD database
      * Query CD information on a remote network server
      * The server can be on the Internet or other TCP/IP networks
      * Public Internet xmcd CD database servers around the world
      * Both the CDDBP or HTTP protocols are supported
      * Support for firewall proxy servers
    - CD database entry send
      * Contribute CD database entries to the master database via
        Internet electronic mail.
    - Dual-mode button labels
      * Main window button face labels can be configured to display
        pictorial symbols, or text with hotkey mnemonics.
    - Keyboard-friendly
      * The complete application can be operated via the keyboard with
        full support for keyboard traversal and hotkeys.
    - Internationalization
      * All labels and messages can be customized to non-English
        languages via X resources.
    - Color customization
      * All colors and many other functionality are user-customizable
        using X resource settings.
    - On-line help
      * feature-specific help information available via a single mouse
        click
    - Attractive, intuitive-to-use
      * Motif user interface with 3D appearance
    - Device-specific configuration files
      * 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)
	- BSD/OS version 3.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, Sun Sparc
	  and other platforms)

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

    12. OpenBSD
	- OpenBSD 2.x or later (on Intel x86 PC-compatible, Sun Sparc
	  and other platforms)

    13. QNX
	- QNX version 4.22 or later (on Intel x86 PC-compatible)

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

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

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

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

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

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

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

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

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

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

    24. 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
	CD-610A (#), CD-912E (#)
    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
    Compro
	CDR-7501
    Creative Labs
	CD-ROM (#)
    Digital Equipment Corporation
	RRD42, RRD43, RRD44, RRD45, RRD46
    Goldstar
	CRD-8160 (#), GCD-R580 (#)
    Hewlett Packard
	XM-3301, XM-3401, XM-3501, XM-3601, XM-4101, CD-Writer 4020,
	CD-Writer 6020
    Hitachi
	CDR-1650S, CDR-1750S, CDR-1950S, CDR-3650, CDR-3750, CDR-6750,
	CDR-7830 (#), CDR-7930 (#), CDR-8130 (#)
    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-140S2 (#), FX-400B (#), FX-600B (#),
	FX-800S (#), FX-1200 (#), FX-1600 (#), LU-005S (#)
    Nakamichi
	MBR-7, MBR-7.4, MJ-4.8s
    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-251 (#), CDR-260 (#), CDR-260R (#), CDR-272 (#),
	CDR-273 (#), CDR-400, CDR-401, CDR-462, 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-1610, 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-584 (#), CR-585 (#), CR-8005,
	CW-7501, LF-1004, LK-MC606BP, LK-MC686BP (#)
    Okano/Wearnes
	CDD110 (#)
    Orchid
	CD-3110 (#)
    Philips/LMS
	CDD2600, CM206 (#), PCA80SC
    Pioneer
	DRM-600, DRM-600A, DRM-610, DRM-602X, DRM-604X (*), DRM-624X,
	DRM-1804X, DR-411 (#), DR-433, DR-444 (#), DR-466S, DR-533,
	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, PX-20X
    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, CRD-820P (#), CDR-C3G (#), CDR-H93RMV
    Silicon Graphics
	XM-3301, XM-3401, XM-3501, XM-5401
    Sony
	CDR-111 (#), CDU-31A (#), CDU-33A (#), CDU-55E (#), CDU-55S,
	CDU-76E (#), CDU-76S, CDU-311 (#), CDU-415, CDU-511 (#),
	CDU-524E (#), 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
	D756, D758, D850, D855, D857, D859
    Sun
	CD-ROM (Sony OEM), CD-ROM (Toshiba OEM)
    Teac
	CD-50, CD-55A (#), CD-56E (#), CD-56S, CD-512E (#), CD-512S,
	CD-516E (#), CD-516S, CD-R50S
    Toshiba
	XM-3101, XM-3201, XM-3301, XM-3401, XM-3501, XM-3601, XM-3701,
	XM-3801, XM-4101, XM-5201, XM-5301, XM-5302 (#), XM-5401,
	XM-5402 (#), XM-5601, XM-5602 (#), XM-5701, XM-5702 (#),
	XM-5901, XM-6002 (#), XM-6102 (#), 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 XMCDLIB/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.

For multi-disc changers, please refer to the MULTI-DISC CHANGERS
section below.

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
XMCDLIB/pixmaps:

    xmcd.icon - for Novell/SCO UnixWare, 5 colors
    xmcd_a.px - for SCO Open Desktop (XPM2 format), 5 colors
    xmcd_b.px - for SCO Open Desktop (XPM2 C format), 5 colors
    xmcd.xpm  - for other systems that use XPM format, 5 colors
    xmcd14.icon - for Novell/SCO UnixWare, 14 colors
    xmcd14_a.px - for SCO Open Desktop (XPM2 format), 14 colors
    xmcd14_b.px - for SCO Open Desktop (XPM2 C format), 14 colors
    xmcd14.xpm  - for other systems that use XPM format, 14 colors

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/NetBSD/OpenBSD 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
    XMCDLIB/config/DEVICE configuration file:

	volumeControlSupport:	False
	balanceControlSupport:	False
	channelRouteSupport:	False

    The Hitachi SCSI-1 CD-ROM drives will not work on the BSD/OS 2.x
    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

    There appears to be a serious bug in Digital UNIX 4.0B that prevents
    xmcd/cda from working properly, The symptom is that the CD-ROM device
    cannot be opened by xmcd/cda (The message is displayed repeatedly
    on stderr: "Cannot open /dev/rrz4c (errno=6).").  Once this happens,
    the CD-ROM device becomes inaccessible to other programs and the
    only solution is to reboot.  The fix to this problem is to upgrade
    to a later version of the OS.

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

    Warning: The Iso9660fsys driver must NOT be running while you use
    xmcd/cda, or else you risk filesystem corruption.

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.

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 XMCDLIB/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:

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

On the AIX, FreeBSD, Linux, NetBSD, OpenBSD, 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 XMCDLIB/config/DEVICE file (where DEVICE is the basename of the
CD-ROM special file).

On AIX, Digital UNIX, 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 Digital UNIX and SCO OSR5 platforms
support the ATAPI/IDE drives via SCSI emulation.  Thus, xmcd/cda will
still operate in the SCSI pass-through method with 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/Documentation/cdrom/*
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/NetBSD/OpenBSD 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.


MULTI-DISC CHANGERS
-------------------

This version of xmcd/cda supports the use of multi-disc changers
and jukeboxes.  Depending upon the type of disc changer you have,
You must select one of the following methods to enable the disc
change capability:

1. SCSI LUN addressing method:

    This is for SCSI changers that occupy one SCSI ID, but allows
    software selects the disc via the LUN (logical unit number)
    address.

    This method is used only for SCSI disc changers that support
    eight discs or less.

    In order for this method to work, your OS platform must support
    separate device nodes for each LUN of the device.  Thus, for
    a 6-disc changer, there must be siz separate device nodes for
    the changer, one for each of the "slots".  Not all platforms
    support this.  On platforms that don't have separate nodes for
    each LUN, xmcd/cda will not be able to change discs.

    This method has been tested and works on HP-UX 9.x and 10.x,
    Linux 2.x, Solaris 2.x and UnixWare 2.x.  It may work on other
    platforms, but we have not tested on them.  If you get this method
    to work on a platform not listed here, please drop us a note at
    xmcd@amb.org to let me know.

2. SCSI medium-changer method:

    This is for SCSI changers that occupy one SCSI ID, with the
    player on one LUN and a medium changer mechanism on another LUN.
    Another variation of this is to have the player on one SCSI ID
    and the medium changer mechanism on another SCSI ID.

    This is typically used on SCSI CD-ROM jukeboxes that support 
    more than eight discs.

    In order for this method to work, your OS platform must support
    a device node for the CD player as well as a separate device node
    for the medium changer mechanism.  Not all systems support this.
    On platforms that don't have a separate node for the medium changer,
    xmcd/cda will not be able to change discs.  Platforms that support
    this interface includes Linux 2.x and UnixWare 2.x.

    This method currently is specifically coded for the Pioneer
    DRM-1804X 18-disc changer.  It may also work with other changers
    with a similar software interface.

    If you have one of these Pioneer changers (or other changers of
    this type), please contact xmcd@amb.org.

3. Non-SCSI OS ioctl method:

    This is for non-SCSI units which has OS ioctl support in the
    CD-ROM driver for disc change operations.

    Currently, this method will work only on late versions of Linux
    kernel 2.0.x and Linux 2.1.x and later.  Moreover, it works
    only for ATAPI/IDE changers via the "ide-cd" driver.  See the
    /usr/src/linux/Documentation/cdrom/ide-cd file for details about
    which drives are supported.

    Due to problems in some versions of the ide-cd driver xmcd/cda
    may have problems changing discs when there are empty slots in
    the CD changer.


The changer control method is configured via the mediumChangeMethod,
numDiscs and deviceList parameters.  These are set up for you when
you install xmcd, or when you run the LIBDIR/xmcd/config.config.sh
script.

Note that if the "multi-play" option is enabled, xmcd/cda scans
each changer slot in order, after a disc is ejected.  This is in
support of changers that have individually eject-able discs.  On
changers that use a magazine (where all discs are ejected at once),
after the magazine is reinserted, xmcd may "land" on the first CD
that it detects while scanning.  This is not necessarily the first
disc in the magazine.  Also, on changers that have individually
eject-able slots, the "auto-eject on done" feature will only eject
the first disc when the "multi-play" mode is finished.


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 public
xmcd 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
XMCDLIB/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 XMCDLIB/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.

A list of current Internet public xmcd CD database servers can be found
on the CD database web site (see below).  Please use hosts that are closest
to you for best response time.

If you don't have a web browser, you can also get a list of public
servers using the telnet command.  Connect to port 888 of "cddb.cddb.com":

    telnet cddb.cddb.com 888

After you see the sign-on banner, issue the "sites" command.  A list of
current public servers will be displayed.  Type "quit" to disconnect.

E-mail regarding the CD database and the servers should be directed to
"cddb-support@moonsoft.com".


WORLD WIDE WEB SITES 
--------------------

The xmcd/cda web site is at:

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

This site provides up-to-date information about the current release
version, online README file, Frequently Asked Questions (and answers),
and late breaking announcement, if any.

The source code bundle and pre-compiled binary releases of xmcd/cda
for certain OS environments are also available from this site.

The CD database web page is at:

    http://www.cddb.com/

This site provides details about how to use the CD database, a public
xmcd CD database server sites list, FAQ, server access statistics,
FTP service to download the CD database archive, links to other apps
which also support the xmcd CD database, and other information.

Also available is the Online CD Database Search engine.  This is
based on the xmcd CD database and allows you to find entries
in the database quickly.  Just follow the link from the CD database
page.

You are invited to visit these sites and make use of their services.
Please be sure to read the FAQ section on the CD database site before
sending submissions to the master database.


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

You are invited to use 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>

    BSDI BSD/OS 3.x port:
	Chris P. Ross <cross@va.pubnix.com>

    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/NetBSD/OpenBSD 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/NetBSD/OpenBSD 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 programs, 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!

