CDSTATUS(1)

NAME
cdstatus - CD Status and Ripping Tool

SYNOPSIS
cdstatus [ OPTIONS]

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.

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 --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 [TRACK]
    Begin readtest/rip at track X (default is 1)

--stop [TRACK]
    Stop readtest/rip at track X (default is last track on cd)

--outputdir <path>
    Place output files in specified path instead of the default of the current working directory.

--basename <name>
    Output files are created with file names based on <name>XX.wav (where XX is the track number) instead of trackXX.wav.

--readchunk <frames>
    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 <number>
    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

--lame
    Pipe extracted audio directly to lame (encode music straight to mp3). Note that lame must be already installed in your system and the lame executable must be in your PATH environment in order for this to work.

--lameopts "<options to pass to lame>"
    Use this to specify options controlling the behavior of the lame encode. A quick example would be --lameopts "--preset standard -q0" See the lame man pages and help output for more details. Note that the double quotes around the arguments to this option are required if you want to pass more than one option to lame.

--format <format string>
    Used to specify filename format for output files. only valid when used with --cddb. The syntax of the format string is:

    #Artist#
        Becomes artist name
    #Album#
        Becomes name of cd
    #TrkNum#
        Becomes track number, like 01, 02 ...
    #TrkName#
        Becomes track name
    See README for examples.  Other characters are allowed freeform.

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 need to copy it from there 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#"

OTHERS
For the curious, NO code has been re-used or pulled in from any other source, program, or person, except as noted below. This work is the original creation of its author, Nathanael Hoyle.

Proviso: As of version .94a, I did use the code on www.freedb.org as a starting point for my code for calculating the cddb disc id. It is re-written to inline the second function and use fewer variables, hopefully running faster overall. Kudos to their documentation team, the info presented there is clear and well-written.

TODO
* a GUI: I believe that a GUI is at this time probably the single most desired/ useful feature that I could add to improve the program. There are many who either lack the comfort with the command-line or simply enjoy the convenience of a GUI who would get far more use out of cdstatus if it had one. I am acutely aware of this fact. I am also acutely aware of my lack of background with GUI programming under linux. I have been programming in C for over a decade but have never learned a modern native windowing API for *nix. (I throw native in there because I *could* throw together a separate executable in Java written to simply call the existing cdstatus executable on the backend... I don't like layering a massive java virtual machine as a requirement on what is currently a very small and tightly written application, relatively speaking.) Unfortunately I also lack the free time (because of normal work time demands) to delve into QT or GTK at this point in time. Therefore I am very actively seeking any volunteers to help me put together a GUI for cdstatus. I cannot offer anything more than full credit given for all work contributed, as cdstatus is not a source of revenue for me. If no volunteer appears, cdstatus will still get a GUI at some point in the indeterminate future, but I have no idea when I will have to time to delve into that.

* configurable re-reads of successfully read data for validation and/or paranoid extraction of audio. Similar to exactaudiocopy, but I have a few more ideas up my sleeve in that area.

* Data extraction (data tracks) from MODE1 MODE2 and MIXED mode cd's. (Note: I am having some difficulty in figuring out exactly how/what I need to pass in for the LBA mode addressing I need to use for the relavent system calls to do this. If anyone reading this is familiar with LBA addressing mode access to cdrom drives under linux and wants to lend me 10 minutes of time to explain a thing or two, it would be most appreciated.)

* Support for other encoders (i.e. ogg vorbis, etc) besides lame for compressed output.

AUTHORS
Written and maintained by Nathanael Hoyle (nathanaelhoyle@users.sourceforge.net)

Tom Weber provided some very good testing for a couple of weeks and contributed some code revisions for a somewhat improved progress bar, my thanks go to him.

The original version of this manual page was contributed by a user whose contact information I have since regrettably lost. His efforts are also appreciated.

BUGS
No known bugs in current revision.

Report bugs to nathanaelhoyle@users.sourceforge.net (Actually, your best bet for quick support and/or a fix if one exists may be to visit the cdstatus user forums, the URL for them may move, but they are linked from http://cdstatus.sourceforge.net/)