Introduction

This guide describes how to set up the xmcd device configuration file if your CD drive is not listed in xmcd's configuration script menu or if you encounter a drive configuration related difficulty using xmcd or cda.

Xmcd and cda use a very flexible configuration scheme that allows the software to adapt and function with just about any CD-ROM, CD-R, CD-RW or DVD drive. It may only require changing a parameter or two in the configuration file to make it all work.

All descriptions below refer only to xmcd for brevity. The same configuration files are used by xmcd and cda. If you have to change the configuration file to get your drive to work, contact the author and describe what you had to do. Please include your drive manufacturer, model number and the type of device that it is (i.e., SCSI, SATA or IDE/ATAPI, CD-ROM, CD-R or CD-RW).

If you cannot get your drive to work with xmcd using these instructions, you may also contact the author for help.

The device configuration file is:

where XMCDLIB is the xmcd library directory that was specified when installing xmcd, and DEVICE is the base name of the drive's device node. For example, if your XMCDLIB is /usr/lib/X11/xmcd and your drive is /dev/scd0, then the configuration file is /usr/lib/X11/xmcd/config/scd0.

This is a text file contains all the parameters that you can tweak. There are comments above each parameter which describe the function. You may edit this file with an editor and make changes. After a change you can re-start xmcd to check the behavior.

You may also run xmcd with the -debug command line option to see what it's doing (For xmcd version 3.0 and later, use -debug 3). If you write to the author for help, please include this debugging output in its entirety.

What To Do

It is assumed that you have already installed the xmcd package on your system. The installation procedure is displayed on this web site when you downloaded the software. For the source code version of xmcd, the instructions are also found in the docs_d/INSTALL file.

To configure xmcd, you should run the XMCDLIB/config/config.sh script. This script is also run automatically when you install using "sh ./install.sh" (binary distribution) or "make install" (source code distribution, after compilation).

When you run config.sh, it configures xmcd for CDDB access, web browser, and CD drive. It is the CD drive configuration portion that you will see a menu of manufacturers. If your drive manufacturer is listed, select it. If not, choose "other (SCSI)" or "other (non-SCSI)" depending on the type of drive you have.

If you had selected a manufacturer, you will be presented with a list of drive models to choose from. If your drive is listed, congratulations. Select the appropriate drive and you are done. If not, then select another model from the same manufacturer which is the same type ("SCSI-1", "SCSI-2" or "OS driver ioctl" for non-SCSI drives). To decide which model to choose, look for a model number that is similar to yours. You may have a new-generation model that is not yet listed in xmcd's configuration menu, but is otherwise compatible with a previous model. For example, Toshiba's model number scheme generally use an increasing model number for each new generation of drive (XM-3501, XM-3601, XM-3701, etc).

If you choose "other (SCSI-2)", then you will be asked a number of questions about the capabilities of the drive. You may not know the answers, so just accept the defaults.

If you choose a non-SCSI drive configuration, you will be prompted to select an OS ioctl device interface method. Use the one that matches the operating system platform that you're running on.

If your drive is listed in xmcd's configuration menu, then everything should work. There may be some features that your drive doesn't implement, so those will not function. The features that are disabled in the configuration are displayed when you finish running the config.sh script. Also, the configuration data for most of the drives are contributed by users, and may require further fine-tuning. If you encounter an error with some xmcd features, use the hints outlined in this guide to adjust some of the xmcd's drive configuration parameters. If you discover errors in xmcd's configuration tables, please send corrections to the author so that the table would be fixed for the next release.

On recent versions of Linux and FreeBSD, you have the option of running SATA or IDE/ATAPI drives under SCSI-emulation. If your system kernel is configured to use this method, treat your drive as a generic SCSI drive for xmcd configuration purposes.

Likewise, some platforms employ SCSI-emulation for SATA and IDE/ATAPI drive support by default. These platforms are: BSDI/WindRiver BSD/OS, Digital UNIX/Compaq Tru64 UNIX 4.x and later, HP-UX 10.x and later, and SCO Open Server 5.x. The config.sh script automatically sets up SATA or IDE/ATAPI drives as "Generic SCSI" on these platforms. However, further manual fine-tuning may be needed to make use of all the drive's capabilities.

You should also read the DRIVES file that comes in the xmcd distribution for specific information about xmcd's drive support.

Now start xmcd and give it a spin.

Testing the Configuration

NOTE: You will need to restart xmcd each time you change a parameter in the drive configuration file, in order to have it take effect. Be aware that sending an unsupported command to a drive sometimes causes the drive to misbehave or lock up. It may even cause a SCSI bus problem that could lead to a system crash. Type the sync(1) command prior to experimenting with these parameters, and do not do this on a mission-critical server.

SCSI Drives (and SATA, IDE/ATAPI drives running under SCSI emulation)

There are several areas where drive capabilities and compatibilities differ from brand to brand (sometimes even model to model). Here are the symptoms of a misconfiguration:

