\input texinfo
@c %**start of header
@setfilename cdcd.info
@settitle Playing an Audio CD
@setchapternewpage odd
@c %**end of header

@set EDITION 1.0
@set VERSION 0.6.5
@set UPDATED 9 August 2001

@ifinfo
This file documents the Cdcd program, version @value{VERSION}.

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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
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.

@end ifinfo

@titlepage
@title The Cdcd Manual
@subtitle Edition @value{EDITION}, for Cdcd version @value{VERSION}
@subtitle @value{UPDATED}
@author by Fabrice Bauzac

@page
@vskip 0pt plus 1filll
Copyright @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.
@end titlepage

@dircategory Individual utilities
@direntry
* Cdcd: (cdcd).                 The Command-Driven CD Player
@end direntry

@node Top, Copying, , (dir)

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

This document applies to version @value{VERSION} of Cdcd.
@end ifinfo

@menu
* Copying::             How you can copy and share Cdcd.
* Introduction::        Introduction.
* Getting Started::     Getting started.
* Invocation::          Invoking Cdcd.
* The Cdcd Prompt::     The Cdcd prompt; all the commands.
* Bugs::                Reporting bugs.
* Concept Index::       Concept index.
@end menu

@node Copying, Introduction, Top, Top
@include gpl.texinfo

@node Introduction, Getting Started, Copying, Top
@chapter Introduction
@cindex 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 @acronym{CDDB}- or @acronym{CDIndex}-compatible
database server.

Cdcd needs the Libcdaudio library.

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

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

@node Getting Started, Invocation, Introduction, Top
@chapter Getting Started
@cindex 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 @command{cdcd} is:

@example
cdcd @var{command} @var{arguments...}
@end example

@section The @code{play} command
@cindex @code{play} command overview

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

@example
cdcd play
@end example

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

To play a specific track, type

@example
cdcd play @var{tracknum}
@end example

