Blame doc/en/cd-paranoia.1

Packit cb6d3d
.TH cd-paranoia 1 "version III release alpha 9.8 libcdio"
Packit cb6d3d
.SH NAME
Packit cb6d3d
cd-paranoia 9.8 (Paranoia release III via libcdio) \- an audio CD reading utility which includes extra data verification features
Packit cb6d3d
.SH SYNOPSIS
Packit cb6d3d
.B cd-paranoia
Packit cb6d3d
.RB [ options ]
Packit cb6d3d
.B span
Packit cb6d3d
.RB [ outfile ]
Packit cb6d3d
.SH DESCRIPTION
Packit cb6d3d
.B cd-paranoia
Packit cb6d3d
retrieves audio tracks from CDDA capable CD-ROM drives.  The data can
Packit cb6d3d
be saved to a file or directed to standard output in WAV, AIFF, AIFF-C
Packit cb6d3d
or raw format.  Most ATAPI, SCSI and several proprietary CD-ROM drive
Packit cb6d3d
makes are supported;
Packit cb6d3d
.B cd-paranoia
Packit cb6d3d
can determine if the target drive is CDDA capable.
Packit cb6d3d
.P
Packit cb6d3d
In addition to simple reading,
Packit cb6d3d
.B cd-paranoia
Packit cb6d3d
adds extra-robust data verification, synchronization, error handling
Packit cb6d3d
and scratch reconstruction capability.
Packit cb6d3d
.P
Packit cb6d3d
This version uses the libcdio library for interaction with a CD-ROM
Packit cb6d3d
drive. The jitter and error correction however are the same as used in
Packit cb6d3d
Xiph's cdparanoia.
Packit cb6d3d
.SH OPTIONS
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-A --analyze-drive
Packit cb6d3d
Run and log a complete analysis of drive caching, timing and reading behavior;
Packit cb6d3d
verifies that cdparanoia is correctly modelling a sprcific drive's cache and
Packit cb6d3d
read behavior. Implies -vQL.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-v --verbose
Packit cb6d3d
Be absurdly verbose about the autosensing and reading process. Good
Packit cb6d3d
for setup and debugging.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-q --quiet
Packit cb6d3d
Do not print any progress or error information during the reading process.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-e --stderr-progress
Packit cb6d3d
Force output of progress information to stderr (for wrapper scripts).
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-V --version
Packit cb6d3d
Print the program version and quit.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-Q --query
Packit cb6d3d
Perform CD-ROM drive autosense, query and print the CD-ROM table of
Packit cb6d3d
contents, then quit.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-h --help
Packit cb6d3d
Print a brief synopsis of
Packit cb6d3d
.B cd-paranoia
Packit cb6d3d
usage and options.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-l --log-summary " file
Packit cb6d3d
Save result summary to file.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-L --log-debug " file
Packit cb6d3d
Save detailed device autosense and debugging output to a file.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-p --output-raw
Packit cb6d3d
Output headerless data as raw 16 bit PCM data with interleaved samples in host byte order.  To force little or big endian byte order, use
Packit cb6d3d
.B \-r
Packit cb6d3d
or
Packit cb6d3d
.B \-R
Packit cb6d3d
as described below.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-r --output-raw-little-endian
Packit cb6d3d
Output headerless data as raw 16 bit PCM data with interleaved samples in LSB first byte order.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-R --output-raw-big-endian
Packit cb6d3d
Output headerless data as raw 16 bit PCM data with interleaved samples in MSB first byte order.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-w --output-wav
Packit cb6d3d
Output data in Micro$oft RIFF WAV format (note that WAV data is always
Packit cb6d3d
LSB first byte order).
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-f --output-aiff
Packit cb6d3d
Output data in Apple AIFF format (note that AIFC data is
Packit cb6d3d
always in MSB first byte order).
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-a --output-aifc
Packit cb6d3d
Output data in uncompressed Apple AIFF-C format (note that AIFF-C data is
Packit cb6d3d
always in MSB first byte order).
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-B --batch "
Packit cb6d3d
Packit cb6d3d
Cdda2wav-style batch output flag; cd-paranoia will split the output
Packit cb6d3d
into multiple files at track boundaries.  Output file names are
Packit cb6d3d
prepended with 'track#.'
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-c --force-cdrom-little-endian
Packit cb6d3d
Some CD-ROM drives misreport their endianness (or do not report it at
Packit cb6d3d
all); it's possible that cd-paranoia will guess wrong.  Use
Packit cb6d3d
.B \-c
Packit cb6d3d
to force cd-paranoia to treat the drive as a little endian device.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-C --force-cdrom-big-endian
Packit cb6d3d
As above but force cd-paranoia to treat the drive as a big endian device.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-n --force-default-sectors " n
Packit cb6d3d
Force the interface backend to do atomic reads of
Packit cb6d3d
.B n
Packit cb6d3d
sectors per read.  This number can be misleading; the kernel will often
Packit cb6d3d
split read requests into multiple atomic reads (the automated Paranoia
Packit cb6d3d
code is aware of this) or allow reads only wihin a restricted size
Packit cb6d3d
range.
Packit cb6d3d
.B This option should generally not be used.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-d --force-cdrom-device " device
Packit cb6d3d
Force the interface backend to read from
Packit cb6d3d
.B device
Packit cb6d3d
rather than the first readable CD-ROM drive it finds containing a
Packit cb6d3d
CD-DA disc.  This can be used to specify devices of any valid
Packit cb6d3d
interface type (ATAPI, SCSI or proprietary).
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-g --force-generic-device " device
Packit cb6d3d
This option is an alias for
Packit cb6d3d
.B \-d
Packit cb6d3d
and is retained for compatibility.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-S --force-read-speed " number
Packit cb6d3d
Use this option explicitly to set the read rate of the CD drive (where
Packit cb6d3d
supported).  This can reduce underruns on machines with slow disks, or
Packit cb6d3d
which are low on memory.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-t --toc-offset " number
Packit cb6d3d
Use this option to force the entire disc LBA addressing to shift by
Packit cb6d3d
the given amount; the value is added to the beginning offsets in the
Packit cb6d3d
TOC.  This can be used to shift track boundaries for the whole disc
Packit cb6d3d
manually on sector granularity.  The next option does something
Packit cb6d3d
similar...
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-T --toc-bias "
Packit cb6d3d
Some drives (usually random Toshibas) report the actual track
Packit cb6d3d
beginning offset values in the TOC, but then treat the beginning of
Packit cb6d3d
track 1 index 1 as sector 0 for all read operations.  This results in
Packit cb6d3d
every track seeming to start too late (losing a bit of the beginning
Packit cb6d3d
and catching a bit of the next track).
Packit cb6d3d
\-T accounts for this behavior.  Note that this option will cause
Packit cb6d3d
cd-paranoia to attempt to read sectors before or past the known user
Packit cb6d3d
data area of the disc, resulting in read errors at disc edges on most
Packit cb6d3d
drives and possibly even hard lockups on some buggy hardware.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI "\-O --sample-offset " number
Packit cb6d3d
Some CD-ROM/CD-R drives will add an offset to the position on reading
Packit cb6d3d
audio data. This is usually around 500-700 audio samples (ca. 1/75
Packit cb6d3d
second) on reading. So when cd-paranoia queries a specific
Packit cb6d3d
sector, it might not receive exactly that sector, but shifted by some
Packit cb6d3d
amount.
Packit cb6d3d
.P
Packit cb6d3d
Use this option to force the entire disc to shift sample position
Packit cb6d3d
output by the given amount; This can be used to shift track boundaries
Packit cb6d3d
for the whole disc manually on sample granularity. Note that if you
Packit cb6d3d
are ripping something including the ending of the CD (e.g. the entire
Packit cb6d3d
disk), this option will cause cd-paranoia to attempt to read
Packit cb6d3d
partial sectors before or past the known user data area, probably
Packit cb6d3d
causing read errors on most drives and possibly even hard lockups on
Packit cb6d3d
some buggy hardware.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.BI \-E --force-overread
Packit cb6d3d
Force overreading into the lead-out portion of the disc. This option is only applicable when using the
Packit cb6d3d
+.B -O
Packit cb6d3d
+option with a positive sample offset value. Many drives are not capable of reading into this portion of the disc and attempting to do so on those drives will produce read errors and possibly hard lockups.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-Z --disable-paranoia
Packit cb6d3d
Disable
Packit cb6d3d
.B all
Packit cb6d3d
data verification and correction features.  When using -Z, cd-paranoia
Packit cb6d3d
reads data exactly as would cdda2wav with an overlap setting of zero.
Packit cb6d3d
This option implies that
Packit cb6d3d
.B \-Y
Packit cb6d3d
is active.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-z --never-skip[=max_retries]
Packit cb6d3d
Do not accept any skips; retry forever if needed.  An optional maximum
Packit cb6d3d
number of retries can be specified; for comparison, default without -z is
Packit cb6d3d
currently 20.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-Y --disable-extra-paranoia
Packit cb6d3d
Disables intra-read data verification; only overlap checking at read
Packit cb6d3d
boundaries is performed. It can wedge if errors occur in the attempted overlap area. Not recommended.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-X --abort-on-skip
Packit cb6d3d
If the read skips due to imperfect data, a scratch, whatever, abort reading this track.  If output is to a file, delete the partially completed file.
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B \-x --test-flags mask
Packit cb6d3d
Simulate CD-reading errors. This is used in regression testing, but
Packit cb6d3d
other uses might be to see how well a CD-ROM performs under
Packit cb6d3d
(simulated) CD degradation. mask specifies the artificial kinds of
Packit cb6d3d
errors to introduced; "or"-ing values from the selection below will
Packit cb6d3d
simulate the kind of specified failure.
Packit cb6d3d
.P
Packit cb6d3d
     0x10  - Simulate under-run reading
