
See the NEWS, README, and man page for the summary on using the new 
features.

*******************************************************************

Preamble: My documentation files tend to get a bit (or really) behind my
code at times.  If you think something in here disagrees with what you
are seeing in practice, you are probably right.  This file went from
2001 to 2004 with only minor edits, and no complete re-write.

Description:
-----------

This utility was designed and implemented by Nathanael Hoyle.  Original
version made in July of 2001.  It began in life as a purely diagnostic
tool, designed to validate and troubleshoot the operation of cdrom drives
and the usability of cdrom media.  Since then it has evolved into a full-
featured and still growing audio extraction (ripping) tool, with support
for a plethora of options, including cddb lookup and automatic track naming.

Features:
* Queries the status of the CDROM drive at a very low level, and displays 
the results; this is useful for diagnosing a malfunctioning drive.

* Can reset a drive internally without a reboot.

* It will display the type of any disc present.  (Helps to figure out for
instance that you burned your cd full of wav files as DATA, not as audio 
tracks).

* Complete, and configurable audio extraction/ripping featureset.  See the
output from --help.

Options:
--------

With no options, version info is displayed followed by basic information about 
the status of the drive, cd if present, and the tracks on said cd, as well as 
volume levels of cd drive.

--reset

       Causes the drive to perform a reset.  You will almost certainly need to 
       be root to perform this operation.

--readtest
--rip

	Performs exhaustive read analysis (audio extraction) for audio cd's.  
	Will retry failed reads up to the max retries chosen by the user (default 3,
	override with --retries X), if so chosen.  --rip has been added as an 
	alternate command for --readtest.  This mode of operation is now the default,
	and is essentially obsolete.  It remains for backward compatibility.

--waveout

	Now the default --readtest mode, --waveout will create .wav files instead of 
	.raw files. You may still obtain .raw files via --rawout.  Specifying 
	--waveout is now redundant, but for historical reasons, it won't break 
	anything.  Use of this option automatically sets --readtest.

--rawout

	Causes ripped tracks to be written in the original .raw format, which is 
	headerless and not directly playable without providing some information to 
	the player application. Use of this option automatically sets --readtest.

--start X

	Begin readtest/rip at track X (default is 1)

--stop X

	Stop readtest/rip at track X (default is last track on cd)

--outputdir /path/

	Place output files in /path/ instead of the default of the current working 
	directory.

--basename somename

	Output files are created with file names based on somenameXX.wav (where XX 
	is the track number) instead of trackXX.wav.

--readchunk X

	Use this to read the track data (--readtest) at some alternate number of 
	frames per read.  Normally this is 1 to allow exact detection of errors 
	on the disc surface, however --readchunk 25 would read 25 frames at once.
	This improves performance up to some system dependent value (i.e. the 
	ideal setting will depend on your system) but it gives up the fine-grained 
	error detection.  Going over 75 is not supported by most hardware, and is
	not a good idea.

--retries X

	Perform X retries of failed reads.  Default is 3.

--version

	Displays version and copyright info, then exits.

--help
	Displays brief usage summary and exits.
	
--cddb

	calculates disc id and contacts freedb server to retrieve album info and track
	listings
	
--format "format spec here"

	only valid when used with --cddb, this option allows you to specify an output
	format for the filenames from the cddb info for the cd.  Example:
	
        "#Artist#/#Album/#Artist#-#Album#-#TrkNum#-#TrkName#"
	Could be: The Beatles/The White Album/The Beatles-The White Album-13-Rocky Raccoon
	
	note that you may use any characters except those proscribed by your 
	filesystem, or spaces, in your format specification.  Incorporating a 
	slash (/) in the spec will create directories and subdirectories if relevant.
	this does not replace --outputdir.  If you used --outputdir 
	/home/myusername/music with the above example, you would end up with files in 
	/home/myusername/music/The Beatles/The White Album/
	
	The format used in the example above is the default format when --cddb is 
	used without an explicit format string.
	
	The directory specified in --outputdir should already exist, but the others 
	will be created as needed.
	
	One more time: DO NOT USE SPACES in your format string.  Thank you.
	Also, the " in the example are NOT just for show.  You MUST enclose the format
	spec pattern inside quotes or the program will seg-fault.

User Configuration File:
------------------------
As of cdstatus 0.95b, there is support for a per-user .cdstatus configuration
file in the home directory to specify defaults for many of the option that
are available at the command line.  I am including the body of an example
.cdstatus config file here, with the intent that it be self-documenting. For
clarification, feel free to check the source :-). This file should be installed
by default to /usr/local/share/cdstatus/cdstatus.cfg or a similar path. You will
need to copy it to your home directory and rename it to .cdstatus in order for it
to take effect.

File begins:
#This per-user file specifies cdstatus default values.  Any values specified here
#override normal cdstatus defaults, but are themselves overwritten by any values
#passed on the command line.

#Comments begin with # or ;.  Any line beginning with # or ; (or a blank line) is ignored.

#The values here (commented out) should be the default program values.  To set a
#value, remove the comment character, and modify the setting.  This is a new feature
#and as such may be buggy.  Please report any trouble encountered to nathanaelhoyle@users.sf.net


#drive=/dev/cdrom

#outputdir=.

#retries=3

#output=wav

#retries=3

#basename=track

#cddb_site=us.freedb.org

#cddb=no

#default_first_match=no

#format="#Artist#/#Album#/#Artist#_-_#Album#_-_#TrkNum#_-_#TrkName#"

Licensing:
----------

Please read the LICENSE file.

Final Notes:
------------
Please send any feedback.  I am asking that those of you who have a moment, 
please take it and write an email with your impressions, suggestions, ideas,
complaints, comments, etc.  These go a long way to encouraging further work 
and making it worthwhile, as well as letting me know what users want from
cdstatus.  Thanks.

Nathanael Hoyle
nathanaelhoyle@users.sourceforge.net

