xmcd

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


     SYNOPSIS
          xmcd [toolkitoption ...] [-dev device] [-debug] [-c device]
          [-X] [-o]


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

          A built-in 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.

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

          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.

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

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


     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 display
          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 pressing 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 pressing 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 Play
          sequence text field.  You can also type the track numbers,
          separated with commas, directly in the Play sequence field.
          Repeat until all desired tracks have been entered, then
          press 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, press 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 when the same CD is
          inserted again.

          You must perform a "save" operation (press 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.

          Once the database information has been saved, the cddb
          indicator on the xmcd main window display area
          "illuminates".

          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 XMCDLIB/cddb/CATEGORY, where XMCDLIB is the
          directory specified by the XMcd.libdir resource, and
          CATEGORY is the category name selected when Save is
          performed.  See the description of XMCD_DBPATH in the
          ENVIRONMENT section below.

          You may view the list of directories that xmcd will search
          for CD database files by pressing 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, press 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.

          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.  See the README file
          of your current xmcd distribution 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.  This version of xmcd makes CD database
          contribution easier with the Send button on the CD
          database/Track Program Editor pop-up subwindow.  Pressing
          this button causes the CD database entry (associated with
          the currently loaded CD) to be mailed to the xmcd CD
          database archive maintainer.  You should use this feature
          only if your computer is configured to send Internet
          electronic mail.


     ENVIRONMENT
          Several environment variables are currently recognized by
          xmcd, and are described as follows:

          XMCD_LIBDIR
               This is used to override the XMcd.libdir resource.
               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 most
               systems is /usr/lib/X11/xmcd.

          XMCD_DBPATH
               This is used to override the dbdirs common
               configuration parameter, which is a list of CD database
               category directories to be used under XMCDLIB/cddb
               (where XMCDLIB is the directory root specified by the
               XMcd.libdir resource or the XMCD_LIBDIR environment
               variable).

                   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_DBPATH entries.  Example:

                   rock:classical:/usr/john/industrial:/usr/john/techno

          HOME This is used to determine your home directory.  If HOME
               is not defined, then xmcd tries to obtain it from the
               /etc/passwd file.  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, most SCSI-1 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/configure.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/*


     SEE ALSO
          cda(1), wm2xmcd(1), X(1).


     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.

Contributed by

Ronald Joe Record (rr@ronrecord.com)

Obtained from

Anonymous ftp to ftp.x.org :

        (instructions)
        ftp.x.org:/contrib/applications/xmcd/xmcd-1.4.README
        (gzip'd tar archive)
        ftp.x.org:/contrib/applications/xmcd/xmcd-1.4.tar.gz
        
        An xmcd CD database is also available via anonymous FTP:
        
        (Instructions)
        ftp.x.org:/contrib/applications/xmcd/xmcd-cddb.README
        (gzip'd tar archive)
        ftp.x.org:/contrib/applications/xmcd/xmcd-cddb.tar.gz

Further Information

See the README