This file documents the Cdcd program, version 0.6.5.

Copyright 2001 Fabrice Bauzac.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

This document describes the Cdcd program: the Command-Driven CD player.

This document applies to version 0.6.5 of Cdcd.

     [file gpl.texinfo not included]

Introduction
************

The Cdcd program, or Command-Driven CD player, is a command-line audio CD player.

It permits you to control your CD drive(s) from any shell prompt, or from Cdcd's own Readline prompt with command and track completion.  It can retrieve the information about an audio CD's track names and artist(s) from any CDDB- or CDIndex-compatible database server.

Cdcd needs the Libcdaudio library.

The homepage for Cdcd and Libcdaudio is currently at http://libcdaudio.sourceforge.net/.

Cdcd was originally written by Antony Arcieri.  Fabrice Bauzac modified it and is the current maintainer.

Getting Started
***************

The Cdcd program works in two ways: either in the non-interactive interface from the command-line, or interactively, from the Cdcd prompt.

This chapter documents a subset of the non-interactive interface, to get started.

The general non-interactive syntax for cdcd is:

     cdcd COMMAND ARGUMENTS...

The play command
================

You can play the current track of an audio CD with this command:

     cdcd play

The current track is a variable contained into your CD drive; it is generally the first track (1).

To play a specific track, type

     cdcd play TRACKNUM

Replace TRACKNUM with the track number you want to play.  The CD drive will keep playing tracks until it reaches a non-audio track or the last track.

If you know a part of the title of the track you want to play, you can type

     cdcd play PART

For example, you may type cdcd play free to play the Free Software Song, sung by Richard Stallman.

Other useful commands
=====================

Other useful commands include:

stop
     Stop playing.

pause
resume
     Pause, resume a paused song.

toggle
     Toggle between pausing/resuming a song.

open
close
     Open, close the CD tray.

next
prev
     Play the next or previous track.

tracks
     Show information about the current CD.

Invocation
**********

Cdcd accepts options and/or commands as arguments.

     cdcd [OPTIONS...] [COMMAND [COMMAND PARAMETERS...]]

If no command is given, it starts the interactive prompt.

Command-line options
====================

Cdcd accepts three options.

-h
--help
     Print a summary of the command-line options and commands to Cdcd and exit.

-v
--version
     Print the version number of Cdcd and exit.

-d DEVICE
--device=DEVICE
     Use DEVICE as the device name.  The default is /dev/cdrom. See The device command, to change the device using a command.

General Commands
================

The commands described in this section can be used either from the command-line, like this:

     cdcd COMMAND [ARGUMENTS...]

or from Cdcd's root prompt.  See The Cdcd Prompt, for more info.

Playing
-------

  * The play command may be used to play a track.

          play [START-TRACK [START-TIME] [END-TRACK]]

     A track is either a track number, or a part of a track name (case-insensitive).  A time is in the MM:SS form, e.g. 3:12, :24, 1:.

  * You can stop the CD drive from playing, with the stop command.

  * The pause and resume commands can be used to temporarily pause the playing of a CD track, allowing the user to resume the play where it was paused, unlike stop.  The toggle command switches between pausing and playing the current song.

  * The rndplay command plays a random track.

Moving around
-------------

  * You can start playing the next or previous track with the next and prev commands.

  * The ff and rew commands let you change the playing position within the current track.

          ff [MM:SS]
          rew [MM:SS]

     For example, ff 3:12 will jump forward by 192 seconds; rew :12 will jump backward by 12 seconds.

     The default time to jump is 15 seconds; i.e. ff means ff :15.

Displaying Useful Information
-----------------------------

  * The status command gives bare-bones information about the status of the CD.

     For more information, use the info command below.

  * The info command displays statistics about the CD, such as the name, artist, track number, time, etc.

  * Cdcd will display the album, artist, track length and track titles with the tracks command.

     If a track line contains the > marker, it means it is the current track.

  * The ext command gives the extended information of the CD or a track.

          ext
          ext TRACKNAME
          ext TRACKNUM
          ext disc

Changing discs
--------------

  * You can open and close the disc tray with the open/eject and close commands.

  * The device command lets you change the device name that Cdcd controls (default /dev/cdrom).  See The --device option, for information about setting the device with a command-line option.

          device DEVICE

Multi-disc Drives
.................

If you own a drive that supports several discs (a cd changer), you can use the following commands to control it.

  * The slot command lets you choose which slot to activate.

          slot DISC-NUMBER

     where DISC-NUMBER is the number of the slot you want to activate.

  * The list command will display the entire contents of your changer.

Note: CD changers are not supported on all platforms.

Controlling the Drive's Volume
------------------------------

  * The setvol command can set the drive's volume.

     Drives can have from two to four channels.  The four channels are: front left (fl), front right(fr), back left (bl) and back right (br).  Two-channel drives only use the front channels. Each channel volume can be set to a value between 0 and 255 inclusive.

          setvol [VOLUME] [f=VOLUME] [b=VOLUME] [l=VOLUME]
                 [r=VOLUME] [fl=VOLUME] [fr=VOLUME]
                 [bl=VOLUME] [br=VOLUME]

  * The getvol command displays the volume settings.

