Table of Contents

Name

cda - Compact disc digital audio player utility

Synopsis

cda [-dev device] [-outport mask#] [-batch] [-online | -offline] [-debug level#] command

Description

Cda is a program that allows the use of the CD-ROM, CD-R, CD-RW or DVD drive as a full-featured stereo compact-disc player and "ripper" from the shell command line. It can be used interactively in line mode or visual (screen) mode, or as a script-driven utility. This is a companion utility to xmcd, a Motif-based CD audio player application for the X window system. Cda uses the same configuration and support files as xmcd.

Most of the features found on "real" CD players are available in cda, such as shuffle and repeat, and track programming functions.

CDDA (CD digital audio) data extraction, playback, save-to-file, and pipe-to-program are supported on many platforms. For data extraction to file or pipe, cda can generate the data in MP3 (MPEG layer 3), OggVorbis, WAV, AU, AIFF, AIFF-C and raw headerless formats. Simultaneous extraction to file/pipe and real-time playback is possible on high performance computers.

Multi-disc changers are also supported. You can select to play only a single disc or auto-play all discs in normal or reverse order.

The Gracenote CDDB(R) Music Recognition Service(sm) feature is supported by cda, which allows the CD artist/title and track titles, and other information associated with the loaded CD to be displayed. For CDDA extraction to MP3 and OggVorbis formats, cda can auto-fill the CD information tags embedded in these files.

This release of cda supports the enhanced Gracenote CDDB2(R) service on a number of platforms, and offers much richer features and content than the "classic" CDDB. Moreover, CDDB2-supplied information is now in UTF-8 data format, providing full localization support. See "LOCALIZATION" below.

In addition to CDDB, this release of cda supports reading CD-TEXT data from the disc for the disc/track artist and title information.

No capability is provided to add, modify or submit CDDB entries in cda. You must use the X-based xmcd(1) utility (or another CDDB-enabled application with the appropriate features) for that purpose.

On systems with more than one CD drive, multiple invocations of cda can be used to operate each drive independently.

Cda is designed to be easy to use, with particular care taken to make all output easily parsable by other programs.

The internal architecture of cda is designed to be easily portable to many UNIX operating system variants, and adaptable to the myriad of CD drives available.

Options

Cda supports the following options:

-dev device
Specifies the path name to the raw CD 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).
-outport mask#
Specifies the audio output port for CDDA real-time playback mode. The mask specifies the output port(s) desired:


1       Internal speaker
2       Headphone
4       Line-out

You may add the values together to enable multiple output ports (i.e., A value of 3 turns on both Internal Speaker and Headphones). When the mask is set to 0, the port setting is unmodified, and an external audio control utility may be used to change the settings. Note that this option may be meaningful only on some platforms, and only certain ports may be available on a particular architecture. See the PLATFORM file for details.

-batch
Signifies that cda should run in batch mode. This suppresses all interaction with the user (i.e., will not prompt the user to type anything). Batch mode is not meaningful in visual mode.
-online, -offline
Forces the cda client to enable or disable Internet access. If this option is not specified, then the default is configured via the internetOffline parameter in the common.cfg file. In offline mode, CDDB lookup will only be done from the local cache.
-debug level#
Causes verbose debugging diagnostics to be displayed on stderr. Note that if you are running in visual mode, the stderr output should be redirected to a file, or the debug information will corrupt the screen. The level specifies the type of debugging messages desired:


1    General debugging
2    Device I/O debugging
4    CD information debugging
32    Sound DSP and output file/pipe debugging

You may add the values together to enable multiple debugging types (i.e., A value of 3 turns on both General and Device I/O debugging).

Commands

Cda supports the following commands:

