XMCD(1) v2.5 XMCD(1)
18 March 1998
NAME
xmcd - CD digital audio player utility for X11/Motif
SYNOPSIS
xmcd [toolkitoption ...] [-dev device] [-instcmap] [-debug] [-c device]
[-X] [-o]
DESCRIPTION
Xmcd is a program that allows the use of the CD-ROM or CD-R drive as a
full-featured stereo compact-disc player for the X window system. See
cda(1) for the command-line CD player. xmcd and cda uses the same
configuration and support files.
Most of the features found on "real" CD players are available in xmcd,
such as shuffle and repeat, track programming functions, a numeric
keypad and track warp slider for direct track access. Additional
functions include sample play, A to B segment play, volume control,
balance control, etc. Several automation options are also available
on CD load, eject, play completion and program exit. A Channel
Routing feature allow you to select from several stereo or mono
routing options. The volume control slider taper characteristics can
also be altered.
Multi-disc changers are also supported. There are buttons to switch
to the next or previous disc in the changer, as well as a way to
specify a specific disc via the keypad. You can select to play only a
single disc or auto-play all discs in normal or reverse order.
A CD database feature allows the CD artist/title and track titles, and
other associated general purpose text to be maintained and loaded as
the program is started or when a CD is inserted. The CD database
contents can be on your local system or queried from a remote CD
database server host. There are a number of worldwide Internet public
CD database servers in operation, serving in both CDDBP (CD database
protocol) and HTTP (Hyper-text transport protocol). Xmcd supports
both of these protocols.
Full feature-specific pop-up help is available for all controls,
indicators, text input fields, and lists.
On systems with more than one CD-ROM or CD-R drive, multiple
invocations of xmcd can be used to operate each drive independently.
Xmcd is designed to be easy to use, as the main window is purposely
made to resemble a real CD player front panel. All other pop-up
windows are also designed to be as intuitive as possible. Moreover,
while the use of a mouse is natural with xmcd, all functionality can
also be operated via the keyboard. This is in conformance to the
guidelines published in the OSF/Motif Style Guide from the Open
- 1 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
Software Foundation.
The internal architecture of xmcd is designed to be easily portable to
many UNIX operating system variants, and adaptable to the myriad of
CD-ROM drives available.
OPTIONS
All standard Xt Intrinsics toolkit options are supported. In
addition, xmcd supports the following options:
-dev device
Specifies the path name to the raw CD-ROM device. If this option
is not used, the default device to be used is the first drive set
up with the xmcd configuration program (See below).
-debug
Causes verbose debugging diagnostics to be printed on stderr.
-instcmap
Causes xmcd to install its own colormap. This may be desirable
if xmcd is to be used at the same time as other color-intensive
applications, which would otherwise cause xmcd to be unable to
allocate all its needed colors. Note that when running on an X
display that does not support many concurrent colormaps, this may
cause other windows to change colors when xmcd has the input
focus.
-c device (Solaris 2 only)
Same as the -dev option.
-X (Solaris 2 only)
Causes the exitOnEject parameter to be set to True.
-o (Solaris 2 only)
This option has no effect.
The -c, -X and -o options are provided only on the Solaris 2 platform
for compatibility with the action_workman.so auto-startup program,
running under the Solaris 2 Volume Manager. See the README file in
the xmcd distribution about configuring xmcd for the Solaris 2 Volume
Manager.
X RESOURCES
Xmcd has many adjustable X resources to customize its look and feel,
as well as its behavior. Notably, the colors of virtually every
feature on xmcd's windows can be changed, as well as the text fonts.
All text labels can also be changed (for example, to another
language).
- 2 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
There are too many resources to list here, but the resource names and
their defaults (plus descriptive comments) can be found in the
XMCDLIB/app-defaults/XMcd file (where XMCDLIB is typically
/usr/lib/X11/xmcd). It is not recommended that you change values in
the XMCDLIB/app-defaults/XMcd file, unless you want the changes to be
forced upon all users of xmcd on the system. Instead, make a copy of
this file, change the copy as you see fit, then place it in your home
directory. Your custom resource settings will then override the
defaults when xmcd is subsequently started. Alternatively, you may
also place specific resources you wish to override in the .Xdefaults
file in your home directory.
DEVICE CONFIGURATION
The X resources described in the previous section affect the general
appearance and behavior of xmcd. There are two additional
configuration files which are used to adapt xmcd to your site
requirements. The first of these contain common parameters, and the
second contain configurable parameters that must vary on a per-drive
basis. For example, in some cases xmcd must operate the drive
differently depending upon the brand and model of the drive. Thus,
there must be a separate configuration file for these parameters per-
device. The common parameters file is XMCDLIB/config/common.cfg and
the device-specific parameters file is XMCDLIB/config/DEVICE (where
XMCDLIB is typically /usr/lib/X11/xmcd and DEVICE is the base name of
the raw device special file for the CD-ROM drive ; e.g.,
/usr/lib/X11/xmcd/config/rcd0). A configuration program
XMCDLIB/config/config.sh is provided to make maintaining these
configuration file easy (Note: on SCO systems the configuration
program can also be invoked as "mkdev xmcd").
You should always use the configuration program to set the
configuration parameters when installing xmcd for the first time, or
when the CD-ROM hardware configuration has changed. If this is not
done then xmcd will probably not operate correctly with your CD-ROM
drive.
WARNING: If xmcd is not correctly configured, you may cause xmcd to
deliver commands that are not supported by your CD-ROM drive. Under
some environments this may lead to system hang or crash.
You can override some of the device-specific configuration parameters
by adding your own configuration files. Xmcd will also look in the
HOME/.xmcdcfg/common.cfg and HOME/.xmcdcfg/DEVICE files for common and
device-specific parameters (where HOME is your home directory and
DEVICE is as specified above). Parameters found in this file will
override the system defaults (except those parameters that cannot be
overridden; see the comments in the XMCDLIB/config/device.cfg for
details).
- 3 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
USING XMCD
The basic functions of xmcd are designed to operate the same way as on
a real stereo CD player. The pictorial symbols used on the main
window buttons are intended to illustrate the function in a non-
language-specific manner. You can also change all main window buttons
to display a text label instead of the pictorial symbols, by clicking
the btn check-box button (the "A" symbol enclosed in a box) located at
the upper left hand corner of the main window.
The CD database and track programming functions are operated via the
CD Database/Track Program Editor pop-up subwindow. You activate the
subwindow by clicking the cddb/prog button (file cabinet symbol) on
the main window (See "CD DATABASE" below).
There will not be a per-item description of all the features, because
full on-line help is available (See "ONLINE HELP" below).
ONLINE HELP
For general information about xmcd, click the help (question mark
symbol) button on the xmcd main window. You can also get specific
help information about each button, control, indicator, text entry
area, selection list by positioning the mouse cursor over the desired
item, then clicking the third mouse button. A pop-up window will
appear, containing the relevant help text.
TRACK PROGRAMMING
You can program xmcd to play only certain tracks, in a custom
sequence. To do so, invoke the CD Database window (by clicking the
cddb/prog button on the main window). Select the desired track by
clicking on the entry in the Track list, and click the Add button to
add to the play sequence. Notice that the track number appears in the
Program sequence text field. You can also type the track numbers,
separated with commas, directly in the Program sequence field. Repeat
until all desired tracks have been entered, then click the Play/Pause
button (on the main window) to start the program play.
When a program sequence is defined, the prog indicator in the main
window display area "illuminates". To erase the program sequence,
click the Clear button on the CD Database/Program Editor window.
CD DATABASE
The CD Database feature of xmcd allows you to enter the CD
artist/title, track titles, other free-form text (such as band
information, lyrics, etc.) associated with the disc and tracks, and a
track play program. After this information is typed in and saved to a
database file, it will automatically appear on the xmcd CD Database
window the next time you insert the same CD.
- 4 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
You must perform a "save" operation (click the Save button) after
typing in the database information before ejecting the CD or exiting,
or the information will be lost. If this is the first time this CD
database entry is being stored, you will be asked to select a category
(rock, classical, jazz, etc.) under which to classify the CD. The
category is used by xmcd to determine the actual directory in the
filesystem to write the database file.
You must type the CD information into the database because the CD's
table of contents (TOC) contains only the number of tracks and the
starting address of each track, but not the actual disc and track
titles.
The CD database window should prove to be intuitive to use. You may
use the on-line help system to obtain specific help information about
the various buttons and items.
The CD database information is stored in text files, one per CD, in a
designated directory (category). The path of this directory is
CDDBDIR/CATEGORY, where CDDBDIR is the top level directory of the
local CD database. CDDBDIR is typically /usr/lib/X11/xmcd/cddb and
CATEGORY is the category name selected when Save is performed. See
the description of XMCD_CDDBPATH in the ENVIRONMENT section below.
You may view the list of directories that xmcd will search for CD
database files by clicking the About... button and viewing the pop-up
information window.
The file name of each CD database entry is a hexadecimal
representation of a special "magic" number computed by xmcd based on
the number of tracks, track timings, and other available information
about this CD. This method is used because there is no reliable
unique CD identifier to be found on the CD itself (the CD standard
allows for a readable IPC/barcode but very few CDs actually contain
such information).
Since different pressings of the same CD may sometimes contain
slightly different track timings, the resultant magic number computed
by xmcd on these CDs will be different. Thus, if you load a CD that
is not the same one that a CD database entry was created with (but is
actually the same CD title), xmcd may not recognize it and display the
database information automatically when you insert the CD. In this
event, you can search the CD database and find the appropriate entry,
and establish a "link" to it. To do so, click the Link button, and
select the appropriate category on the popup window. Xmcd will then
present another pop-up window containing a list of all CD database
entries in the specified category (that has the same number of tracks
as the currently inserted disc). Select the appropriate entry and a
link will be made in the CD database.
- 5 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
The Link feature alleviates the need to type in CD database
information again and avoids duplicate CD database entries.
In very rare occasions it is possible that the magic number of a CD
conflicts with that of another. This is a problem that will be
addressed in a future release of xmcd.
A master xmcd CD database of thousands of CD titles is available for
Internet anonymous FTP. Visit the xmcd web site for details. You are
encouraged to contribute to this database by sending CD database
entries (that you typed in) to the archive. The master CD database is
updated periodically with new user-contributed entries. To do so, you
click the Submit... button on the CD database/Track Program Editor
pop-up subwindow. Clicking this button causes the CD database entry
(associated with the currently loaded CD) to be sent to the xmcd
master CD database server. You should use this feature only if your
computer is configured to send Internet electronic mail. You can send
a CD database entry only after you first save it to your local CD
database.
Xmcd also has the ability to query a remote CD database server host
for CD database information. Thus, it is not necessary to keep a full
copy of the master CD database locally. If your system is connected
to a TCP/IP network (such as the Internet) and has access to a server
system running the CD database server program, you can configure your
xmcd client to query the server. The cddbPath parameter or the
XMCD_CDDBPATH environment variable is used to configure the use of a
remote server. See the ENVIRONMENT section below for details.
You may configure xmcd to communicate with the CD database server in
either CDDBP or HTTP protocols. The CDDBP protocol is the standard CD
database protocol developed for use by xmcd and other clients. The
HTTP protocol is intended for users who are behind a firewall that
allows HTTP traffic (for web access) but blocks the normal CDDBP port,
Not all public CD database server sites support HTTP. Please visit
the CD database server web site to get a list of the current public CD
database servers in operation, and the protocols they support.
While xmcd is running, the file /tmp/.cdaudio/curr.nnnn (where nnnn is
the hexadecimal representation of the CD-ROM's device number) contains
the device node path, CD database category and disc identifier
information pertaining to the currently loaded CD. Other applications
may read this file to identify the currently loaded disc.
ENVIRONMENT
Several environment variables are currently recognized by xmcd, and
are described as follows:
XMCD_LIBDIR
This parameter is the directory path under which xmcd's
- 6 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
configuration files, help files, and CD database files are
located. The default value of XMCD_LIBDIR on most systems is
/usr/lib/X11/xmcd.
XMCD_CDDBPATH
This is used to override the cddbPath common configuration
parameter, which is a list of CD database category directories to
be used under $XMCD_LIBDIR/cddb. Also, remote CD database hosts
can be specified.
rock;classical;jazz;newage;soundtrack;misc
This string will cause xmcd to search the following directories
for CD database files:
XMCDLIB/cddb/rock
XMCDLIB/cddb/classical
XMCDLIB/cddb/jazz
etc.
You may also specify absolute path names in the XMCD_CDDBPATH
entries. Example:
rock;classical;/home/john/industrial;~john/punk;~/cddb/jazz
You may also specify a remote CD database server hosts which xmcd
can use to query CD database information. The syntax is in URL
form:
protocol://hostname[:port]/path
The protocol is either "cddbp" or "http", depending on which
protocol you want xmcd to use to communicate with the remote
server. The hostname can be a fully qualified host name or an IP
number. The port number is optional (the default is 888 for
cddbp and 80 for http ) and the path is used only in the http
mode.
Example:
country;folk;cddbp://abc.fubar.com;http://xyz.snafu.com/~cddb/cddb.cgi
HOME This is used to determine your home directory. Xmcd first tries
to obtain your home directory from the /etc/passwd file. If that
is not found, then it uses what is defined in the HOME
environment variable. The home directory path is used by xmcd to
locate the .xmcdcfg directory.
NOTES
Not all CD-ROM drives support all features that appear on xmcd. For
- 7 - Formatted: January 15, 2025
XMCD(1) v2.5 XMCD(1)
18 March 1998
example, some drives do not support a software-driven volume control.
On these drives the xmcd volume control slider may have no effect, or
in some cases it is made to function as a mute control (i.e., it will
snap to the full-off or full-on positions only). Similarly, the caddy
lock, eject and index search buttons found on xmcd may not have any
effect on drives that do not support the appropriate functionality.
FILES
$HOME/.xmcdcfg/*
XMCDLIB/cddb/*
XMCDLIB/config/config.sh
XMCDLIB/config/common.cfg
XMCDLIB/config/device.cfg
XMCDLIB/config/.tbl/*
XMCDLIB/config/*
XMCDLIB/help/*
LIBDIR/app-defaults/XMcd
BINDIR/xmcd
MANDIR/xmcd.1
/tmp/.cdaudio/*
RELATED WEB SITES
Xmcd/cda home page: http://metalab.unc.edu/tkan/xmcd/
CD database server page: http://www.cddb.com/
Xmmix home page: http://metalab.unc.edu/tkan/xmmix/
SEE ALSO
cda(1), cddbcmd(1), wm2xmcd(1), X(1),
Xmcd's README and INSTALL files
Xmcd web site: http://metalab.unc.edu/tkan/xmcd/
CDDB web site: http://www.cddb.com/
AUTHOR
Ti Kan (ti@amb.org)
AMB Research Laboratories, Sunnyvale, CA, U.S.A.
Xmcd also contains code contributed by several dedicated individuals.
See the README file in the xmcd distribution for information.
Comments, suggestions, and bug reports are always welcome.
- 8 - Formatted: January 15, 2025