Packit cb6d3d
.TP
Packit cb6d3d
Packit cb6d3d
Packit cb6d3d
.SH OUTPUT SMILIES
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-)
Packit cb6d3d
Normal operation, low/no jitter
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-|
Packit cb6d3d
Normal operation, considerable jitter
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-/
Packit cb6d3d
Read drift
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-P
Packit cb6d3d
Unreported loss of streaming in atomic read operation
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  8-|
Packit cb6d3d
Finding read problems at same point during reread; hard to correct
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-0
Packit cb6d3d
SCSI/ATAPI transport error
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :-(
Packit cb6d3d
Scratch detected
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  ;-(
Packit cb6d3d
Gave up trying to perform a correction
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  8-X
Packit cb6d3d
Aborted read due to known, uncorrectable error
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
  :^D
Packit cb6d3d
Finished extracting
Packit cb6d3d
Packit cb6d3d
.SH PROGRESS BAR SYMBOLS
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
<space>
Packit cb6d3d
No corrections needed
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
   -
Packit cb6d3d
Jitter correction required
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
   +
Packit cb6d3d
Unreported loss of streaming/other error in read
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
   !
Packit cb6d3d
Errors found after stage 1 correction; the drive is making the
Packit cb6d3d
same error through multiple re-reads, and cd-paranoia is having trouble
Packit cb6d3d
detecting them.
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
   e
Packit cb6d3d
SCSI/ATAPI transport error (corrected)
Packit cb6d3d
.TP
Packit cb6d3d
.B
Packit cb6d3d
   V
Packit cb6d3d
Uncorrected error/skip
Packit cb6d3d
Packit cb6d3d
.SH SPAN ARGUMENT
Packit cb6d3d
Packit cb6d3d
The span argument specifies which track, tracks or subsections of
Packit cb6d3d
tracks to read.  This argument is required.
Packit cb6d3d
.B NOTE:
Packit cb6d3d
Unless the span is a simple number, it's generally a good idea to
Packit cb6d3d
quote the span argument to protect it from the shell.
Packit cb6d3d
.P
Packit cb6d3d
The span argument may be a simple track number or an offset/span
Packit cb6d3d
specification.  The syntax of an offset/span takes the rough form:
Packit cb6d3d
.P
Packit cb6d3d
1[ww:xx:yy.zz]-2[aa:bb:cc.dd]
Packit cb6d3d
.P
Packit cb6d3d
Here, 1 and 2 are track numbers; the numbers in brackets provide a
Packit cb6d3d
finer grained offset within a particular track. [aa:bb:cc.dd] is in
Packit cb6d3d
hours/minutes/seconds/sectors format. Zero fields need not be
Packit cb6d3d
specified: [::20], [:20], [20], [20.], etc, would be interpreted as
Packit cb6d3d
twenty seconds, [10:] would be ten minutes, [.30] would be thirty
Packit cb6d3d
sectors (75 sectors per second).
Packit cb6d3d
.P
Packit cb6d3d
When only a single offset is supplied, it is interpreted as a starting
Packit cb6d3d
offset and ripping will continue to the end of the track.  If a single
Packit cb6d3d
offset is preceeded or followed by a hyphen, the implicit missing
Packit cb6d3d
offset is taken to be the start or end of the disc, respectively. Thus:
Packit cb6d3d
Packit cb6d3d
.TP
Packit cb6d3d
.B  1:[20.35]
Packit cb6d3d
Specifies ripping from track 1, second 20, sector 35 to the end of
Packit cb6d3d
track 1.
Packit cb6d3d
.TP
Packit cb6d3d
.B 1:[20.35]-
Packit cb6d3d
Specifies ripping from 1[20.35] to the end of the disc
Packit cb6d3d
.TP
Packit cb6d3d
.B \-2
Packit cb6d3d
Specifies ripping from the beginning of the disc up to (and including) track 2
Packit cb6d3d
.TP
Packit cb6d3d
.B \-2:[30.35]
Packit cb6d3d
Specifies ripping from the beginning of the disc up to 2:[30.35]
Packit cb6d3d
.TP
Packit cb6d3d
.B 2-4
Packit cb6d3d
Specifies ripping from the beginning of track 2 to the end of track 4.
Packit cb6d3d
.P
Packit cb6d3d
Again, don't forget to protect square brackets and preceeding hyphens from
Packit cb6d3d
the shell.
Packit cb6d3d
Packit cb6d3d
.SH EXAMPLES
Packit cb6d3d
Packit cb6d3d
A few examples, protected from the shell:
Packit cb6d3d
.TP
Packit cb6d3d
Query only with exhaustive search for a drive and full reporting of autosense:
Packit cb6d3d
.P
Packit cb6d3d
       cd-paranoia -vsQ
Packit cb6d3d
.TP
Packit cb6d3d
Extract an entire disc, putting each track in a seperate file:
Packit cb6d3d
.P
Packit cb6d3d
       cd-paranoia -B
Packit cb6d3d
.TP
Packit cb6d3d
Extract from track 1, time 0:30.12 to 1:10.00:
Packit cb6d3d
.P
Packit cb6d3d
       cd-paranoia "1[:30.12]-1[1:10]"
Packit cb6d3d
.TP
Packit cb6d3d
Extract from the beginning of the disc up to track 3:
Packit cb6d3d
.P
Packit cb6d3d
       cd-paranoia -- "-3"
Packit cb6d3d
.TP
Packit cb6d3d
The "--" above is to distinguish "-3" from an option flag.
Packit cb6d3d
.SH OUTPUT
Packit cb6d3d
Packit cb6d3d
The output file argument is optional; if it is not specified,
Packit cb6d3d
cd-paranoia will output samples to one of
Packit cb6d3d
.BR cdda.wav ", " cdda.aifc ", or " cdda.raw
Packit cb6d3d
depending on whether
Packit cb6d3d
.BR \-w ", " \-a ", " \-r " or " \-R " is used (" \-w
Packit cb6d3d
is the implicit default).  The output file argument of
Packit cb6d3d
.B \-
Packit cb6d3d
specifies standard output; all data formats may be piped.
Packit cb6d3d
Packit cb6d3d
.SH ACKNOWLEDGEMENTS
Packit cb6d3d
cd-paranoia sprang from and once drew heavily from the interface of
Packit cb6d3d
Heiko Eissfeldt's (heiko@colossus.escape.de) 'cdda2wav'
Packit cb6d3d
package. cd-paranoia would not have happened without it.
Packit cb6d3d
.P
Packit cb6d3d
Joerg Schilling has also contributed SCSI expertise through his
Packit cb6d3d
generic SCSI transport library.
Packit cb6d3d
.P
Packit cb6d3d
.SH AUTHOR
Packit cb6d3d
Monty <monty@xiph.org>
Packit cb6d3d
.P
Packit cb6d3d
Cdparanoia's homepage may be found at:
Packit cb6d3d
http://www.xiph.org/paranoia/
Packit cb6d3d
.P
Packit cb6d3d
Revised for use with libcdio by Rocky <rocky@gnu.org>
Packit cb6d3d
.P
Packit cb6d3d
The libcdio homepage may be found at:
Packit cb6d3d
http://www.gnu.org/software/libcdio