on
Start the cda daemon.
off
Terminate the cda daemon.
disc <load | eject | prev | next | disc#>
Load or eject the CD, or change discs on a multi-disc changer.
lock <on | off>
Enable/disable the CD disc lock. When locked, the CD cannot be ejected using the CD drive front-panel eject button.
play [track# [mm:ss]]
Start playback. If the track# is used, the playback starts from the specified track. The optional mm:ss argument specifies the minutes and seconds offset into the track from where to start playback.
pause
Pauses the playback. Use cda play to resume playback.
stop
Stop the plaback.
track <prev | next>
Proceed to the previous or the next track. This command is only valid when playback is already in progress.
index <prev | next>
Proceed to the previous or the next index. This command is only valid when playback is already in progress.
program [clear | save | track# ...]
If no argument is specified, this command displays the current program play sequence, if any. The clear argument will cause the current program to be cleared. The save argument will save the current program, so that a future load of the same CD will automatically get the program sequence. To define a new program, specify a list of track numbers separated by spaces. To start program play, use the play command. You cannot define a new program while shuffle mode is enabled.
shuffle <on | off>
Enable/disable shuffle play mode. When shuffle is enabled, cda will play the CD tracks in a random order. You can use this command only when audio playback is not in progress. Also, you must clear any program sequence before enabling shuffle.
repeat <on | off>
Enable/disable the repeat mode.
volume [value# | linear | square | invsqr ]
If no argument is specified, this command displays the current audio volume and taper setting. If a value is used, then the audio volume level is set to the specified value. The valid range is 0 to 100. If one of linear, square or invsqr is specified, then the volume control taper is set to the specified curve.
balance [value#]
If no argument is specified, this command displays the current balance control setting. If a value is used, then the balance is set to the specified value. The valid range is 0 to 100, where 0 is full left, 50 is center and 100 is full right.
route [stereo | reverse | mono-l | mono-r | mono | value#]
If no argument is specified, this command displays the current channel routing setting. Otherwise, to set the routing, 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
status [cont [secs#]]
Display the current disc status, disc number, track number, index number, time, modes, and repeat count. If the cont argument is specified, then the display will run continuously until the user types the interrupt character (typically Delete or Ctrl-C). The optional secs sub-argument is the display update time interval. The default is 1 second.
toc [offsets]
Display the CD Table of Contents. The disc artist/title and track titles associated with the current disc, queried from CDDB, is also shown. If the disc has associated notes or credits, an asterisk (*) is displayed after the genre description. Similarly, if a track has associated notes or credits, an asterisk is displayed after the track title.

If the CDDB server cannot determine an exact match for your CD, but found a list of possible matches, then the user will be prompted to select from that list. If batch mode is active (i.e., the -batch option is used), then no such prompt will occur.

If the offsets argument is used, then the track times are the absolute offsets from the start of the CD. Otherwise, the times shown are the track lengths.

extinfo [track#]
Display extended information associated with the current CD, if available from CDDB. If the CD is currently playing, then extended information associated with the playing track is also displayed. If a track number is used in the argument, then the extended information of the specified track is shown instead.
notes [track#]
Display disc notes information text associated with the current CD, if available from CDDB. If the CD is currently playing, then the track notes information associated with the playing track is also displayed. If a track number is used in the argument, then the track notes information text of the specified track is shown instead.
on-load [none | spindown | autoplay | autolock | noautolock]
Display, enable or disable options when a CD is loaded. 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 autolock option causes the caddy or disc tray to be automatically locked. The none, spindown and autoplay options are mutually-exclusive. If no argument is used, then the current settings are displayed.
on-exit [none | autostop | autoeject]
Display, enable or disable options when the cda daemon exits. The autostop option will cause cda to stop playback, and the autoeject option will cause cda to eject the CD. Use none to cancel these options. If no argument is used, then te current settings are displayed.
on-done [autoeject | noautoeject | autoexit | noautoexit]
Display, enable or disable options when cda is done with playback. The autoeject option causes the cda daemon to eject the CD. The autoexit option will cause the cda daemon to exit. If no argument is used, then the current settings are displayed.
on-eject [autoexit | noautoexit]
Display, enable or disable options when cda ejects a CD. The autoexit option will cause the cda daemon to exit after ejecting the CD. If no argument is used, then the current settings are displayed.
changer [multiplay | nomultiplay | reverse | noreverse]
Display, enable or disable multi-disc changer options. The multiplay option specifies that cda plays all discs in sequence. The nomultiplay option will cause cda to stop after the current disc is done. The reverse option implies multiplay, except that the disc order is reversed. If no argument is used, then the current settings are displayed.
mode [standard | cdda-play | cdda-save | cdda-pipe]
Selects the playback mode. If no argument is used, then the current setting is displayed. See "PLAYBACK MODES" below for details about the modes.
jittercorr [on | off]
Enables or disables CDDA jitter correction. If no argument is used, then the current setting is displayed.
trackfile [on | off]
For CDDA-save mode, specifies whether a separate file should be created for each CD track. If no argument is used, then the current setting is displayed.
subst [on | off]
For CDDA-save mode, specifies whether space and tab characters in the output file path name should be substituted with underscores ('_'). This makes the files easier to manipulate while using the UNIX command shell. If no argument is used, then the current setting is displayed.
filefmt [raw | au | wav | aiff | aiff-c | mp3 | ogg]
Specifies the output audio file format if running in cdda-save or cdda-pipe modes.
outfile [template]
Specifies the output audio file path name if running in cdda-save mode (default is audio.ext, where ext is dependent upon the file format selected). If no argument is used, then the currently defined template is displayed. See the xmcd help file on the output file path template for information about the special tokens that could be used in the template.
pipeprog [path [arg ...]]
Specifies the external program to which the audio stream will be piped to when running in cdda-pipe mode. If no argument is used, then the currently defined program is displayed.
compress [<cbr | abr> [bitrate#] | <vbr | vbr2> [qual#]]
If the output file format is mp3 or ogg, this command selects the file compression scheme to be used. The cbr method indicates "constant bitrate", the abr method denotes "average bitrate", and the vbr modes indicate "variable bitrate". There are two variable bitrate algorithms to choose from. Vbr is a time-tested algorithm, whereas the vbr2 mode is a newer, faster algorithm that also produces great results. For the cbr and abr modes, an optional bitrate (in kb/s) sub-argument can be specified. The supported bitrates are a discrete set of numbers from 32 to 320. A value of 0 can also be used to indicate the use of an internal default. For the vbr modes, an optional quality factor (from 1 to 10) sub-argument can be used. Lower bitrates and quality factor values yield smaller files whereas higher numbers produce higher audio quality. If no argument is used, then the current settings are displayed.
Note: For the ogg format, cbr and abr selects the same internal algorithm and the two vbr modes are synonymous.
min-brate [bitrate#]
In average bitrate and variable bitrate modes, this commands lets you specify a low bitrate limit. The encoder will not drop below this limit while dynamically changing the bitrate. A value of 0 can be specified to indicate the use of an internal default. If no argument is used, then the current setting is displayed.
max-brate [bitrate#]
In average bitrate and variable bitrate modes, this commands lets you specify a high bitrate limit. The encoder will not go above this limit while dynamically changing the bitrate. A value of 0 can be specified to indicate the use of an internal default. If no argument is used, then the current setting is displayed.
mp3 [stereo | j-stereo | force-ms | mono | algo#>]fR
If the output file format is mp3, this command selects the stereo mode and encoding noise-shaping/psychoacoustics algorithm. The algorithm is a number from 1 to 10. Lower numbers gives faster encoding whereas higher numbers produce higher audio quality. If no argument is used, then the current settings are displayed.
lowpass [off | auto | freq# [width#]]
For encoding to mp3 files, this allows a lowpass filter to be added. The off setting means no filter, the auto setting causes the encoder to determine whether a filter should be added and its parameters. Specifying a frequency (and optionally, a width) will enable the filter in manual mode. The frequency and width are both in Hz. The valid frequency range is from 16 to 50000 Hz. If no argument is used, then the current settings are displayed.
highpass [off | auto | freq# [width#]]
For encoding to mp3 files, this allows a highpass filter to be added. The off setting means no filter, the auto setting causes the encoder to determine whether a filter should be added and its parameters. Specifying a frequency (and optionally, a width) will enable the filter in manual mode. The frequency and width are both in Hz. The valid frequency range is from 500 to 50000 Hz. The lower limit is imposed by the polyphase filter implementation in the MP3 encoder. If no argument is used, then the current settings are displayed.
flags [C|c][O|o][N|n][E|e][I|i]
This allows you to specify some mp3 header and frame flags. The letter c denotes the "copyright" flag, the letter o denotes the "original" flag, the letter n denotes the "no res" (no bit reservoir) flag, the letter e denotes the addition of a 2-byte checksum to each frame for error correction, and the letter i indicates strict ISO compatibility. The use of a upper-case letter turns on the flag, and lower-case turns off the flag. Multiple flags may be specified together. If no argument is used, then the current settings are displayed.
tag [off | v1 | v2 | both]
This command specifies whether an ID3tag should be added to an mp3 output file (and which version of the ID3 tag should be added). For ogg files, a comment tag is added if the argument is not set to off. If no argument is used, then the current setting is displayed.
Note: A ID3v2 tag will not be added to the cdda-pipe stream regardless of the setting of this command.
device
Displays the CD drive and device information.
version
Displays the cda version and copyright information.
cddbreg
Invoke dialog to register with Gracenote in order to access the CDDB2 service. This command can be used to do the initial registration, as well as to change or update user registration information. This function is not available with the "classic" CDDB service.
cddbhint
Ask Gracenote to send the password hint via e-mail. This is used in case you forget the CDDB user password. The password and password hint are both initially set via the cddbreg command. This function is not available with the "classic" CDDB service.
debug [level#]
Show, or set the debug level. If set, verbose debugging diagnostics will be printed on stderr of the terminal that the cda daemon is started from. If this is the same terminal that is running cda in visual mode, the debug information will corrupt the screen. See the description of the -debug option above for supported debug levels.
visual
Enter an interactive, screen-oriented visual mode. All other cda commands can also be invoked within this mode.

Device Configuration

See xmcd(1) for a description of the device configuration requirements.

WARNING: If cda is not correctly configured, you may cause cda to deliver commands that are not supported by your CD drive. Under some environments this may lead to system hang or crash.

Using Cda

Start the cda daemon with the cda on command (or the F1 (o) function in visual mode). This reserves the CD device and initializes the program for further commands. All other cda functions will not work unless the cda daemon is running. The other cda commands should be self explanatory.

The off command (or the F1 (o) function in visual mode) can be used to terminate the cda daemon and release the CD drive for use by other software.

Visual Mode

If the cda visual command is used, it enters a screen-oriented visual mode. In this mode, the status and other information available is continuously displayed and updated on the screen, and virtually all functions are available via a single key stroke.

A minimum screen size of 80 columns by 24 rows is recommended for the visual mode.

Visual mode uses the curses screen library to control the screen. It is essential that the TERM environment variable reflect the current terminal type, which ideally should have 8 (or more) function keys. Since function key definitions in terminfo descriptions are often unreliable, alphabetic key alternatives are also available.

The screen is divided into two windows: an information window and a status window. According to context, the information window displays a help screen, device and version information, disc information and table of contents, or extended information about the track. This window is scrollable if it overflows its allotted screen area. The status window consists of the last few lines of the screen, enclosed in a box. The first line contains the program list, or track number and offset together with volume, balance and stereo/mono information. The remaining lines contain the function keys (with their alphabetic synonymns) and the functions they invoke. These functions are highlighted when they are on, making it easy to see the current state.

Screen annotation and online help make operation self explanatory, but for reference, a list of commands follows. Alphabetic key alternatives to function keys are given in parenthesis.

?
Display help screen. Dismiss this screen by pressing the space bar.
F1 (o)
On/Off. Start or stop the cda daemon.
F2 (j)
Load or eject the CD.
F3 (p)
Play, pause or unpause.
F4 (s)
Stop.
F5 (k)
Enable/disable the CD caddy lock. When locked, the CD cannot be ejected using the CD drive front-panel eject button.
F6 (u)
Shuffle/Program. Pressing this key cycles through three states: normal, shuffle and program. In shuffle mode, the tracks of the CD will be played in random order. On entering program mode, cda will prompt for a space or comma separated list of track numbers, representing a desired playing order. The list should be terminated by carriage return. An empty list returns cda to normal mode. Shuffle and program mode cannot be engaged unless a CD is loaded but not playing or paused.
F7 (e)
Enable/disable repeat mode.
F8 (q)
Terminate the visual mode. If the cda daemon is running, a reminder of the fact is given and it is allowed to continue. The CD drive will continue operating in the same state. Cda may be invoked again in either visual or line mode when required.
D/d
Change to the previous/next disc on multi-disc changes.
Cursor left/right (C/c)
Previous/next track. This is only valid if playback is already in progress.
</>
Proceed to the previous/next index mark. This is only valid if playback is already in progress.
Cursor up/down (^/v)
Scroll the information portion of the screen up or down. It may be scrolled up only until the last line is on the top line of the screen, and may not be scrolled down beyond the initial position. The initial scroll position is restored when different information is displayed, (e.g., when switching to or from the help information).
+/-
Increase or decrease volume by 5%.
l/r
Move balance 5% to left or right.
Tab
Successive depressions of this key change the mode from stereo to mono, mono right, mono left, reverse stereo, and back to normal stereo.
<n> [mins secs]
Proceed to track n at mins minutes and secs seconds from the start. If mins secs is not given, start at the beginning of track n.
^l/^r
Control-l or control-r repaints the screen. This is useful if the screen has been corrupted (e.g., by operator messages sent by the wall(1M) command).

CD Database

The Gracenote CDDB(R) Music Recognition Service(sm) feature is supported by cda, which allows you to display the disc artists/title, track titles, and other information about the CD or tracks via the toc, extinfo and notes commands of cda. In visual mode, this information is displayed automatically if available. You cannot add, modify or submit CDDB information via cda. For more details about CDDB, see xmcd(1) and the CDDB file that comes with this release.

This release of cda also supports reading the CD-TEXT data from the disc for CD information. Only some recent CDs are produced with CD-TEXT data and this data can only be read on CD drives with CD-TEXT capability.

The priority of the CD information schemes (CDDB, CD-TEXT or local CD database files) is controlled via the cdinfoPath parameter in the common.cfg file.

Playback Modes

This release supports the following user-selectable playback modes (via the cda mode command):

standard

When playing an audio CD, the audio output is the analog "line out" connection on the back of your CD drive. There should be an audio cable connecting this output to your computer audio hardware CD input (or to an externally amplfied speaker or stereo system). The audio output is also available at the CD drive's front panel headphone connection, if so equipped. The cda volume command affect the CD drive's built-in volume control, if the drive has such controls. This is the mode that previous releases (cda version 1.x through 3.0) supported.

cdda-play

When playing a CD in this mode, cda extracts the CD digital audio data off the CD drive over the data cable (e.g., SCSI or ATAPI/IDE). Then, it sends the data to the DSP (digital signal processor) device in your computer's audio hardware for real-time playback. The audio is typically heard through the computer's built-in speakers. No signal is produced at the line-out or headphone connections of the CD drive. The cda volume command affects the computer's DSP device.

cdda-save

When playing a CD in this mode, cda extracts the CD digital audio data off the CD drive over the data cable (e.g., SCSI or ATAPI/IDE). Then, it writes the data into a file of your choosing. The cda volume command does not affect the data written to the output file. The output file format can be selected to be one of the following:


Format Ext   Description
------ ----- ---------------------------------------
RAW    .raw  Little-endian, 16 bit, 44.1 kHz, stereo
AU     .au   Big-endian, 16 bit, 44.1 kHz, stereo
WAV    .wav  Little-endian, 16 bit, 44.1 kHz, stereo
AIFF   .aiff Big-endian, 16 bit, 44.1 kHz, stereo
AIFF-C .aifc Big-endian, 16 bit, 44.1 kHz, stereo
MP3    .mp3  Compressed
OGG    .ogg  Compressed

The file can be played later using an appropriate playback utility, or converted to another format. This mode will typically run faster than real-time with the non-compressed formats. With the compressed formats, it depends on the CPU performance of your system.

cdda-pipe

When playing a CD in this mode, cda extracts the CD digital audio data off the CD drive over the data cable (e.g., SCSI or ATAPI/IDE). Then, it pipes the data stream to an external program that you specify. The output format is selected as in the CDDA save to file mode. This mode can be used with an external audio player, encoder, or other digital audio manipulation program. The external program must be capable of accepting audio data on its standard input, in one of the formats listed above.

More than one of the three CDDA modes can be selected at the same time. For example, if both the cdda-play and the cdda-save modes are enabled, the two functions will be performed simultaneously. Note that on most systems, only one program can access the system's DSP at a time, therefore you will likely not be able to select cdda-play and cdda-pipe at the same time, where the external program is itself an audio player.

NOTE: The CDDA (CD digital audio) modes will function only on CD drives that provides this capability, and only on some OS and hardware platforms. See the RELNOTES file for details about platform support and other CDDA related notes.

Localization

The "classic" CDDB service supplies data in the ISO Latin-1 format only, multi-byte characters are not supported.

The CDDB2 service supplies data is in UTF-8 data format, which is identical to ISO Latin-1 for single-byte characters. Multi-byte character sets are also supported. On platforms that provides the iconv(3) function, cda will attempt to convert UTF-8 strings to the default character set as specified by the LANG environment variable. This conversion will occur only if the system's list of locales also support UTF-8. Otherwise cda will display the UTF-8 strings without modification.

If you desire to view CDDB data in languages other than English or the ISO Latin-1 European character set, you may need to configure your display terminal to display the appropriate fonts (if the terminal has such capabilities). Terminal font configuration is device-dependent, OS-dependent and beyond the scope of this document. Please see your display terminal's documentation (or in the case of a computer graphics console, the operating system's console font related documentation for information.

Non-CDDB text (such as headings, labels and error messages) are not localized in cda.

Notes

Not all platforms and CD drives support all the features of cda. For example, some drives do not support a software-driven volume control. On these drives the cda volume and balance commands may have no effect, or may simply change the volume between full mute and maximum. Similarly, the lock, disc, index, and route commands of cda may not have any effect on drives that do not support the appropriate functionality.

The lame(1) MP3 encoder program must be installed on your system in order for cda to perform CD ripping to .mp3 format files.

Your copy of the cda executable must be compiled and linked with the OggVorbis encoder libraries in order to perform CD ripping to .ogg format files.

Environment Variables

The LANG environment variable sets the default character set. See "LOCALIZATION" above.

The LAME_PATH environment variable may be used to specify the path to the lame(1) MP3 encoder program.

The AUDIODEV environment variable may be used to specify an alternate audio device when running cda in the cdda-play mode. The default audio device is write method dependent as follows:

AIX write method:    /dev/paud0/1    (PCI audio)
AIX write method:    /dev/baud0/1    (MCA audio)
ALSA write method:    plughw:0,0
HP-UX write method:    /dev/audio
Linux/OSS write method:    /dev/dsp
OSF1 write method:    0
Solaris write method:    /dev/audio

In addition, with the OSS and ALSA write methods, the MIXERDEV environment variable may be used to specify the PCM mixer channel device. The default is /dev/mixer for OSS, and default for ALSA.

Files

$HOME/.cddb2/*
$HOME/.xmcdcfg/*
XMCDLIB/cdinfo/*
XMCDLIB/config/config.sh
XMCDLIB/config/common.cfg
XMCDLIB/config/device.cfg
XMCDLIB/config/.tbl/*
XMCDLIB/config/*
XMCDLIB/help/*
BINDIR/cda
MANDIR/cda.1
/tmp/.cdaudio/*

Related Web Sites

Xmcd/cda web site: http://www.amb.org/xmcd/
Gracenote web site: http://www.cddb.com/
Xmmix web site: http://www.amb.org/xmmix/
LAME MP3 encoder: http://www.mp3dev.org/
OggVorbis: http://www.xiph.org/ogg/vorbis/
Sox audio format conversion utility: http://www.spies.com/Sox/

See Also

xmcd(1) , xmmix(1) , X(1) , lame(1) , sox(1)

Xmcd's README and INSTALL files

Author

Ti Kan (xmcd@amb.org)
AMB Laboratories, Sunnyvale, CA, U.S.A.
Cda also contains code contributed by several dedicated individuals. See the ACKS file in the cda distribution for information.
Comments, suggestions, and bug reports are always welcome.


Table of Contents