CDA(1)                     OpenBSD Reference Manual                     CDA(1)



NAME
       cda - Compact disc digital audio player utility


SYNOPSIS
       cda [-dev device] [-batch] [-remote | -noremote] [-debug] command


DESCRIPTION
       Cda is a program that allows the use of the CD-ROM or CD-R drive as a
       full-featured stereo compact-disc player 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.  Multi-
       disc changers are also supported.

       A CD database feature allows the CD artist/title and track titles, and
       other associated general purpose text to be displayed 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.  No
       capability is provided to update the CD database via cda.  You must use
       the X-based xmcd(1) utility to add or modify CD database entries.

       On systems with more than one CD-ROM or CD-R 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-
       ROM drives available.


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

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

       -remote, -noremote
              Forces the cda client to enable or disable remote CDDB server
              access.  If this option is not specified, then the default is
              configured via the cddbRemoteDisable parameter in the common.cfg
              file.

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


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-ROM 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 | 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.  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#]
              If no argument is specified, this command displays the current
              audio volume setting.  If a value is used, then the audio volume
              level is set to the specified value.  The valid range is 0 to
              100.

       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 from the CD database associated with the current
              disc is also shown, if available.

              If an exact CD database match is not found, but the CD database
              server provides a list of inexact 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 the disc extended information text associated with the
              current CD, if available from the CD database.  If the CD is
              currently playing, then the track extended information
              associated with the playing track is also displayed.  If a track
              number is used in the argument, then the track extended
              information text of the specified track is shown instead.

       on-load [autolock | noautolock | none | spindown | autoplay]
              Display, 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.  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.

       device Displays the CD-ROM and device information.

       version
              Displays the cda version and copyright information.

       debug [on | off]
              Show, set or unset the debug mode.  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.

       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-ROM 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-ROM 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-ROM 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 track extended information.  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-ROM 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-ROM 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 CD Database feature of xmcd is supported by cda, which allows you
       to display the disc artists/title, track titles, and extended
       information about the CD or tracks via the toc or extinfo commands of
       cda.  In visual mode, this information is displayed automatically if
       available.  You cannot update the CD database via cda.  Xmcd must be
       used for that purpose.


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

       XMCD_LIBDIR
              This parameter which specifies the directory path under which
              cda's configuration files and CD database files are located.  On
              modern systems this 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.  See xmcd(1) for details.


NOTES
       Not all CD-ROM drives support all features that appear on 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.


FILES
       $HOME/.xmcdcfg/*
       /etc/xmcd/common.cfg
       /etc/xmcd/device.cfg
       /etc/xmcd/*
       /usr/local/sbin/xmcdconfig
       /usr/local/share/doc/xmcd/*
       /usr/local/share/xmcd/help/*
       /usr/local/share/xmcd/tbl/*
       /var/db/xmcd/cddb/*
       /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
       xmcd(1), cddbcmd(1), wm2xmcd(1), X(1),
       Xmcd's README and INSTALL files
       Xmcd web site: http://metalab.unc.edu/tkan/xmcd/
       CDDB web site: http://www.cddb.com/


AUTHOR
       Ti Kan (ti@amb.org)
       AMB Research Laboratories, Sunnyvale, CA, U.S.A.

       Cda also contains code contributed by several dedicated individuals.
       See the README file in the cda distribution for information.

       Comments, suggestions, and bug reports are always welcome.



v2.6                            18 January 2000                         CDA(1)
