XMCD(1)                    OpenBSD Reference Manual                    XMCD(1)



NAME
       xmcd - CD digital audio player utility for X11/Motif


SYNOPSIS
       xmcd [toolkitoption ...] [-dev device] [-instcmap] [-remote] [-rmthost
       hostname] [-help] [-debug] [-c device] [-X] [-o] [command [arg ...]]


DESCRIPTION
       Xmcd is a program that allows the use of the CD-ROM, CD-R or CD-RW
       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.

       Xmcd provides the ability to drive a web browser and search for web
       sites related to the currently playing CD artist or track.  You may
       also drive the web browser via xmcd to access online music reviews and
       go to the official xmcd and CDDB web sites.  Moreover, the browser
       integration gives users the ability to manage local discography
       information pertaining to his or her CD collection.

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

       Many functions on a running xmcd session can be "remote controlled"
       from the command line via the -remote option.  See the OPTIONS section
       below.

       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 (such as
       -display, -geometry. -iconic, etc.).  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).

       -help  Causes command line usage information to be displayed on stderr.

       -debug Causes verbose debugging diagnostics to be displayed 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.

       -remote
              Causes a command to be sent to another running xmcd process.
              The command and appropriate arguments are specified at the
              invoking shell (or shell script) as command-line arguments,
              After the command is delivered, the "sender" xmcd process exits,
              and the "receiver" process responds by executing the command.
              In effect, the sender becomes a remote control for a running
              xmcd session.  See "COMMANDS" below for a list of supported
              commands.

              The sender xmcd process can be invoked on the same host or on a
              different host than the receiver xmcd process.  By default, the
              sender will attempt to locate an xmcd process running on the
              same X display (determined by the DISPLAY environment variable
              or the -display option), and controlling the same default CD-ROM
              device.  You may specify the device via the -dev option to
              override the default.  Use of the -dev and -rmthost options on
              the sender's command line can resolve ambiguities when there are
              multiple xmcd clients displaying on the same X server.

       -rmthost hostname
              This may be used with the -remote option to specify the host on
              which the receiver xmcd client must be running.

       -c device (Solaris only)
              Same as the -dev option.

       -X (Solaris only)
              Causes the exitOnEject parameter to be set to True.

       -o (Solaris only)
              This option has no effect.

       The -c, -X and -o options are provided only on the Solaris platform for
       compatibility with the action_workman.so auto-startup program, running
       under the Solaris Volume Manager (vold).  See the README file in the
       xmcd distribution about configuring xmcd for the Solaris 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).

       There are too many resources to list here, but the resource names and
       their defaults (plus descriptive comments) can be found in the
       /usr/local/lib/X11/app-defaults/XMcd file.  It is not recommended that
       you change values in this 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.