1. When I start xmcd, it plays the CD just fine, but the time display doesn't advance, and I get a stream of error messages like this:
   
   SCSI command error on /dev/rcd0:
   Opcode=0x42 Status=0x1 Msg=0x0 ...
   Solution:
   
   If the opcode is 42, then try edit your configuration file and change the curposFormat parameter. If it's False, set it to True, or vice versa. Restart xmcd and test.
   
   
2. When I click play, it displays the following error:
   
   SCSI command error on /dev/rcd0:
   Opcode=0x47 Status=0x1 Msg=0x0 ...
   Solution:
   
   Try increasing the spinUpInterval parameter in your configuration file. Some drives are slow to start, and when xmcd asks it to play it fails with a "not ready" status. Restart xmcd and test.
   
   
3. The xmcd volume control, balance control, or channel routing controls don't work. When I use these either there is no effect or it generates error messages:
   
   SCSI command error on /dev/rcd0:
   Opcode=0x1a Status=0x1 Msg=0x0 ...
   or
   SCSI command error on /dev/rcd0:
   Opcode=0x15 Status=0x1 Msg=0x0 ...
   Solution:
   
   Check that the volumeControlSupport, balanceControlSupport and channelRouteSupport parameters to see if they are set to True. If not, change them, restart xmcd and test.
   
   If you still get error messages when you use these features, try experimenting with different combinations of the modeSenseSetDBD and modeSenseUse10Byte parameters. Restart xmcd and test. Note: The modeSenseUse10Byte parameter was introduced in xmcd version 3.1.
   
   If you still can't get it to work, then it's likely that your drive simply does not implement these features. You should set the volumeControlSupport, balanceControlSupport or channelRouteSupport parameters to False as appropriate.
   
   For the volume control, you may instead use the CD input and master level controls on your sound card if you're using one. You must run a sound mixer utility to do that. See xmmix for Linux and other Open Sound System compliant platforms.
   
   
4. The "Previous index" and "Next Index" buttons don't work. They either have no effect or causes error messages:
   
   SCSI command error on /dev/rcd0:
   Opcode=0x48 Status=0x1 Msg=0x0 ...
   Solution:
   
   This feature of xmcd allows you to skip between indices within a track. The CD you are playing must have indices on it. Such CDs are not very common.
   
   Check that the playTISupport parameter to see if it is set to True. If not, change it, restart xmcd and test.
   If your CD does not have indices, and you attempt to change the index, you may get an error message. Some drives will skip to the previous or next track instead, or stop.
   
   If you get an error message and you are certain that the CD has indices, then it's likely that your drive does not support the appropriate command to skip indices. You should set the playTISupport parameter to False.
   
   The "Previous index" and "Next Index" buttons are not supported on many platforms when running in one of the CDDA playback modes.
   
   
5. The buttons to select one or all of the CDDA playback modes are "greyed" out.
   
   Solution:
   
   
   • The cddaMethod, cddaReadMethod or cddaWriteMethod parameters may be misconfigured.
   • Your copy of xmcd/cda may be compiled with the support for this method disabled. See the INSTALL and RELNOTES files.
   • Your platform may not support the CDDA feature.
   See also the comments in the device configuration file for details.
   
   
6. Some of the CDDA output file formats in the selection menu are "greyed" out.
   
   Solution:
   
   
   • If the greyed out formats are MP3, AAC or MP4, you need to install the lame(1) and faac(1) encoder software, and have these program executables accessible in your PATH environment. If these encoder programs are installed and it doesn't correct the problem, then your copy of xmcd/cda was compiled without -DHAS_LAME and/or -DHAS_FAAC. See the INSTALL file for details.
   • If the greyed out formats are Ogg Vorbis or FLAC, then your copy of xmcd was not compiled with -DHAS_VORBIS and/or -DHAS_FLAC. See the INSTALL file for details.
   
   Note: The MP3 and Ogg Vorbis formats were introduced in xmcd 3.2.0, and the AAC, MP4 and FLAC formats were introduced in xmcd 3.3.0.
   
   
7. The CDDA playback modes do not work.
   
   Solution:
   
   Make sure your CD drive is capable of performing CDDA (CD digital audio) read operations. Not all drives support this feature, especially older drives.
   
   On those drives that do support CDDA, there was not a standard SCSI command set for it until the advent of the ANSI MMC (SCSI Multi-media Commands) standard in the late 1990s. Prior to that, each vendor created their own commands or overloaded an existing command for this capability. These are the popular CDDA command schemes in use:
   
   
   • MMC standard "Read CD" command
   • SCSI standard "Read" command (originally for reading data CDs)
   • NEC vendor unique "Read CD-DA"
   • Sony vendor unique "Read CD-DA"
   
   
   Your drive may support one or more of these schemes. The cddaScsiReadCommand parameter is used to select which scheme xmcd should use to perform CDDA transfers. You may try each of these to see if any of these commands work.
   
   Some drives require that a Mode Select SCSI command be sent to the drive to enable CDDA mode, prior to sending the aforementioned read commands. The Mode Select command sets the sector size to 2352 bytes per sector, which is the raw sector size appropriate for CDDA transfers. The cddaScsiModeSelect parameter configures whether such a Mode Select command should be sent. Additionally, some drives require a special "density code" to be set in the Mode Select command. In particular, Toshiba drives require a density code of 130 in order to enable CDDA mode. This code is configured by the cddaScsiDensity parameter, and is only used when cddaScsiModeSelect is also set to True.
   
   
