#
# @(#)README	2.43 94/02/16
#
Xmcd (Motif(tm) CD Audio Player) by Ti Kan
------------------------------------------

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

This is the release notes for xmcd, the X11/Motif-based CD audio player
utility.  Please read through this file before building, installing, or
using xmcd.  You should also read the INSTALL file if you will be
compiling xmcd from the source code distribution.  After installing
xmcd, you can use the man(1) or xman(1) command to read the on-line
manual entry.  The CHANGES file contains a revision log.


SOURCE CODE RELEASE NOTES
-------------------------

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


	1.  DEC OSF/1 (on DEC Alpha AXP)
	    - DEC OSF/1 version 1.3 or later (see notes below)

	2.  DEC Ultrix (on DECstation)
	    - DEC Ultrix version 4.3 or later
	      (with SCSI CAM installed, see notes below)

	3.  HP-UX (on HP Series 700 PA-RISC)
	    - HP-UX Release 9.x or later

	4.  IBM AIX (on IBM RS/6000)
	    - AIX version 3.2.x

	5.  Linux (on Intel x86)
	    - Linux SCSI kernel 0.99plxx or later with
	      XFree86 (X11R5) + Motif 1.2

	6.  Silicon Graphics IRIX (on SGI)
	    - IRIX version 4.x
	    - IRIX version 5.x

	7.  SunOS (on Sun Sparc)
	    - SunOS 4.1.x / Solaris 1.x (see notes below)

	8.  SunOS (on Sun Sparc)
	    - SunOS 5.x / Solaris 2.x (see notes below)

	9.  SunOS (on Intel x86)
	    - SunOS 5.x / Solaris 2.x (see notes below)

	10. UNIX System V Release 3.2 (on Intel x86)
	    - SCO Open Desktop Version 2.x (X11R4 or X11R5 server)
	    - SCO Open Desktop Version 3.x
	    - SCO UNIX 3.2v4.x with XFree86 (X11R5) + Motif 1.2

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

	12. UNIX System V Release 4.0 (on Motorola 88k)
	    - Motorola

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

	14. UNIX System V Release 4.2MP (on Intel x86)
	    - Novell/USL UnixWare 2.x


In general, binaries compiled on one OS can run on another OS under
the same group.  Thus, xmcd compiled on Consensys SVR4.0 should run
on ESIX SVR4.0, but not on Univel UnixWare or SCO ODT.  There are some
issues with shared library compatibility amongst the different SVR4.0
vendors, so it is best to run xmcd on the same OS that it's compiled
on.

Xmcd must be installed as a setuid-root program on virtually all
platforms.  This is because xmcd uses the SCSI pass-through mechanism
to control the CD-ROM drive, which requires root privilege on most
systems.  Xmcd has been designed to be quite secure, however, since it
does not send read/write commands to a device.  It will also refuse to
send any more commands to a device if the initial inquiry shows that
the device is not a CD-ROM.  Also, xmcd changes the uid to that of the
real user before reading/writing any CD database files.

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

The minimum DEC Ultrix and OSF/1 OS version listed above should be
heeded.  Running xmcd on earlier releases of either OS may cause
the system to crash, due to bugs in the OS.  The port of xmcd to the
DEC platforms has not been extensively tested as of this writing.
Please send fixes to the author.

Xmcd's 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.  Please note it has been observed
that at least on some SunOS 4.x systems, 12-byte SCSI commands are
not properly supported by the Sun CD-ROM driver.  Thus, if you have
a SCSI-2 CD-ROM drive, be sure that the "playAudio12Support" parameter
is set to "False" in your xmcd device-specific configuration file
(such as /usr/lib/X11/xmcd/config/rsr0).  Because of this OS
limitation, the SCSI-1 Hitachi CD-ROM drives (which has all 12-byte
vendor-unique SCSI-1 audio commands) may not work under SunOS 4.1.

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" X resource 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, then you should set exitOnEject to
True.  Also, if the 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.

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 SGI IRIX systems.  To remedy this, remove the "\"
continuation markers and join the multiple lines back into a single
line.

Several portions of xmcd were contributed by these dedicated individuals:

    Motorola SVR4/88K port:
	Mark Scott (mscott@urbana.mot.com)

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

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

    In addition, several Solaris 2.x enhancements were contributed
    by Lee Duncan (Lee.Duncan@sun.com).

Although xmcd 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 xmcd with the -debug option, and capture the
disgnostic output.  Send the output to the author for examination.

Better yet, send bug fixes!

See the INSTALL file for information about the required X11 and Motif
library versions and configurations, and build/install instructions.

For Copyright information, read the COPYING file.