COMMANDS
       You may specify a command as an xmcd command line argument, to make
       xmcd execute the command after initial startup.  For example, the
       following command starts xmcd and then begins playing at track 4:

           xmcd play 4 &


       If the -remote option is used, then the command is sent to another
       running xmcd process for execution (See "OPTIONS" above).

       The supported commands are:

       stop   Stop playback.

       play [track# | min:sec | track#:min:sec]
              Start playback.  You may also specify the starting track number,
              and/or the starting minute and second offset.

       pause  Pause the playback.  You may resume the playback by using either
              the pause command again, or the play command.

       sample Start sample playback.  This will play each track for 10
              seconds.

       disc <load | eject | prev | next | disc#>
              Perform a disc operation:  Load or eject the CD, or change to
              another disc on a multi-disc changer.

       track <prev | next | track#>
              Perform a track operation: Change to the previous or next track,
              or a specified track number.

       index <prev | next>
              Perform an index operation: Change to the previous or next
              index.

       lock <on | off>
              Enable or disable the caddy (or disc tray) lock.  When enabled,
              pressing the eject button on the drive will not eject the CD.

       shuffle <on | off>
              Enable or disable shuffle (random play) mode.

       repeat <on | off>
              Enable or disable repeat mode.

       program <clear | track# ...>
              Set or clear a track program sequence.  Track numbers may be
              space or comma-separated.

       volume <value# | linear | square | invsqr>
              Volume control operation.  You can specify a numeric value to
              set the volume level (The range is 0 to 100), or change the
              volume control's taper characteristic: linear, square, or
              inverse-square.

       balance value#
              Balance control.  The value should be between 0 and 100.   50 is
              center, 0 is full-left, and 100 is full-right.

       route <stereo | reverse | mono-l | mono-r | mono | value#>
              Channel routing control.  Use one of the appropriate keywords,
              or a value as follows:

              0    Normal stereo
              1    Reverse stereo
              2    Mono-L
              3    Mono-R
              4    Mono-L+R

       time <elapse | e-disc | r-trac | r-disc>
              Change the time display mode.  Select from elapsed track time,
              elapsed disc time, remaining track time, or remaining disc time.

       on-load <autolock | noautolock | none | spindown | autoplay>
              Enable or disable options when a CD is loaded.  The autolock
              option causes the caddy or disc tray to be automatically locked,
              The spindown option will cause the CD to stop after loading to
              conserve the laser and motor.  The autoplay option will cause
              the CD to automatically start playing after loading.  The none,
              spindown and autoplay options are mutually-exclusive.

       on-exit <none | autostop | autoeject>
              Enable or disable options when xmcd exits.  The autostop option
              will cause xmcd to stop playback, and the autoeject option will
              cause xmcd to eject the CD.  Use none to cancel these options.

       on-done <autoeject | noautoeject | autoexit | noautoexit>
              Enable or disable options when xmcd is done with playback.  The
              autoeject option causes xmcd to eject the CD.  The autoexit
              option will cause xmcd to exit.

       on-eject <autoexit | noautoexit>
              Enable or disable options when xmcd ejects a CD.  The autoexit
              option will cause xmcd to exit after ejecting the CD.

       changer <multiplay | nomultiplay | reverse | noreverse>
              Enable or disable multi-disc changer options.  The multiplay
              option specifies that xmcd plays all discs in sequence.  The
              nomultiplay option will cause xmcd to stop after the current
              disc is done.  The reverse option implies multiplay, except that
              the disc order is reversed.

       window <modechg | iconify | deiconify | raise | lower>
              Xmcd window control.  The modechg command causes the main window
              to toggle between the normal mode and basic mode.  In normal
              mode, all controls and indicators are available.  In basic mode,
              xmcd shrinks to a smaller size and only basic controls are
              shown.  The iconify, deiconify, raise and lower commands cause
              the xmcd window to change as specified.

       quit   Causes xmcd to exit.

       debug <on | off>
              Enable or disable debug mode.  When debug mode is enabled, xmcd
              generates verbose debugging diagnostics to be displayed on
              stderr.

       Some of these commands, when used in start-up mode, do not perform a
       meaningful function.  For example, the "track prev" command is not
       useful just after xmcd startup.  It is more appropriate to use this
       command in the remote control mode.


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 @SYCONFIGDIR@/xmcd/common.cfg
       and the device-specific parameters file is /etc/xmcd/DEVICE (where
       DEVICE is the base name of the raw device special file for the CD-ROM
       drive ; e.g., /etc/xmcd/rcd0c).  A configuration program xmcdconfig 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 /etc/xmcd/device.cfg for details).


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.  If enabled, a small "tooltip" will appear after a
       short delay, when you position the mouse cursor over any xmcd main
       window feature.  The tooltip contains textual description of the
       feature.

       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 BCD database/track programming 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 CD
       database/track programming 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.

       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 /var/db/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.

       The Link feature alleviates the need to type in CD database information
       again and avoids duplicate CD database entries.

       A master CD database of hundreds of thousands of CD titles is available
       for Internet access.  Xmcd has the ability to query a remote CDDB
       server host for CD database information.  If your system is connected
       to the Internet, 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.
       Proxy servers are also supported under the HTTP mode.

       You are encouraged to contribute to this database by sending CD
       database entries (that you typed in) to the master CD database.  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 CDDB
       master 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.

       For more information about CDDB, visit the http://www.cddb.com web site
       for details.

       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
              configuration files, help files, and CD database files are
              located.  The default value of XMCD_LIBDIR on modern systems is
              /usr/local/share/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 /var/db/xmcd/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:

                  /var/db/xmcd/cddb/rock
                  /var/db/xmcd/cddb/classical
                  /var/db/xmcd/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
       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.

       The remote control feature (using the -remote option) is governed by
       the standard display server  security mechanisms of the X window
       system.  In order for an xmcd sender client to communicate with a
       running xmcd receiver client, the sender must have the appropriate
       access permissions to the receiver client's X display.  See xhost(1),
       xauth(1) and Xsecurity(1) for more information.  If logging is enabled,
       remote control activity is logged by the xmcd receiver client in the
       $HOME/.xmcdcfg/remote.log file for each xmcd user.


FILES
       $HOME/.xmcdcfg/*
       /etc/xmcd/config.sh
       /etc/xmcd/common.cfg
       /etc/xmcd/device.cfg
       /etc/xmcd/*
       /usr/local/lib/X11/app-defaults/XMcd
       /usr/local/share/doc/xmcd/*
       /usr/local/share/xmcd/help/*
       /usr/local/share/xmcd/tbl/*
       /var/db/xmcd/cddb/*
       /var/db/xmcd/discog/*
       /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), xhost(1), xauth(1), Xsecurity(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.



v2.6                            18 January 2000                        XMCD(1)
