cdparanoia/cdparanoia.1

   1 .TH CDPARANOIA 1 "02 Mar 2001"
   2 .SH NAME
   3 cdparanoia 9.8 (Paranoia release III) \- an audio CD reading utility which includes extra data verification features
   4 .SH SYNOPSIS
   5 .B cdparanoia
   6 .RB [ options ]
   7 .B span
   8 .RB [ outfile ]
   9 .SH DESCRIPTION
  10 .B cdparanoia
  11 retrieves audio tracks from CDDA capable CDROM drives.  The data can
  12 be saved to a file or directed to standard output in WAV, AIFF, AIFF-C
  13 or raw format.  Most ATAPI, SCSI and several proprietary CDROM drive
  14 makes are supported;
  15 .B cdparanoia
  16 can determine if the target drive is CDDA capable.
  17 .P
  18 In addition to simple reading,
  19 .B cdparanoia
  20 adds extra-robust data verification, synchronization, error handling
  21 and scratch reconstruction capability.
  22 .SH OPTIONS
  23
  24 .TP
  25 .B \-v --verbose
  26 Be absurdly verbose about the autosensing and reading process. Good
  27 for setup and debugging.
  28
  29 .TP
  30 .B \-q --quiet
  31 Do not print any progress or error information during the reading process.
  32
  33 .TP
  34 .B \-e --stderr-progress
  35 Force output of progress information to stderr (for wrapper scripts).
  36
  37 .TP
  38 .B \-V --version
  39 Print the program version and quit.
  40
  41 .TP
  42 .B \-Q --query
  43 Perform CDROM drive autosense, query and print the CDROM table of
  44 contents, then quit.
  45
  46 .TP
  47 .B \-s --search-for-drive
  48 Forces a complete search for a cdrom drive, even if the /dev/cdrom link exists.
  49
  50 .TP
  51 .B \-h --help
  52 Print a brief synopsis of
  53 .B cdparanoia
  54 usage and options.
  55
  56 .TP
  57 .B \-p --output-raw
  58 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
  59 .B \-r
  60 or
  61 .B \-R
  62 as described below.
  63
  64 .TP
  65 .B \-r --output-raw-little-endian
  66 Output headerless data as raw 16 bit PCM data with interleaved samples in LSB first byte order.
  67
  68 .TP
  69 .B \-R --output-raw-big-endian
  70 Output headerless data as raw 16 bit PCM data with interleaved samples in MSB first byte order.
  71
  72 .TP
  73 .B \-w --output-wav
  74 Output data in Micro$oft RIFF WAV format (note that WAV data is always
  75 LSB first byte order).
  76
  77 .TP
  78 .B \-f --output-aiff
  79 Output data in Apple AIFF format (note that AIFC data is
  80 always in MSB first byte order).
  81
  82 .TP
  83 .B \-a --output-aifc
  84 Output data in uncompressed Apple AIFF-C format (note that AIFF-C data is
  85 always in MSB first byte order).
  86
  87 .TP
  88 .BI "\-B --batch "
  89
  90 Cdda2wav-style batch output flag; cdparanoia will split the output
  91 into multiple files at track boundaries.  Output file names are
  92 prepended with 'track#.'
  93
  94 .TP
  95 .B \-c --force-cdrom-little-endian
  96 Some CDROM drives misreport their endianness (or do not report it at
  97 all); it's possible that cdparanoia will guess wrong.  Use
  98 .B \-c
  99 to force cdparanoia to treat the drive as a little endian device.
 100
 101 .TP
 102 .B \-C --force-cdrom-big-endian
 103 As above but force cdparanoia to treat the drive as a big endian device.
 104
 105 .TP
 106 .BI "\-n --force-default-sectors " n
 107 Force the interface backend to do atomic reads of
 108 .B n
 109 sectors per read.  This number can be misleading; the kernel will often
 110 split read requests into multiple atomic reads (the automated Paranoia
 111 code is aware of this) or allow reads only wihin a restricted size
 112 range.
 113 .B This option should generally not be used.
 114
 115 .TP
 116 .BI "\-d --force-cdrom-device " device
 117 Force the interface backend to read from
 118 .B device
 119 rather than the first readable CDROM drive it finds.  This can be used
 120 to specify devices of any valid interface type (ATAPI, SCSI or
 121 proprietary).
 122
 123 .TP
 124 .BI "\-g --force-generic-device " device
 125 This option is used along with
 126 .B \-d
 127 when one wants explicit control in setting both the SCSI cdrom and
 128 generic devices seperately. This option is only useful on
 129 non-standard SCSI setups.
 130
 131 .TP
 132 .BI "\-S --force-read-speed " number
 133 Use this option explicitly to set the read rate of the CD drive (where
 134 supported).  This can reduce underruns on machines with slow disks, or
 135 which are low on memory.
 136
 137 .TP
 138 .BI "\-t --toc-offset " number
 139 Use this option to force the entire disc LBA addressing to shift by
 140 the given amount; the value is added to the beginning offsets in the
 141 TOC.  This can be used to shift track boundaries for the whole disc
 142 manually on sector granularity.  The next option does something
 143 similar...
 144
 145 .TP
 146 .BI "\-T --toc-bias "
 147 Some drives (usually random Toshibas) report the actual track
 148 beginning offset values in the TOC, but then treat the beginning of
 149 track 1 index 1 as sector 0 for all read operations.  This results in
 150 every track seeming to start too late (losing a bit of the beginning
 151 and catching a bit of the next track).
 152 .B \-T
 153 accounts for this behavior.  Note that this option will cause
 154 cdparanoia to attempt to read sectors before or past the known user
 155 data area of the disc, resulting in read errors at disc edges on most
 156 drives and possibly even hard lockups on some buggy hardware.
 157
 158 .TP
 159 .BI "\-O --sample-offset " number
 160 Use this option to force the entire disc to shift sample position
 161 output by the given amount; This can be used to shift track boundaries
 162 for the whole disc manually on sample granularity. Note that this will
 163 cause cdparanoia to attempt to read partial sectors before or past the
 164 known user data area of the disc, probably causing read errors on most
 165 drives and possibly even hard lockups on some buggy hardware.
 166
 167
 168 .TP
 169 .B \-Z --disable-paranoia
 170 Disable
 171 .B all
 172 data verification and correction features.  When using -Z, cdparanoia
 173 reads data exactly as would cdda2wav with an overlap setting of zero.
 174 This option implies that
 175 .B \-Y
 176 is active.
 177
 178 .TP
 179 .B \-z --never-skip[=max_retries]
 180 Do not accept any skips; retry forever if needed.  An optional maximum
 181 number of retries can be specified; for comparison, default without -z is
 182 currently 20.
 183
 184 .TP
 185 .B \-Y --disable-extra-paranoia
 186 Disables intra-read data verification; only overlap checking at read
 187 boundaries is performed. It can wedge if errors occur in the attempted overlap area. Not recommended.
 188
 189 .TP
 190 .B \-X --abort-on-skip
 191 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.
 192
 193 .SH OUTPUT SMILIES
 194 .TP
 195 .B
 196   :-)
 197 Normal operation, low/no jitter
 198 .TP
 199 .B
 200   :-|
 201 Normal operation, considerable jitter
 202 .TP
 203 .B
 204   :-/
 205 Read drift
 206 .TP
 207 .B
 208   :-P
 209 Unreported loss of streaming in atomic read operation
 210 .TP
 211 .B
 212   8-|
 213 Finding read problems at same point during reread; hard to correct
 214 .TP
 215 .B
 216   :-0
 217 SCSI/ATAPI transport error
 218 .TP
 219 .B
 220   :-(
 221 Scratch detected
 222 .TP
 223 .B
 224   ;-(
 225 Gave up trying to perform a correction
 226 .TP
 227 .B
 228   8-X
 229 Aborted read due to known, uncorrectable error
 230 .TP
 231 .B
 232   :^D
 233 Finished extracting
 234
 235 .SH PROGRESS BAR SYMBOLS
 236 .TP
 237 .B
 238 <space>
 239 No corrections needed
 240 .TP
 241 .B
 242    -
 243 Jitter correction required
 244 .TP
 245 .B
 246    +
 247 Unreported loss of streaming/other error in read
 248 .TP
 249 .B
 250    !
 251 Errors found after stage 1 correction; the drive is making the
 252 same error through multiple re-reads, and cdparanoia is having trouble
 253 detecting them.
 254 .TP
 255 .B
 256    e
 257 SCSI/ATAPI transport error (corrected)
 258 .TP
 259 .B
 260    V
 261 Uncorrected error/skip
 262
 263 .SH SPAN ARGUMENT
 264
 265 The span argument specifies which track, tracks or subsections of
 266 tracks to read.  This argument is required.
 267 .B NOTE:
 268 Unless the span is a simple number, it's generally a good idea to
 269 quote the span argument to protect it from the shell.
 270 .P
 271 The span argument may be a simple track number or an offset/span
 272 specification.  The syntax of an offset/span takes the rough form:
 273 .P
 274 1[ww:xx:yy.zz]-2[aa:bb:cc.dd]
 275 .P
 276 Here, 1 and 2 are track numbers; the numbers in brackets provide a
 277 finer grained offset within a particular track. [aa:bb:cc.dd] is in
 278 hours/minutes/seconds/sectors format. Zero fields need not be
 279 specified: [::20], [:20], [20], [20.], etc, would be interpreted as
 280 twenty seconds, [10:] would be ten minutes, [.30] would be thirty
 281 sectors (75 sectors per second).
 282 .P
 283 When only a single offset is supplied, it is interpreted as a starting
 284 offset and ripping will continue to the end of the track.  If a single
 285 offset is preceeded or followed by a hyphen, the implicit missing
 286 offset is taken to be the start or end of the disc, respectively. Thus:
 287
 288 .TP
 289 .B  1:[20.35]
 290 Specifies ripping from track 1, second 20, sector 35 to the end of
 291 track 1.
 292 .TP
 293 .B 1:[20.35]-
 294 Specifies ripping from 1[20.35] to the end of the disc
 295 .TP
 296 .B \-2
 297 Specifies ripping from the beginning of the disc up to (and including) track 2
 298 .TP
 299 .B \-2:[30.35]
 300 Specifies ripping from the beginning of the disc up to 2:[30.35]
 301 .TP
 302 .B 2-4
 303 Specifies ripping from the beginning of track 2 to the end of track 4.
 304 .P
 305 Again, don't forget to protect square brackets and preceeding hyphens from
 306 the shell.
 307
 308 .SH EXAMPLES
 309
 310 A few examples, protected from the shell:
 311 .TP
 312 Query only with exhaustive search for a drive and full reporting of autosense:
 313 .P
 314        cdparanoia -vsQ
 315 .TP
 316 Extract an entire disc, putting each track in a seperate file:
 317 .P
 318        cdparanoia -B
 319 .TP
 320 Extract from track 1, time 0:30.12 to 1:10.00:
 321 .P
 322        cdparanoia "1[:30.12]-1[1:10]"
 323 .TP
 324 Extract from the beginning of the disc up to track 3:
 325 .P
 326        cdparanoia -- "-3"
 327 .TP
 328 The "--" above is to distinguish "-3" from an option flag.
 329 .SH OUTPUT
 330
 331 The output file argument is optional; if it is not specified,
 332 cdparanoia will output samples to one of
 333 .BR cdda.wav ", " cdda.aifc ", or " cdda.raw
 334 depending on whether
 335 .BR \-w ", " \-a ", " \-r " or " \-R " is used (" \-w
 336 is the implicit default).  The output file argument of
 337 .B \-
 338 specifies standard output; all data formats may be piped.
 339
 340 .SH ACKNOWLEDGEMENTS
 341 Cdparanoia sprang from and once drew heavily from the interface of
 342 Heiko Eissfeldt's (heiko@colossus.escape.de) 'cdda2wav'
 343 package. Cdparanoia would not have happened without it.
 344 .P
 345 Joerg Schilling has also contributed SCSI expertise through his
 346 generic SCSI transport library.
 347 .P
 348 .SH AUTHOR
 349 Monty <monty@xiph.org>
 350 .P
 351 Cdparanoia's homepage may be found at:
 352 http://www.xiph.org/paranoia/