The modular design of xmcd is such that support for other UNIX
environments can be easily added by implementing a new OS-interface
library module for xmcd.  Moreover, support for other non SCSI-2
compliant CD-ROM drives can also be added via new vendor-unique
library modules.  See the "PORTING" file for details if you are
interested in contributing to the development effort to make xmcd
run under more environments and support more CD-ROM drives.  Before
you start a porting effort or add significant code, contact the
author to ensure that this effort isn't being duplicated by others.


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

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.
	- Volume control.
	- Shuffle (random) play function.
	- Repeat function.
	- 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.
	- 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.
	- 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.
	- 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 in the .Xdefaults file.
	- All colors and many other functionality are user-customizable
	  using X resource settings.
	- On-line help information.
	- Attractive, intuitive-to-use Motif user interface.


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.

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

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

Certain OS platforms will print console error messages 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.

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


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

This release of xmcd should work with the following CD-ROM drives.
See notes below for specific information:

	Apple CD SC+
	Apple CD-150
	Apple CD-300
	Apple CD-300i
	Chinon CDS-431
	Chinon CDX-431
	Chinon CDS-435
	Chinon CDX-435
	Chinon CDS-535
	Chinon CDX-535
	Compaq CDU-561
	Compaq CR-503BCQ
	DEC RRD42
	Hitachi CDR-1650S
	Hitachi CDR-1750S
	Hitachi CDR-1950S
	Hitachi CDR-3650
	Hitachi CDR-3750
	Hitachi CDR-6750
	IBM 7210-001
	NEC CDR-72
	NEC CDR-74
	NEC CDR-77
	NEC CDR-80
	NEC CDR-82
	NEC CDR-84
	NEC CDR-38 (*)
	NEC CDR-74-1 (*)
	NEC CDR-84-1 (*)
	NEC CDR-500 (Multispin 3Xe)
	NEC CDR-510 (Multispin 3Xi)
	NEC CDR-600 (Multispin 3Xp)
	Pioneer DRM-600
	Pioneer DRM-600A
	Pioneer DRM-610
	Pioneer DRM-602X
	Pioneer DRM-604X (*)
	Pioneer DRM-1804X
	Plextor/Texel DM-3024
	Plextor/Texel DM-5024
	Plextor/Texel DM-3028
	Plextor/Texel DM-5028
	Procom CDT4-3X
	Procom CDT4-DS
	Procom CDT4-MX
	Procom CDT7-3X
	Procom CDT7-DS
	Procom DSP-DR0020
	Procom ICD-MX
	Procom MCD-DS
	Procom MCDN-3X
	Procom SICD-DS
	Procom SICDN-3X
	Procom SXCD-DS
	Procom SXCDN-3X
	Sony CDU-541
	Sony CDU-561
	Sony CDU-6111
	Sony CDU-6211
	Sony CDU-7211
	Sony CDU-7811
	Sony CDU-8002
	Sony CDU-8003
	Sony CDU-8003A
	Sony CDU-8012
	Sun CD-ROM
	Toshiba XM-3101
	Toshiba XM-3201
	Toshiba XM-3301
	Toshiba XM-3401
	Toshiba XM-4101
	Toshiba XM-8100
	Other SCSI-2 compliant CD-ROM drives

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/configure.sh
program).  Depending upon the specific model, you may find that xmcd
supports more features while operating in SCSI-2 mode.  See the CD-ROM
drive owner's manual for details about setting the mode.

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.  The
CDx-535 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 CD-ROM drives while
the unit is playing audio.  Use xmcd's software eject button instead.
Also, you may wish to adjust the XMcd.searchSkipBlocks and
XMcd.searchPauseInterval resources to achieve the best audio
sampling effect during REW and FF search operations.

This release of xmcd 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 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 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.

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

If you have a CD-ROM drive not listed above, I would appreciate a note
from you regarding whether it works with xmcd 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, 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,
synchronous negotiation is configurable via the on-board setup program,
and is settable on a per-ID basis.  Please consult your SCSI host
adapter board owner's manual for information.


WHERE TO GET XMCD
-----------------
The source code release of xmcd version 1.1 is available via Internet
anonymous FTP.  Location:

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

	ftp.x.org:/contrib/xmcd-1.1.tar.Z	(compress'd tar archive)
		or
	ftp.x.org:/contrib/xmcd-1.1.tar.gz	(gzip'd tar archive)

An xmcd CD database is also available via FTP:

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

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

This database is periodically updated with more entries, and you are
encouraged to contribute to this database by sending entries via
e-mail to "ti@amb.org".

Binary releases of xmcd-1.1 for certain OS environments are also available
from the author.   Please write to "ti@amb.org" for more information.


ACKNOWLEGEMENTS
---------------

Companies names and product names appearing in this file are each
trademarks of the respective company.  The names are for identification
purposes only.  Xmcd 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 of xmcd.
Many thanks also goes out to those that have contributed code to xmcd!