Note: if you listen to your tracks through a mixer-capable device such as a sound card, it is best to leave the drive's volume settings to the default (usually 255), since the drive's mixer is basic and is less easily controlled.  The setvol and getvol commands are provided only for completeness.  Use /dev/mixer instead.

Other Commands
--------------

  * The refresh command looks up for the current CD's information in the cd databases online, and updates it.

  * You can control Cdcd's verbosity with the verbose command.  When verbosity is off, Cdcd will display only necessary information.

          verbose on
          verbose off

The Cdcd Prompt
***************

When you invoke Cdcd with no command on the command-line, for example cdcd, then you enter the interactive prompt.  The output looks like this:

     cdcd 0.5.6
     Copyright (C) 1998, 1999 Tony Arcieri.
     Copyright (C) 2001 Fabrice Bauzac.
     cdcd is free software, covered by the GNU General Public Licence, and
     you are welcome to change it and/or distribute copies of it under
     certain conditions.  There is absolutely no warranty for cdcd.  See the
     file COPYING for details.
     Using libcdaudio 0.99.5.
     Enter ? for help.
     cdcd>

The prompt, cdcd>, tells us that we are in the "root" directory of commands.  Here is a table of all the command directories in Cdcd:

(root)
     The main directory.  You can use all of the basic commands. See General Commands, for information about the basic commands.

sites
     From this directory, you can manipulate your list of cd database servers.

edit
     This directory is used to modify the contents of the current disc's database entry: artist, album, track names...

access
     The access commands are in this directory.  They permit you to change the online/offline setting, and the proxy configuration.

The Directories System
======================

The commands in Cdcd are organized in groups: general commands, commands related to edition of the CD info, etc.  Because these groups are nested, they are called directories.

The directories are root, edit, access, and sites.

The prompt tells you in which directory you are.  e.g. cdcd> means that you are in the root directory, whereas cdcd/access> means you are in the access directory.

You can change the current directory in two ways.

  * You can go into one subdirectory typing its name.  e.g. if you are in the root directory and want to go to the sites subdirectory, type sites.

  * You can go back up one directory typing ".."; e.g. if you are in the edit subdirectory and type "..", then you'll be in the root directory.

You can use the help command to list all of the available commands in the current directory.  ? is an alias for help.

You can display information about a particular command with the following syntax:

     help COMMAND

Then Cdcd will display the on-line help for the command COMMAND.

Miscellaneous Root Commands
===========================

Most of the root commands have been already described, in the case of non-interactive use; see General Commands, for more information. Some commands can be used specifically in interactive Cdcd:

  * ! is the generic shell call.  You can execute a shell from within Cdcd with this command: just type !.  You can execute any program by typing it and its arguments after the !; e.g. ! ls -l ~rms.

  * debug shows a number of debugging information.

  * quit lets you quit Cdcd.  exit is an alias.  You can type C-d (also known as ^D) too.

The Sites Directory
===================

The sites directory can be used to customize the list of CD database servers.

  * refresh [URL] updates the CDDB server list from the default server or from the specified URL.

  * display shows the current buffer list.

  * add LOCATION url=URL TYPE adds url URL with type TYPE (one of CDDB or CDI) at position number LOCATION in the list.

  * del LOCATION deletes the entry number LOCATION from the list.

  * move SOURCE DESTINATION moves the entry number SOURCE to position number DESTINATION.

The Edit Directory
==================

The edit directory is used to edit the information about a CD: the album name, artist, and track names.

  * name [NAME] is the command to get (if NAME is not supplied) or set (if it is) the disc name.

  * artist [ARTIST] is for the artist for the whole CD.

  * genre [GENRE] for the genre.

  * track TRACKNUM [TITLE] for the track number TRACKNUM's title.

  * With the submit command, you can submit your modifications to a cd database such as CDDB or CDIndex.

          submit [EMAIL]

     You have to specify an e-mail address.

The Access Directory
====================

The access directory permits the user to configure the access to the internet.

  * access displays the current access method.

  * remote sets the current access method to remote, i.e. Cdcd will try to connect to remote databases.

  * local sets the current access method to local, i.e. Cdcd will only access the database locally, and not attempt to reach the outside world.

  * proxy [URL | off] sets the current HTTP proxy to URL or turns proxying off.  Without argument, it shows the current status.

Reporting Bugs
**************

If you find a bug, please report it to noon@users.sourceforge.net.  Please give as many details as possible; you can try to explain a possible interpretation but please, report facts primarily.

Explain how to reproduce the bug if you can, as it often speeds up the localization of the bug.

Remember to supply the version number of Cdcd and Libcdaudio.