Replace @var{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

@example
cdcd play @var{part}
@end example

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

@section Other useful commands
@cindex overview of commands
@cindex commands, overview

Other useful commands include:

@table @samp
@item stop
Stop playing.
@item pause
@itemx resume
Pause, resume a paused song.
@item toggle
Toggle between pausing/resuming a song.
@item open
@itemx close
Open, close the CD tray.
@item next
@itemx prev
Play the next or previous track.
@item tracks
Show information about the current CD.
@end table

@node Invocation, The Cdcd Prompt, Getting Started, Top
@chapter Invocation
@cindex invocation
@cindex Cdcd invocation
@cindex invoking Cdcd
@cindex command-line interface
@cindex shell, invoking cdcd from the shell

Cdcd accepts options and/or commands as arguments.

@example
cdcd [@var{options...}] [@var{command} [@var{command parameters...}]]
@end example

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

@menu
* Command-line Options::  Classic @acronym{UNIX} options.
* General Commands::      Main commands.
@end menu

@node Command-line Options, General Commands, , Invocation
@section Command-line options
@cindex options

Cdcd accepts three options.

@table @samp
@item -h
@itemx --help
Print a summary of the command-line options and commands to Cdcd and
exit.

@item -v
@itemx --version
Print the version number of Cdcd and exit.

@cindex several drives, commandline option
@cindex setting the current drive
@cindex device, setting the
@item -d @var{device}
@itemx --device=@var{device}
Use @var{device} as the device name.  The default is @file{/dev/cdrom}.
@xref{Changing CDs, The @code{device} command}, to change the device
using a command.
@end table

@node General Commands, , Command-line Options, Invocation
@section General Commands
@cindex general commands
@cindex commands, general

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

@example
cdcd @var{command} [@var{arguments...}]
@end example

or from Cdcd's root prompt.  @xref{The Cdcd Prompt}, for more info.

@menu
* Playing::            Playing.
* Moving::             Moving around.
* Displaying::         Displaying useful information.
* Changing CDs::       Opening and closing the tray; managing multi-CD
                       drives.
* Volume Control::     Changing the drive's volume level.
* Other Commands::     Miscellaneous commands.
@end menu

@node Playing, Moving, , General Commands
@cindex Playing
@subsection Playing

@itemize @bullet

@item
@cindex @code{play}
The @command{play} command may be used to play a track.

@example
play [@var{start-track} [@var{start-time}] [@var{end-track}]]
@end example

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

@item
@cindex @code{stop}
You can stop the CD drive from playing, with the @code{stop} command.

@item
@cindex @code{pause}
@cindex @code{resume}
@cindex @code{toggle}
The @code{pause} and @code{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 @code{stop}.  The @code{toggle} command
switches between pausing and playing the current song.

@item
@cindex @code{rndplay}
The @code{rndplay} command plays a random track.

@end itemize

@node Moving, Displaying, Playing, General Commands
@cindex moving
@subsection Moving around

@itemize @bullet

@item
@cindex @code{next}
@cindex @code{prev}
You can start playing the next or previous track with the @code{next}
and @code{prev} commands.

@item
@cindex @code{ff}
@cindex fast forwarding
@cindex @code{rew}
@cindex rewinding
The @code{ff} and @code{rew} commands let you change the playing
position within the current track.

@example
ff [@var{mm}:@var{ss}]
rew [@var{mm}:@var{ss}]
@end example

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

The default time to jump is 15 seconds; i.e. @samp{ff} means @samp{ff
:15}.

@end itemize

@node Displaying, Changing CDs, Moving, General Commands
@cindex information, displaying
@cindex displaying useful information
@subsection Displaying Useful Information

@itemize @bullet

@item
@cindex @code{status}
The @code{status} command gives bare-bones information about the status
of the CD.

For more information, use the @code{info} command below.

@item
@cindex @code{info}
The @code{info} command displays statistics about the CD, such as the
name, artist, track number, time, etc.

@item
@cindex @code{tracks}
Cdcd will display the album, artist, track length and track titles with
the @code{tracks} command.

If a track line contains the @samp{>} marker, it means it is the current
track.

@item
@cindex @code{ext}
@cindex extended information, obtaining
The @code{ext} command gives the extended information of the CD or a
track.

@example
ext 
ext @var{trackname}
ext @var{tracknum}
ext disc
@end example

@end itemize

@node Changing CDs, Volume Control, Displaying, General Commands
@cindex changing discs
@cindex disc, changing
@subsection Changing discs

@itemize @bullet

@item
@cindex tray, controlling the
@cindex CD tray, controlling the
@cindex @code{open}
@cindex @code{close}
@cindex @code{eject}
You can open and close the disc tray with the @code{open}/@code{eject}
and @code{close} commands.

@item
@cindex several drives, command
@cindex modifying the current drive
@cindex device, changing the
The @code{device} command lets you change the device name that Cdcd
controls (default @file{/dev/cdrom}).  @xref{Command-line Options, The
@code{--device} option}, for information about setting the device with a
command-line option.

@example
device @var{device}
@end example

@end itemize

@cindex disc changer commands
@cindex changer, commands
@cindex multi-disc drive
@subsubsection Multi-disc Drives
If you own a drive that supports several discs (a cd changer), you can
use the following commands to control it.

@itemize @bullet

@item
@cindex @code{slot}
The @code{slot} command lets you choose which slot to activate.

@example
slot @var{disc-number}
@end example

where @var{disc-number} is the number of the slot you want to activate.

@item
@cindex @code{list}
The @code{list} command will display the entire contents of your
changer.

@end itemize

@emph{Note}: CD changers are not supported on all platforms.

@node Volume Control, Other Commands, Changing CDs, General Commands
@cindex volume, controlling the drive's
@subsection Controlling the Drive's Volume

@itemize @bullet

@item
@cindex @code{setvol}
The @code{setvol} command can set the drive's volume.

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

@example
setvol [@var{volume}] [f=@var{volume}] [b=@var{volume}] [l=@var{volume}]
       [r=@var{volume}] [fl=@var{volume}] [fr=@var{volume}]
       [bl=@var{volume}] [br=@var{volume}]
@end example

@item
@cindex @code{getvol}
The @code{getvol} command displays the volume settings.

@end itemize

@strong{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 @code{setvol} and @code{getvol} commands are
provided only for completeness.  Use @file{/dev/mixer} instead.

@node Other Commands, , Volume Control, General Commands
@subsection Other Commands

@itemize @bullet

@item
@cindex @code{refresh}
The @code{refresh} command looks up for the current CD's information in
the cd databases online, and updates it.

@item
@cindex @code{verbose}
You can control Cdcd's verbosity with the @code{verbose} command.  When
verbosity is off, Cdcd will display only necessary information.

@example
verbose on
verbose off
@end example

@end itemize

@node The Cdcd Prompt, Bugs, Invocation, Top
@cindex prompt
@chapter The Cdcd Prompt

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

@example
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>
@end example

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

@cindex commands, directory tree
@table @samp
@item (root)
The main directory.  You can use all of the basic commands.
@xref{General Commands}, for information about the basic commands.

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

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

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

@menu
* The Directories System::       How to switch from a directory to another.
* Miscellaneous Root Commands::  Useful commands when you are in
                                 interactive mode.
* The Sites Directory::          Managing servers.
* The Edit Directory::           Building a new cd database entry.
* The Access Directory::         Access parameters.
@end menu

@node The Directories System, Miscellaneous Root Commands, , The Cdcd Prompt
@cindex directories, how directories work
@cindex commands, directories of
@section 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, @samp{edit}, @samp{access}, and @samp{sites}.

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

You can change the current directory in two ways.

@itemize @bullet
@item
You can go into one subdirectory typing its name.  e.g. if you are in
the root directory and want to go to the @samp{sites} subdirectory, type
@code{sites}.

@item
You can go back up one directory typing "@code{..}"; e.g. if you are in
the @samp{edit} subdirectory and type "@code{..}", then you'll be in the
root directory.
@end itemize

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

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

@example
help @var{command}
@end example

Then Cdcd will display the on-line help for the command @var{command}.

@node Miscellaneous Root Commands, The Sites Directory, The Directories System, The Cdcd Prompt
@cindex directories, root
@section Miscellaneous Root Commands

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

@itemize @bullet
@cindex @code{!}
@cindex invoking the shell
@cindex shell invocation
@cindex program, executing
@item
@code{!} is the generic shell call.  You can execute a shell from within
Cdcd with this command: just type @code{!}.  You can execute any program
by typing it and its arguments after the @code{!}; e.g. @samp{! ls -l
~rms}.

@cindex @code{debug}
@item
@code{debug} shows a number of debugging information.

@cindex @code{quit}
@cindex @code{exit}
@cindex leaving Cdcd
@cindex exiting Cdcd
@item
@code{quit} lets you quit Cdcd.  @code{exit} is an alias.  You can type
@kbd{C-d} (also known as @samp{^D}) too.
@end itemize

@node The Sites Directory, The Edit Directory, Miscellaneous Root Commands, The Cdcd Prompt
@cindex @samp{sites}
@cindex directories, @samp{sites}
@section The Sites Directory

The @samp{sites} directory can be used to customize the list of CD
database servers.

@itemize @bullet
@item
@samp{@code{refresh} [@var{url}]} updates the CDDB server list from the
default server or from the specified @var{url}.

@item
@code{display} shows the current buffer list.

@item
@samp{@code{add} @var{location} url=@var{url} @var{type}} adds url
@var{url} with type @var{type} (one of @samp{CDDB} or @samp{CDI}) at
position number @var{location} in the list.

@item
@samp{@code{del} @var{location}} deletes the entry number @var{location}
from the list.

@item
@samp{@code{move} @var{source} @var{destination}} moves the entry number
@var{source} to position number @var{destination}.
@end itemize

@node The Edit Directory, The Access Directory, The Sites Directory, The Cdcd Prompt
@cindex @samp{edit}
@cindex directories, @samp{edit}
@section The Edit Directory

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

@itemize @bullet
@cindex @code{name}
@cindex album, changing the name
@item
@samp{@code{name} [@var{name}]} is the command to get (if @var{name} is
not supplied) or set (if it is) the disc name.

@cindex @code{artist}
@cindex author, setting the author
@item
@samp{@code{artist} [@var{artist}]} is for the artist for the whole CD.

@cindex @code{genre}
@cindex category, setting the CD category
@item
@samp{@code{genre} [@var{genre}]} for the genre.

@cindex @code{track}
@cindex title, setting a track's title
@cindex name, setting a track's name
@item
@samp{@code{track} @var{tracknum} [@var{title}]} for the track number
@var{tracknum}'s title.

@cindex @code{submit}
@item
With the @code{submit} command, you can submit your modifications to a
cd database such as CDDB or CDIndex.

@example
submit [@var{email}]
@end example

You have to specify an e-mail address.
@end itemize

@node The Access Directory, , The Edit Directory, The Cdcd Prompt
@cindex @samp{access}
@cindex directories, @samp{access}
@section The Access Directory

The @samp{access} directory permits the user to configure the access to
the internet.

@itemize @bullet
@cindex @code{access}
@item
@code{access} displays the current access method.

@cindex @code{remote}
@item
@code{remote} sets the current access method to @samp{remote}, i.e. Cdcd
will try to connect to remote databases.

@cindex @code{local}
@item
@code{local} sets the current access method to @samp{local}, i.e. Cdcd
will only access the database locally, and not attempt to reach the
outside world.

@cindex @code{proxy}
@item
@samp{@code{proxy} [@var{url} | off]} sets the current @acronym{HTTP}
proxy to @var{url} or turns proxying off.  Without argument, it shows
the current status.
@end itemize

@node Bugs, Concept Index, The Cdcd Prompt, Top
@cindex bugs
@cindex segmentation violation
@chapter Reporting Bugs

If you find a bug, please report it to
@email{noon@@users.sourceforge.net}.  Please give as many details as
possible; you can try to explain a possible interpretation but
@emph{please}, report @emph{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.

@node Concept Index, , Bugs, Top
@unnumbered Concept Index

@printindex cp
@contents
@bye


@c Local Variables:
@c mode: texinfo
@c mode: auto-fill
@c End: