From bb1bb5113dedc44424d006caa8c9736508ccf69d Mon Sep 17 00:00:00 2001 From: rocky Date: Tue, 11 Jan 2005 04:00:26 +0000 Subject: [PATCH] doc: add some paranoia documentation. src: Cleaner way to get usage and allow it to be customized to a particular name configure.ac: add --with-cd-paranoia-name to allow customization of the cd-paranoia name. More work is needed to get the binary renamed. --- configure.ac | 11 +- include/cdio/paranoia.h | 6 +- src/cd-paranoia/.cvsignore | 2 + src/cd-paranoia/Makefile.am | 18 +- src/cd-paranoia/cd-paranoia.c | 136 +------ src/cd-paranoia/doc/FAQ.txt | 620 +++++++++++++++++++++++++++++ src/cd-paranoia/doc/overlapdef.txt | 18 + src/cd-paranoia/pod2c.pl | 44 ++ src/cd-paranoia/usage.txt.in | 119 ++++++ 9 files changed, 836 insertions(+), 138 deletions(-) create mode 100644 src/cd-paranoia/doc/FAQ.txt create mode 100644 src/cd-paranoia/doc/overlapdef.txt create mode 100755 src/cd-paranoia/pod2c.pl create mode 100644 src/cd-paranoia/usage.txt.in diff --git a/configure.ac b/configure.ac index 5890352a..b171ebb8 100644 --- a/configure.ac +++ b/configure.ac @@ -1,4 +1,4 @@ -dnl Copyright (C) 2003, 2004 Rocky Bernstein +dnl Copyright (C) 2003, 2004, 2005 Rocky Bernstein dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -19,7 +19,7 @@ define(RELEASE_NUM, 72) define(CDIO_VERSION_STR, 0.$1cvs) AC_PREREQ(2.52) -AC_REVISION([$Id: configure.ac,v 1.126 2005/01/08 20:39:40 rocky Exp $])dnl +AC_REVISION([$Id: configure.ac,v 1.127 2005/01/11 04:00:26 rocky Exp $])dnl AC_INIT(libcdio, CDIO_VERSION_STR(RELEASE_NUM)) AC_CONFIG_SRCDIR(src/cd-info.c) AM_INIT_AUTOMAKE @@ -48,6 +48,12 @@ AC_ARG_WITH(cd_paranoia, [ --without-cd-paranoia build program cd-paranoia (enabled by default)], enable_cd_paranoia="${withval}", enable_cd_paranoia=yes) +AC_ARG_WITH(cd_paranoia_name, +[ --with-cd-paranoia-name name to use as the cd-paranoia program name (default cd-paranoia)], +cd_paranoia_name="${withval}", cd_paranoia_name="cd-paranoia") +CDPARANOIA_NAME="$cd_paranoia_name" +AC_SUBST(CDPARANOIA_NAME) + AC_ARG_WITH(cd_read, [ --without-cd-read build program cd-read (enabled by default)], enable_cd_read="${withval}", enable_cd_read=yes) @@ -527,6 +533,7 @@ AC_CONFIG_FILES([ \ lib/iso9660/Makefile \ lib/paranoia/Makefile \ src/cd-paranoia/Makefile \ + src/cd-paranoia/usage.txt \ src/Makefile \ test/check_nrg.sh \ test/check_cue.sh \ diff --git a/include/cdio/paranoia.h b/include/cdio/paranoia.h index 274bb8a0..ec3696ef 100644 --- a/include/cdio/paranoia.h +++ b/include/cdio/paranoia.h @@ -1,5 +1,5 @@ /* - $Id: paranoia.h,v 1.1 2004/12/18 17:29:32 rocky Exp $ + $Id: paranoia.h,v 1.2 2005/01/11 04:00:26 rocky Exp $ Copyright (C) 2004 Rocky Bernstein Copyright (C) 1998 Monty xiphmont@mit.edu @@ -49,6 +49,10 @@ typedef struct cdrom_paranoia_s cdrom_paranoia_t; typedef struct cdrom_drive_s cdrom_drive_t; +/** For compatibility. cdrom_drive_t is depricated, use cdrom_drive_t instead. */ +#define cdrom_drive cdrom_drive_t + + typedef enum { PARANOIA_CB_READ, PARANOIA_CB_VERIFY, diff --git a/src/cd-paranoia/.cvsignore b/src/cd-paranoia/.cvsignore index 0a0bb169..f0f4549f 100644 --- a/src/cd-paranoia/.cvsignore +++ b/src/cd-paranoia/.cvsignore @@ -4,3 +4,5 @@ Makefile Makefile.in *.o cd-paranoia +usage.h +usage.txt diff --git a/src/cd-paranoia/Makefile.am b/src/cd-paranoia/Makefile.am index 7546c2b4..88413d66 100644 --- a/src/cd-paranoia/Makefile.am +++ b/src/cd-paranoia/Makefile.am @@ -1,4 +1,4 @@ -# $Id: Makefile.am,v 1.4 2005/01/06 11:39:40 rocky Exp $ +# $Id: Makefile.am,v 1.5 2005/01/11 04:00:26 rocky Exp $ # # Copyright (C) 2004, 2005 Rocky Bernstein # Copyright (C) 1998 Monty xiphmont@mit.edu @@ -24,20 +24,32 @@ else getopt_sources = getopt.c getopt1.c endif +EXTRA_DIST = $(man_MANS) getopt.c getopt1.c \ + usage.txt.in pod2c.pl \ + doc/FAQ.txt doc/overlapdef.txt + noinst_HEADERS = getopt.h header.h report.h if BUILD_CD_PARANOIA cd_paranoia_SOURCES = cd-paranoia.c \ buffering_write.c buffering_write.h \ - $(getopt_sources) header.c report.c + $(getopt_sources) header.c report.c usage.h cd_paranoia_LDADD = $(LIBCDIO_LIBS) $(LIBCDIO_CDDA_LIBS) $(LIBCDIO_PARANOIA_LIBS) bin_PROGRAMS = cd-paranoia man_MANS = cd-paranoia.1 cd-paranoia.1.jp -EXTRA_DIST = $(man_MANS) $(getopt_sources) INCLUDES = -I$(top_srcdir) $(LIBCDIO_CFLAGS) + +# These are the implict rules we've got here. +SUFFIXES = .txt .h + +.txt.h: $(srcdir)/pod2c.pl + $(PERL) $(srcdir)/pod2c.pl $< >$@ + endif +MOSTLYCLEANFILES = usage.h usage.txt + diff --git a/src/cd-paranoia/cd-paranoia.c b/src/cd-paranoia/cd-paranoia.c index b98f7108..f8da5657 100644 --- a/src/cd-paranoia/cd-paranoia.c +++ b/src/cd-paranoia/cd-paranoia.c @@ -50,17 +50,6 @@ # include "config.h" #endif -/* Give folks a way to choose what this program is to be called. - Some may want to use "cdparanoia", especially there is no other - program arround, since that name is what applications tend to use, - - Others may want to have both programs around, so the default below - is suggested. - */ -#ifndef PROGRAM_NAME -#define PROGRAM_NAME "cd-paranoia" -#endif - #ifdef HAVE_STDIO_H # include #endif @@ -299,127 +288,10 @@ display_toc(cdrom_drive_t *d) report(""); } -static void usage(FILE *f){ - fprintf( f, -PARANOIA_VERSION"\n" - -"USAGE:\n" -" %s [options] [outfile]\n\n" - -"OPTIONS:\n" -" -v --verbose : extra verbose operation\n" -" -q --quiet : quiet operation\n" -" -e --stderr-progress : force output of progress information to\n" -" stderr (for wrapper scripts)\n" -" -V --version : print version info and quit\n" -" -Q --query : autosense drive, query disc and quit\n" -" -B --batch : 'batch' mode (saves each track to a\n" -" seperate file.\n" -" -s --search-for-drive : do an exhaustive search for drive\n" -" -h --help : print help\n\n" - -" -p --output-raw : output raw 16 bit PCM in host byte \n" -" order\n" -" -r --output-raw-little-endian : output raw 16 bit little-endian PCM\n" -" -R --output-raw-big-endian : output raw 16 bit big-endian PCM\n" -" -w --output-wav : output as WAV file (default)\n" -" -f --output-aiff : output as AIFF file\n" -" -a --output-aifc : output as AIFF-C file\n\n" - -" -c --force-cdrom-little-endian : force treating drive as little endian\n" -" -C --force-cdrom-big-endian : force treating drive as big endian\n" -" -n --force-default-sectors : force default number of sectors in read\n" -" to n sectors\n" -" -o --force-search-overlap : force minimum overlap search during\n" -" verification to n sectors\n" -" -d --force-cdrom-device : use specified device; disallow \n" -" autosense\n" -" -g --force-generic-device : use specified generic scsi device\n" -" -S --force-read-speed : read from device at specified speed\n" -" -t --toc-offset : Add sectors to the values reported\n" -" when addressing tracks. May be negative\n" -" -T --toc-bias : Assume that the beginning offset of \n" -" track 1 as reported in the TOC will be\n" -" addressed as LBA 0. Necessary for some\n" -" Toshiba drives to get track boundaries\n" -" correct\n" -" -O --sample-offset : Add samples to the offset when\n" -" reading data. May be negative.\n" -" -z --never-skip[=n] : never accept any less than perfect\n" -" data reconstruction (don't allow 'V's)\n" -" but if [n] is given, skip after [n]\n" -" retries without progress.\n" -" -Z --disable-paranoia : disable all paranoia checking\n" -" -Y --disable-extra-paranoia : only do cdda2wav-style overlap checking\n" -" -X --abort-on-skip : abort on imperfect reads/skips\n\n" - -"OUTPUT SMILIES:\n" -" :-) Normal operation, low/no jitter\n" -" :-| Normal operation, considerable jitter\n" -" :-/ Read drift\n" -" :-P Unreported loss of streaming in atomic read operation\n" -" 8-| Finding read problems at same point during reread; hard to correct\n" -" :-0 SCSI/ATAPI transport error\n" -" :-( Scratch detected\n" -" ;-( Gave up trying to perform a correction\n" -" 8-X Aborted (as per -X) due to a scratch/skip\n" -" :^D Finished extracting\n\n" - -"PROGRESS BAR SYMBOLS:\n" -" No corrections needed\n" -" - Jitter correction required\n" -" + Unreported loss of streaming/other error in read\n" -" ! Errors are getting through stage 1 but corrected in stage2\n" -" e SCSI/ATAPI transport error (corrected)\n" -" V Uncorrected error/skip\n\n" - -"SPAN ARGUMENT:\n" -"The span argument may be a simple track number or a offset/span\n" -"specification. The syntax of an offset/span takes the rough form:\n\n" - -" 1[ww:xx:yy.zz]-2[aa:bb:cc.dd] \n\n" - -"Here, 1 and 2 are track numbers; the numbers in brackets provide a\n" -"finer grained offset within a particular track. [aa:bb:cc.dd] is in\n" -"hours/minutes/seconds/sectors format. Zero fields need not be\n" -"specified: [::20], [:20], [20], [20.], etc, would be interpreted as\n" -"twenty seconds, [10:] would be ten minutes, [.30] would be thirty\n" -"sectors (75 sectors per second).\n\n" - -"When only a single offset is supplied, it is interpreted as a starting\n" -"offset and ripping will continue to the end of he track. If a single\n" -"offset is preceeded or followed by a hyphen, the implicit missing\n" -"offset is taken to be the start or end of the disc, respectively. Thus:\n\n" - -" 1:[20.35] Specifies ripping from track 1, second 20, sector 35 to \n" -" the end of track 1.\n\n" - -" 1:[20.35]- Specifies ripping from 1[20.35] to the end of the disc\n\n" - -" -2 Specifies ripping from the beginning of the disc up to\n" -" (and including) track 2\n\n" - -" -2:[30.35] Specifies ripping from the beginning of the disc up to\n" -" 2:[30.35]\n\n" - -" 2-4 Specifies ripping from the beginning of track two to the\n" -" end of track 4.\n\n" - -"Don't forget to protect square brackets and preceeding hyphens from\n" -"the shell...\n\n" -"A few examples, protected from the shell:\n" -" A) query only with exhaustive search for a drive and full reporting\n" -" of autosense:\n" -" %s -vsQ\n\n" -" B) extract up to and including track 3, putting each track in a seperate\n" -" file:\n" -" %s -B -- \"-3\"\n\n" -" C) extract from track 1, time 0:30.12 to 1:10.00:\n" -" %s \"1[:30.12]-1[1:10]\"\n\n" - -"Submit bug reports to bug-libcdio@gnu.org\n\n", - PROGRAM_NAME, PROGRAM_NAME, PROGRAM_NAME, PROGRAM_NAME -); +#include "usage.h" +static void usage(FILE *f) +{ + fprintf( f, usage_help); } long callbegin; diff --git a/src/cd-paranoia/doc/FAQ.txt b/src/cd-paranoia/doc/FAQ.txt new file mode 100644 index 00000000..5a099d73 --- /dev/null +++ b/src/cd-paranoia/doc/FAQ.txt @@ -0,0 +1,620 @@ + +CDDA Paranoia FAQ + +---------------------------------------------------------------------------- + + "Suspicion Breeds Confidence!" + --Brazil + +---------------------------------------------------------------------------- + +August 20, 1999 + +For those new to Paranoia and cdparanoia, this is the +best, first place to look for information and answers to +your questions. + +More information can be found on the cdparanoia homepage: + +http://www.xiph.org/paranoia/ + +---------------------------------------------------------------------------- +Table of Contents + +1. Questions about the Paranoia and cdparanoia projects + 1. What is cdparanoia? + 2. Why use cdparanoia? + 3. What is Paranoia? + 4. Is cdparanoia / Paranoia portable? + 5. What is Paranoia's history? + 6. Is cdparanoia/Paranoia related to cdda2wav? + 7. What are the differences between Paranoia II, III and IV? + 8. Are there cdparanoia mailing lists for users or developers? + 9. What is Paranoia IV's current development status? + 10. Will cdparanoia, and cdda2wav or xcdroast merge anytime in the future? + +2. Questions about using Paranoia and cdparanoia + 1. Requirements to run cdparanoia (as of alpha 3) + 2. Does Cdparanoia support ATAPI drives? SCSI Emulation? Parallel port + drives? + 3. I can play audio CDs perfectly; why is reading the CD into a file so + difficult and prone to errors? + 4. Does cdparanoia lose quality from the CD recording? + 5. Can cdparanoia detect pregaps? Can it remove the two second gaps + between tracks? + 6. Why don't you implement CDDB? A GUI? Four million other features I want? + 7. The progress meter: What is that weird bargraph during ripping? + 8. How can I tell if my drive would be OK with regular cdda2wav? + 9. What is the biggest value of SG_BIG_BUFF I can use? + 10. Why do the binary files from two reads differ when compared? + 11. Why does CDParanoia rip files off into WAV format (and other sample + formats) but not CDDA format? + +------------------------------------------------------------------------- + + Questions about the Paranoia and cdparanoia projects + + What is cdparanoia? + + Cdparanoia is a Compact Disc Digital Audio (CDDA) extraction tool, + commonly known on the net as a 'ripper'. The application is built on + top of the Paranoia library, which is doing the real work (the + Paranoia source is included in the cdparanoia source distribution). + Like the original cdda2wav, cdparanoia package reads audio from the + CDROM directly as data, with no analog step between, and writes the + data to a file or pipe in WAV, AIFC or raw 16 bit linear PCM. + + Cdparanoia is a bit different than most other CDDA extration tools. It + contains few-to-no 'extra' features, concentrating only on the ripping + process and knowing as much as possible about the hardware performing + it. Cdparanoia will read correct, rock-solid audio data from + inexpensive drives prone to misalignment, frame jitter and loss of + streaming during atomic reads. Cdparanoia will also read and repair + data from CDs that have been damaged in some way. + + At the same time, however, cdparanoia turns out to be easy to use and + administrate; It has no compile time configuration, happily + autodetecting the CDROM, its type, its interface and other aspects of + the ripping process at runtime. A single binary can serve the diverse + hardware of the do-it-yourself computer laboratory from Hell... + +----------------------------------------------------------------------- + + Why use cdparanoia? + + All CDROM drives are not created equal. You'll need cdparanoia if + yours is a little less equal than others-- or maybe you just keep your + CD collection in a box of full of gravel. Jewel cases are for wimps; + you know what I'm talking about. + + Unfortunately, cdda2wav and readcdda cannot work properly with a large + number of CDROM drives in the desktop world today. The most common + problem is sporadic or regular clicks and pops in the read sample, + regardless of 'nsector' or 'overlap' settings. Cdda2wav also cannot do + anything about scratches (and they can cause cdda2wav to break). + Cdparanoia is also smarter about probing CDDA support from SCSI and + IDE-SCSI drives; many drives that do not work at all with cdda2wav, + readcdda, tosha, etc, will work just fine with cdparanoia. + +----------------------------------------------------------------------- + + What is Paranoia? + + Paranoia is a library project that provides a platform independent, + unified, robust interface for packet-command based devices. In the + case of CDROM drives for example, handling and programming cdrom + drives becomes identical whether on Solaris or Linux, or if the Linux + drive is SCSI, ATAPI or on the parallel port. In this way, Paranoia is + similar to Joerg Schilling's SCG library. + + In addition to device/platform unification, the library provides tools + for automatically identifying devices, and intelligent + handling/correction of errors at all levels of the interface. On top + of a generic low-level packet command layer, Paranoia implements + high-level error-correcting interfaces for tasks such as CDDA where + broken or vastly non-standard devices are the rule, rather than the + exception. + + The Paranoia libraries are incomplete; the first release for use will + be Paranoia IV, to be bundled with cdparanoia alpha release 10. + Programming documentation for Paranoia IV will appear shortly on the + documentation page as Programming with Paranoia IV. Programmers + interested in contributing to Paranoia IV should read the heading + Paranoia IV development information. + +----------------------------------------------------------------------- + + Is cdparanoia / Paranoia portable? + + Paranoia III is Linux only (although it runs on all the flavors of + linux with a 2.0 or later kernel. It is not only for x86). + + Paranoia IV (cdparanoia alpha 10 and later) is a port to other UNIX + flavors and uses a substantially revised infrastructure. NetBSD and + Solaris will be first; others will be added as time and outside + assistance allow. + + Suggestions on the proper way to handle each OS's native configuration + idioms are welcome. I want Rhapsody cdparanoia to look just like other + Rhapsody apps just as much as I want Linux cdparanoia to look like a + Linux app. + +----------------------------------------------------------------------- + + What is Paranoia's history? + + Is cdparanoia/Paranoia related to cdda2wav? + + Paranoia I/II and cdparanoia began life as a set of patches to Heiko + Eissfeldt's 'cdda2wav' application. Cdparanoia gained its own life as + a rewrite of cdda2wav in January of 1998 as "Paranoia III". Paranoia + III proved to have an inadequate structure for extention and use on + other platforms, so Paranoia IV began to take form in fall of 1998. + + Modern Paranoia no longer has any relation to cdda2wav aside from + general cooperation in sharing details between the two projects. In + fact, cdda2wav itself doesn't look much like the cdda2wav of a year or + two ago. + +----------------------------------------------------------------------- + + What are the differences between Paranoia II, III and IV? + + Paranoia I and II were a set of patches to Heiko Eissfeldt's cdda2wav + 0.8. These patches did nothing more than add some error checks to the + standard cdda2wav. They were inefficient and only worked with some + drives. + + Paranoia III was the first version to be written seperately from + cdda2wav in the form of a standalone library. It was not terribly + portable, however, and the API proved to be inadequate for extension. + + Paranoia IV is the upcoming new generation of CDDA Paranoia. It is + both portable and more capable than Paranoia III. + +----------------------------------------------------------------------- + + Are there cdparanoia mailing lists for users or developers? + + Yes. In addition to the mailing lists below, read-only CVS access to + Paranoia III and IV will be availble from xiph.org soon (Paranoia IV + is not yet under CVS). See http://www.xiph.org/paranoia/ for upto + date information and automated ways of subscribing. + + Mailing list for Paranoia and Cdparanoia users (paranoia@xiph.org): + + To join: send a message containing only the one-word line + 'subscribe' in the body to paranoia-request@xiph.org. Do not send + subscription requests directly to the main list. The list server at + xiph.org should respond fairly quickly with a welcome message. + + Mailing list for Paranoia IV developers: paranoia-dev@xiph.org + + The developers list is intended for focused development discussion + amongst the core Paranoia development team and outside groups + developing their own applications using Paranoia. Of course, anyone is + welcome to read. + + To join: send a message containing only the one-word line + 'subscribe' in the body to paranoia-dev-request@xiph.org. Do not + send subscription requests directly to the main list. + + List for general CDROM tools + + There's also a general mailing list for those using/developing CDDA + extraction and CD writing tools + (cdwrite@other.debian.org). Subscribe by sending mail to + other-cdwrite-request@lists.debian.org containing only the word + subscribe in the body. Do not send subscription requests directly to + the main list. + +----------------------------------------------------------------------- + + What is Paranoia IV's current development status? + + Paranoia IV code will soon be available for internal evaluation, + testing and development work to the developers involved in the + Paranoia project; read-only CVS access should also be available soon. + A public release does not yet set for any firm date. + + Those interested in contributing to the development of Paranoia, or + who wich to contribute to porting to other platforms, please contact + us. Paranoia IV prerelease code will be available to porters soon; I + prefer to be in contact with those porting to other platforms so that + Paranoia development has consistent quality across platforms. + + At the moment, volunteers have contacted me for most major platforms, + but more help is still welcome on every OS. + +----------------------------------------------------------------------- + + Will cdparanoia, and cdda2wav or xcdroast merge anytime in the future? + + Probably not beyond the point it already has. Versions of XCDRoast + (and other GUI frontends; see the links page) that make use of + cdparanoia already exist. + + Although the cdrecord/cdda2wav and Paranoia projects cooperate, + they're likely to remain seperate as the former is committed to Joerg + Schilling's libscg (part of the cdrecord package), just as cdparanoia + is committed to using Paranoia IV. + +----------------------------------------------------------------------- + + Questions about using Paranoia and cdparanoia + + Requirements to run cdparanoia (as of alpha 3) + + 1. A CDDA capable CDROM drive + 2. Linux 2.0, 2.1, 2.2 or 2.3 + 1. kernel support for the particular CDROM in use + 2. kernel support for the generic SCSI interface (if using a + SCSI CDROM drive) and proper device (/dev/sg?) files (get + them with the MAKEDEV script) in /dev. Most distributions + already have the /dev/sg? files. + + The cdparanoia binary will likely work with Linux 1.2 and 1.3, but I + do not actively support kernels older than 2.0 I do know for a fact + that the source will not build on kernel installs older than 2.0, but + the problems are mostly related to the ever-changing locations of + proprietary cdrom include files. + + Also, although a 2.0 stock SCSI setup will work, performance will be + better if linux/include/scsi/sg.h defines SG_BIG_BUFF to 65536 (it + can't be bigger). Recent kernels (2.0.30+?) already set it to 32768; + that's OK. Cdparanoia will tell you how big your generic SCSI buffer + is. 2.2+ does not use a static DMA pool for SG, so there is nothing + to tune. + + Unlike cdda2wav, cdparanoia does not require threading, IPC or + (optionally) sound card support. /proc filesystem support is no longer + required (but encouraged!), and /dev/sr? or /dev/scd? devices are not + required for SCSI, although they do add functionality if present. + +----------------------------------------------------------------------- + + Does Cdparanoia support ATAPI drives? SCSI Emulation? Parallel port + drives? + + Alpha 9 supports the full ATAPI, IDE-SCSI and SCSI generic interfaces + under Linux. + + Note that the native ATAPI driver is supported, but that IDE-SCSI + emulation works better with ATAPI drives. This is an issue of control; + the emulation interface gives cdparanoia complete control over the + drive whereas the native ATAPI driver insists on hiding the device + under an abstraction layer with poor error handling capabilities. Note + also that a number of ATAPI drives that do not work at all with the + ATAPI driver (error 006: Could not read audio) *will* work with + IDE-SCSI emulation. + + Parallel port based CDROM (paride) drives are not yet supported; + support for these drives in Linux will appear in alpha release 10 + (Paranoia IV). + +----------------------------------------------------------------------- + + I can play audio CDs perfectly; why is reading the CD into a file so + difficult and prone to errors? It's just the same thing. + + Unfortunately, it isn't that easy. + + The audio CD is not a random access format. It can only be played from + some starting point in sequence until it is done, like a vinyl LP. + Unlike a data CD, there are no synchronization or positioning headers + in the audio data (a CD, audio or data, uses 2352 byte sectors. In a + data CD, 304 bytes of each sector is used for header, sync and error + correction. An audio CD uses all 2352 bytes for data). The audio CD + *does* have a continuous fragmented subchannel, but this is only good + for seeking +/-1 second (or 75 sectors or ~176kB) of the desired area, + as per the SCSI spec. + + When the CD is being played as audio, it is not only moving at 1x, the + drive is keeping the media data rate (the spin speed) exactly locked + to playback speed. Pick up a portable CD player while it's playing and + rotate it 90 degrees. Chances are it will skip; you disturbed this + delicate balance. In addition, a player is never distracted from what + it's doing... it has nothing else taking up its time. Now add a + non-realtime, (relatively) high-latency, multitasking kernel into the + mess; it's like picking up the player and constantly shaking it. + + CDROM drives generally assume that any sort of DAE will be linear and + throw a readahead buffer at the task. However, the OS is reading the + data as broken up, seperated read requests. The drive is doing + readahead buffering and attempting to store additional data as it + comes in off media while it waits for the OS to get around to reading + previous blocks. Seeing as how, at 36x, data is coming in at + 6.2MB/second, and each read is only 13 sectors or ~30k (due to DMA + restrictions), one has to get off 208 read requests a second, minimum + without any interruption, to avoid skipping. A single swap to disc or + flush of filesystem cache by the OS will generally result in loss of + streaming, assuming the drive is working flawlessly. Oh, and virtually + no PC on earth has that kind of I/O throughput; a Sun Enterprise + server might, but a PC does not. Most don't come within a factor of + five, assuming perfect realtime behavior. + + To keep piling on the difficulties, faster drives are often prone to + vibration and alignment problems; some are total fiascos. They lose + streaming *constantly* even without being interrupted. Philips + determined 15 years ago that the CD could only be spun up to 50-60x + until the physical CD (made of polycarbonate) would deform from + centripetal force badly enough to become unreadable. Today's players + are pushing physics to the limit. Few do so terribly reliably. + + Note that CD 'playback speed' is an excellent example of advertisers + making numbers lie for them. A 36x cdrom is generally not spinning at + 36x a normal drive's speed. As a 1x drive is adjusting velocity + depending on the access's distance from the hub, a 36x drive is + probably using a constant angular velocity across the whole surface + such that it gets 36x max at the edge. Thus it's actually spinning + slower, assuming the '36x' isn't a complete lie, as it is on some + drives. + + Because audio discs have no headers in the data to assist in picking + up where things got lost, most drives will just guess. + + This doesn't even *begin* to get into stupid firmware bugs. Even + Plextors have occasionally had DAE bugs (although in every case, + Plextor has fixed the bug *and* replaced/repaired drives for free). + Cheaper drives are often complete basket cases. + + Rant Update (for those in the know): + + Several folks, through personal mail and on Usenet, have pointed out + that audio discs do place absolute positioning information for (at + least) nine out of every ten sectors into the Q subchannel, and that + my original statement of +/-75 sectors above is wrong. I admit to it + being misleading, so I'll try to clarify. + + The positioning data certainly is in subchannel Q; the point is moot + however, for a couple of reasons. + + 1. The SCSI and ATAPI specs (there are a couple of each, pick one) + don't give any way to retrieve the subchannel from a desired + sector. The READ SUB-CHANNEL command will hand you Q all right, + you just don't have any idea where exactly that Q came from. The + command was intended for getting rough positioning information + from audio discs that are paused or playing. This is audio; + missing by several sectors is a tiny fraction of a second. + + 2. Older CDROM drives tended not to expect 'READ SUB-CHANNEL' unless + the drive was playing audio; calling it during data reads could + crash the drive and lock up the system. I had one of these drives + (Apple 803i, actually a repackaged Sony CD-8003). + + 3. MMC-2 *does* give a way to retrieve the Q subchannel along with + user data in the READ CD command. Although the drive is required + to recognize the fetaure, it is allowed to simply return zeroes + (effectively leaving the feature unimplemented). Guess how many + drives actually implement this feature: not many. + + 4. Assuming you *can* get back the subchannel, most CDROM drives + seem to understand audio discs primarily at the "little frame" + level; thus sector-level structures aren't reliable. One might + get a reassembled subQ, but if the read began in the middle of a + sector (or dropped a little frame in the middle; many do), the + subQ is likely corrupt and useless. + + As reassembling uncorrupted frames is easy without the subchannel, and + corrupted reads likely result in a corrupted subchannel too, + cdparanoia treats the subchannel as more trouble than it's worth + (during verification). + + At least one other package (Exact Audio Copy for Win32) manages to use + the subchannel to enhance the Table of Contents information. I don't + know if this only works on MMC-2 drives that support returning Q with + READ CD, but I think I'm going to revisit using the subchannel for + extra TOC information. + +----------------------------------------------------------------------- + + Does cdparanoia lose quality from the CD recording? Does it just + re-record the analog signal played from the CDROM drive? + + No to both. Cdparanoia (and all other true CD digital audio extraction + tools) reads the values off the CDROM in digital form. The data never + comes anywhere near the soundcard, and does not pass through any + conversion to analog first. + +----------------------------------------------------------------------- + + Can cdparanoia detect pregaps? Can it remove the two second gaps + between tracks + + Not yet. This feature is slated to appear in a release of alpha 10 + (Paranoia IV). + +----------------------------------------------------------------------- + + Why don't you implement CDDB? A GUI? Four million other features I + want? + + Too many features spoil the broth. "Software is not perfect when there + is nothing left to add, but rather when there is nothing extraneous + left to take away." The goal of cdparanoia is perfect, rock-solid + audio from every capable cdrom on every platform. As this goal has not + yet been met, I'm uninterested in adding unrelated capability to the + core engine. + + Several GUIs that incorporate cdparanoia already exist; I'm in the + process of compiling a list (see the links page). Other software that + implements new features by wrapping around cdpar anoia (like CDDB + lookup) also exist. + + 'Cdparanoia' will not play to sound cards (you can always pipe the + output to a WAV player), do MD5 signatures, read CD catalog or serial + numbers (this *is* a feature I plan to add), search indexes, do rate + reduction (use Sox, Ogg or a million others), or generally make use of + the maximum speed available from a CDROM drive. + + If your CDROM drive is *not* prone to jitter and you don't have + scratched discs to worry about, you might want to look at the original + cdda2wav for features cdparanoia does not have. Keep in mind however + that even the really good drives do occasionally stumble. I know of at + least one cdparanoia user who insists on using full paranoia with his + Plextor UltraPlex because it once botched a single sector from a rip; + he'd already burned the track to several CD-Rs before noticing... + +----------------------------------------------------------------------- + + The progress meter: What is that weird bargraph during ripping? + + It's a progress/status indicator. There's a completion bargraph, a + number indicating the last sector number completely verified of the + read currently happening, an overlap indicator, a gratuitous smilie, + and a heartbeat indicator to show if the process is still alive, hung, + or spinning. + + The bargraph also marks points during the read with characters to + indicate where various 'paranoia' features were tripped into action. + Different bargraph characters indicate different things occurred + during that part of the read. The letters are heirarchical; for + example if a trasport error occurs in the same sector as jitter, the + bargraph will print 'e' instead of '-'. + + Legend of + characters + A hyphen indicates that two blocks overlapped properly, + - but they were skewed (frame jitter). This case is + completely corrected by Paranoia and is not a cause for + concern. + A plus indicates not only frame jitter, but an + unreported, uncorrected loss of streaming in the middle + + of an atomic read operation. That is, the drive lost + its place while reading data, and restarted in some + random incorrect location without alerting the kernel. + This case is also corrected by Paranoia. + An 'e' indicates that a transport level SCSI or ATAPI + e error was caught and corrected. Paranoia will + completely repair such an error without audible + defects. + An "X" indicates a scratch was caught and corrected. + X Cdparanoia wil interpolate over any missing/corrupt + samples. + An asterisk indicates a scratch and jitter both + * occurred in this general area of the read. Cdparanoia + wil interpolate over any missing/corrupt samples. + A ! indicates that a read error got through the stage + one of error correction and was caught by stage two. + Many '!' are a cause for concern; it means that the + drive is making continuous silent errors that look + ! identical on each re-read, a condition that can't + always be detected. Although the presence of a '!' + means the error was corrected, it also means that + similar errors are probably passing by unnoticed. + Upcoming releases of cdparanoia will address this + issue. + A V indicates a skip that could not be repaired or a + V sector totally obliterated on the medium (hard read + error). A 'V' marker generally results in some audible + defect in the sample. + + The smilie is actually relevant. It makes different faces depending on + the current errors it's correcting. + + Legend of + smilies + + :-) Normal operation. No errors to report; if any jitter is + present, it's small. + :-| Normal operation, but average jitter is quite large. + A rift was found in the middle of an atomically read + block; in other words, the drive lost streaming in the + :-P middle of a read and did not abort, alert the kernel , or + restart in the proper location. The drive silently + continued reading in so me random location. + + :-/ The read appears to be drifting; cdparanoia is shifting + all of its reads to make up for it. + Two matching vectors were found to disagree even after + first stage verification; this is an indication that the + drive is reliably dropping/adding bytes at consistent + locations. Because the verification algorithm is partially + 8-| based on rereading and comparing vectors, if two vectors + read incorrectly but identically, cdparanoia may never + detect the problem. This smilie indicates that such a + situation *was* detected; other instances may be slipping + through. + Transport or drive error. This is normally not a cause for + concern; cdparanoia can repair just about any error that + :-0 it actually detects. For more information about these + errors, run cdparanoia with the -v option. Any all all + errors and a description will dump to stderr. + :-( Cdparanoia detected a scratch. + Cdparanoia gave up trying to repair a sector; it could not + read consistent enough information from the drive to do + ;-( so. At this point cdparanoia will make the best guess it + has available and continue (a V appears in the bargraph at + this point). This often results in an audible defect. + Cdparanoia displays this smilie both when finished reading + :^D a track and also if no error correction mechanism has been + tripped so far reading a new track. + +----------------------------------------------------------------------- + + How can I tell if my drive would be OK with regular cdda2wav? + + Easy. Run cdparanoia; if the progress meter never shows any characters + but the little arrow going across the screen, the CDROM drive is + probably one of the (currently) few drives that can read a pristine + stream of data off an audio disc regardless of circumstances. This + drive will work quite well with cdda2wav (or cdparanoia using the '-Z' + option) + + A drive that results in a bargraph of all hyphens would *likely* work + OK with cdda2wav, but it's less certain. + + Any other characters in the bargraph (colons, semicolons, pluses, Xs, + etc..) indicate that a fixups had to be performed at that point during + the read; that read would have failed or 'popped' using cdda2wav. + +----------------------------------------------------------------------- + + What is the biggest value of SG_BIG_BUFF I can use? + + This is relevant only to 2.0 kernels and early 2.2 kernels. + Modern Linux kernels no longer have a single static SG DMS pool. + + For 2.0, 65536 (64 kilobytes). Some motherboards can use 128kB + DMA, but attempting to use 128kB DMA on a machine that can't do + it will crash the machine. Cdparanoia will not use larger than + 64kB requests. + +----------------------------------------------------------------------- + + Why do the binary files from two reads differ when compared? + + The problem is the beginning point of the read. Cdparanoia enforces + consistency from whatever the drive considers to be the starting point + of the data, and the drive is returning a slightly different beginning + point each time. The beginning point should not vary by much, and if + this shift is accounted for when comparing the files, they should + indeed turn out to be the same (aside from errors duly reported during + the read; scratch correction or any reported skips will very likely + also result in different files). + +----------------------------------------------------------------------- + + Why do CDParanoia, CDDA2WAV et al. rip files off into WAV format (and + other sample formats) but not CDDA format? + + WAV and AIFC are simply convenient formats that include enough header + information such that multipurpose audio software can uniquely + identify the form of the data in the sample. In raw form, mulaw, SND + and CDDA look exactly alike to a program like xplay, and are very + likely to blow your ears (and stereo) out when played! Header formats + are more versatile and safer. By default, cdparanoia and cdda2wav + write WAV files. + + That said, cdparanoia (and cdda2wav) will write raw, headerless + formats if explicitly told to. Cdparanoia writes headerless, signed 16 + bit, 44.1kHz stero files in little endian format (LSB first) when + given the -r option, and the same in big endian (MSB) format when + given -R. All files written by cdparanoia are a multiple of 2352 bytes + long (minus the header, if any) as required by cd writer software. + + +Cdparanoia and the Laser-Playback-Head-of-Omniscience logo are +trademarks (tm) of Xiphophorus (xiph.org). This document copyright (C) +1994-1999 Xiphophorus. All rights reserved. Comments and questions +are welcome. diff --git a/src/cd-paranoia/doc/overlapdef.txt b/src/cd-paranoia/doc/overlapdef.txt new file mode 100644 index 00000000..be51ffa0 --- /dev/null +++ b/src/cd-paranoia/doc/overlapdef.txt @@ -0,0 +1,18 @@ + 0 70 100 +A |----------|-----| +B |-----|---------| + 0 40 100 + +offset=-30 +begin=30 +end=100 + + 0 70 100 +A |----------|-----| +B |-----|---------| + 50 90 150 + +offset=20 +begin=30 +end=100 + diff --git a/src/cd-paranoia/pod2c.pl b/src/cd-paranoia/pod2c.pl new file mode 100755 index 00000000..a6c56fbf --- /dev/null +++ b/src/cd-paranoia/pod2c.pl @@ -0,0 +1,44 @@ +#!/usr/bin/perl +# $Id: pod2c.pl,v 1.1 2005/01/11 04:00:26 rocky Exp $ +# Utility to turn pieces of pod text to help text. +use File::Basename; + +die "Expecting exactly one argument, a filename" if @ARGV != 1; +$filename = shift; + +($name, $path, $suffix)=fileparse($filename,"\.txt"); +close(STDIN); +open(STDIN, "<$filename") + || die "Can't open $filename for reading:\n$!"; + +#$outfile="../${filename}.h"; +#open(STDOUT, ">$outfile") +# || die "Can't open $outfile for writing:\n$!"; + +print "/* + Copyright (C) 1999, 2005 Rocky Bernstein + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +*/ +const char ${name}_help[] =\n"; +while() { + s/["]/\\"/g; + # Change POD'ed items to quoted items, e.g. See L and L becomes + # See "y" and "z" (with \'s around the quotes) + s/[C,L,I,B,F]<(.+?)>/\\"$1\\"/g; + chomp; + print "\"$_\\n\"\n"; +} +print ";\n"; diff --git a/src/cd-paranoia/usage.txt.in b/src/cd-paranoia/usage.txt.in new file mode 100644 index 00000000..e853c777 --- /dev/null +++ b/src/cd-paranoia/usage.txt.in @@ -0,0 +1,119 @@ +USAGE: + @CDPARANOIA_NAME@ [options] [outfile] + +OPTIONS: + -v --verbose : extra verbose operation + -q --quiet : quiet operation + -e --stderr-progress : force output of progress information to + stderr (for wrapper scripts) + -V --version : print version info and quit + -Q --query : autosense drive, query disc and quit + -B --batch : 'batch' mode (saves each track to a + seperate file. + -s --search-for-drive : do an exhaustive search for drive + -h --help : print help + + -p --output-raw : output raw 16 bit PCM in host byte + order + -r --output-raw-little-endian : output raw 16 bit little-endian PCM + -R --output-raw-big-endian : output raw 16 bit big-endian PCM + -w --output-wav : output as WAV file (default) + -f --output-aiff : output as AIFF file + -a --output-aifc : output as AIFF-C file + + -c --force-cdrom-little-endian : force treating drive as little endian + -C --force-cdrom-big-endian : force treating drive as big endian + -n --force-default-sectors : force default number of sectors in read + to n sectors + -o --force-search-overlap : force minimum overlap search during + verification to n sectors + -d --force-cdrom-device : use specified device; disallow + autosense + -g --force-generic-device : use specified generic scsi device + -S --force-read-speed : read from device at specified speed + -t --toc-offset : Add sectors to the values reported + when addressing tracks. May be negative + -T --toc-bias : Assume that the beginning offset of + track 1 as reported in the TOC will be + addressed as LBA 0. Necessary for some + Toshiba drives to get track boundaries + correct + -O --sample-offset : Add samples to the offset when + reading data. May be negative. + -z --never-skip[=n] : never accept any less than perfect + data reconstruction (don't allow 'V's) + but if [n] is given, skip after [n] + retries without progress. + -Z --disable-paranoia : disable all paranoia checking + -Y --disable-extra-paranoia : only do cdda2wav-style overlap checking + -X --abort-on-skip : abort on imperfect reads/skips + +OUTPUT SMILIES: + :-) Normal operation, low/no jitter + :-| Normal operation, considerable jitter + :-/ Read drift + :-P Unreported loss of streaming in atomic read operation + 8-| Finding read problems at same point during reread; hard to correct + :-0 SCSI/ATAPI transport error + :-( Scratch detected + ;-( Gave up trying to perform a correction + 8-X Aborted (as per -X) due to a scratch/skip + :^D Finished extracting + +PROGRESS BAR SYMBOLS: + No corrections needed + - Jitter correction required + + Unreported loss of streaming/other error in read + ! Errors are getting through stage 1 but corrected in stage2 + e SCSI/ATAPI transport error (corrected) + V Uncorrected error/skip + +SPAN ARGUMENT: +The span argument may be a simple track number or a offset/span +specification. The syntax of an offset/span takes the rough form: + + 1[ww:xx:yy.zz]-2[aa:bb:cc.dd] + +Here, 1 and 2 are track numbers; the numbers in brackets provide a +finer grained offset within a particular track. [aa:bb:cc.dd] is in +hours/minutes/seconds/sectors format. Zero fields need not be +specified: [::20], [:20], [20], [20.], etc, would be interpreted as +twenty seconds, [10:] would be ten minutes, [.30] would be thirty +sectors (75 sectors per second). + +When only a single offset is supplied, it is interpreted as a starting +offset and ripping will continue to the end of he track. If a single +offset is preceeded or followed by a hyphen, the implicit missing +offset is taken to be the start or end of the disc, respectively. Thus: + + 1:[20.35] Specifies ripping from track 1, second 20, sector 35 to + the end of track 1. + + 1:[20.35]- Specifies ripping from 1[20.35] to the end of the disc + + -2 Specifies ripping from the beginning of the disc up to + (and including) track 2 + + -2:[30.35] Specifies ripping from the beginning of the disc up to + 2:[30.35] + + 2-4 Specifies ripping from the beginning of track two to the + end of track 4. + +Don't forget to protect square brackets and preceeding hyphens from +the shell... + +A few examples, protected from the shell: + A) query only with exhaustive search for a drive and full reporting + of autosense: + @CDPARANOIA_NAME@ -vsQ + + B) extract up to and including track 3, putting each track in a seperate + file: + @CDPARANOIA_NAME@ -B -- "-3" + + C) extract from track 1, time 0:30.12 to 1:10.00: + @CDPARANOIA_NAME@ "[:30.12]-1[1:10]" + +Submit bug reports to bug-libcdio@gnu.org +