8. The CDDA modes appear to work, but white noise is produced rather than music.
   
   Solution:
   
   Most CD drives produce CDDA audio data stream in "little endian" byte order. However some drives produce "big endian" data. If you have such a drive, change the setting of the cddaDataBigEndian parameter and restart xmcd. This should fix the problem.
   
   
9. The CDDA modes work when jitter correction is turned off, but fails when jitter correction is enabled.
   
   Solution:
   
   Try increasing the cddaReadChunkBlocks parameter. This parameter should normally be set no lower than 4. The upper limit of this parameter is OS dependent. Increasing this parameter will also generally improve read performance, but if you set it beyond the maximum allowed by the OS, the CDDA reads may fail.
   
   The CDDA transfer performance of some drives may simply be too slow. On those drives, the only solution is to turn off jitter correction.
   
   
10. Other Anomalies
    
    In rare cases, some drives that may exhibit other problems. You may want to try changing one of more of the following parameters to see if you can get xmcd to work better:
    
    
    • playMSFSupport
    • play10Support
    • play12Support
    • playTISupport
    • caddyLockSupport
    • loadSupport
    • ejectSupport
    • pauseResumeSupport
    • strictPauseResume *
    • playPausePlay *
    • noTURWhenPlaying
    • tocLBA **
    • subchannelLBA **
    • driveBlockSize **
    • cdTextDisable ***
    • mcnDisable ****
    • isrcDisable ****
    
    
    Read the comments in the configuraion file about what these parameters affect.

Non-SCSI Drives

Non-SCSI drives are supported by the CD-ROM driver in your kernel, The driver dictates the feature set supported and its compatibility with specific drives. The only parameters that may have an effect are:

• playMSFSupport
• playTISupport
• spinUpInterval
• volumeControlSupport
• balanceControlSupport
• channelRouteSupport
• caddyLockSupport
• loadSupport
• ejectSupport
• pauseResumeSupport
• strictPauseResume *
• playPausePlay *

Read the comments in the configuraion file about what these parameters affect.

All Drives

If the REW and FF scan-search functionality does not work well, try adjusting the searchSkipBlocks and searchPauseInterval parameters to see if this may help the behavior. It may be better to use the "Track Warp" slider in the xmcd keypad sub-window instead, especially in the CDDA playback mode.

*	These parameters were introduced in xmcd 2.5.
**	These parameters were introduced in xmcd 2.6.
***	These parameters were introduced in xmcd 3.2.0.
****	These parameters were introduced in xmcd 3.3.0.
	Most CDDA-related parameters were introduced in xmcd 3.1.

Configuration Schemes and Philosophy

Most other CD player software do not require any configuration, and simply rely on the OS CD-ROM driver's ioctl code to control the drive. Xmcd can operate in this mode on many platforms, and in fact uses this method for non-SCSI drives. This often restricts xmcd from extracting the full capabilities of the drive. Hence, for SCSI drives (and for those platforms where SATA and IDE/ATAPI drives are handled via SCSI-emulation), xmcd uses the SCSI pass-through mechanism to deliver commands to the drive, in effect becoming a user-mode device driver. Since drives vary in capabilities and SCSI command support, it is necessary for xmcd to determine these drive-specific nuances in order to make the drives operate correctly and to their full capability.

Some players hard-code these configurations in the software. The vendor and model names (as returned by the SCSI "Inquiry" command) are then used as a key to determine the mode of operation. This method has the obvious disadvantage that code modification and recompilation needed in order to support new and different drives.

Some players attempt to perform "auto-probing" of the drive. Differing commands are sent to the drive to see if they succeed, and an internal capabilities table is then established. While this method has the benefit that code changes are not usually needed to support new drives, it has the risk of causing the drive to misbehave or lock-up, as some drives do not take unsupported commands gracefully.

Xmcd uses an external configuration file to set up a capabilities list. The config.sh script uses a directory full of support tables (one file for each CD drive manufacturer) so that the user needs only to select the manufacturer and model of the drive from interactive configuration menus, and the configuration file will be filled in with the appropriate capabilities. For new drives or drives that do not appear in the config.sh menus, this guide provides help on getting the drive to work by manually editing the configuration file. There is no auto-probing of the drive each time xmcd is run. The configuration file is external, so no code modifications or recompilation is needed to adapt xmcd to new and different drives.

Many users would prefer to have the software work without any configuration. However, given the above facts it becomes apparent that the xmcd way of drive configuration is the best method to make use of the full capabilities of the drive. Fortunately, xmcd drive configuration only needs to be done once after installation (or after drive replacement with a different brand/model), so the inconvenience is minimal.