Imported Upstream version 1.1.11upstream/1.1.11upstream

1 files changed, 549 insertions, 0 deletions

diff --git a/doc/icedax/README b/doc/icedax/README
new file mode 100644
index 0000000..4b65532
--- /dev/null
+++ b/doc/icedax/README
@@ -0,0 +1,549 @@
+Hi dear cdrom drive users,
+
+This README describes hardware related matters as well as the installation of 
+icedax, the sampling utility. 
+
+This icedax utility comes with the Cdrkit project. Cdrkit is a spinoff from 
+cdrtools. However, the cdrtools developers are not involved in the 
+development of this spinoff and therefore shall not be made responsible for 
+any problem caused by it. Please do not try to get support for this program by 
+contacting the original authors.
+
+Requirements
+============
+
+For SCSI cdroms and CD-writers, as well as SCSI-emulated ATAPIS and parallel
+    port drives
+1s. kernel support for SCSI, the host adapter, SCSI cdroms and the
+    generic SCSI interface (if under Linux). You need to have the proper device
+    descriptors (get them under Linux with the MAKEDEV script from /dev).
+
+For ATAPI cdroms under Linux
+1a. kernel support for the ATAPI cdrom driver or alternatively ide-scsi
+    emulation. You need to have the proper device descriptors (get them
+    with the MAKEDEV script from /dev).
+
+For parallel port cdroms under Linux
+    With newer kernels icedax uses the same parallel port access
+    as does wodim.  Please refer additionally to the wodim documentation.
+    There are generally two drivers to access the cdrom through the parallel
+    port: the ATAPI cd emulation (called pcd), and the SCSI device emulation
+    (called pg). The pcd driver does NOT support cdda reading (kernel 2.2.12),
+    while the pg driver has no restriction. So you have to use pg for that.
+
+
+For cdrom drives with proprietary busses under Linux
+1p. Please check the CDROM-HOWTO for features of the respective
+    drivers. The sbpcd driver is very demanding due to the lack of
+    interrupts.
+
+optionally currently for Solaris and all platforms running 4fronts
+OpenSoundSystems:
+2. kernel sound card support.
+
+
+Recommendations for higher throughput on Linux SCSI systems
+===========================================================
+
+Higher throughput will give better chances for non-interrupted
+sampling. This should avoid typical interruption errors (cracklings
+at buffer boundaries).
+
+1. Increase SG_BIG_BUFF to (128*1024) in /usr/src/linux/include/scsi/sg.h
+   (and recompile your kernel and boot it :-).
+NOTE: Some kernel configurations will lead to 'out of kernel memory' errors.
+   If you encounter this message regularly, better leave SG_BIG_BUFF at
+   32768.
+
+1a.There is a patch for multiple sg device access under Linux. It uses
+   up to 128 K buffer for each device. See here:
+ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/alpha/sg*
+
+2. Ensure your harddisk has write cache enabled (For SCSI hard disks I
+   switched it on with the scsiinfo program from tsx-11.mit.edu), but
+   enable this only if it is correctly working ;-)
+
+This has boosted the throughput of icedax considerably.
+
+
+Supported interfaces
+====================
+
+Non SCSI drives (Linux only):
+	ATAPI:
+	The greatest group nowadays are ATAPI (EIDE) cdrom drives.
+	Support is only limited by the drive. Kernel and icedax
+	are ready for them (unless the drive uses a very uncommon method).
+
+        Newer kernels can do an scsi emulation for ATAPI devices.
+        This interface is supported.
+
+	Parallel port interface:
+	There is a driver that maps the parallel port driver to an generic
+	scsi like driver. Should work with newer kernels.
+
+	Proprietary interfaces:
+	Older drives with proprietary interfaces are supported only
+	if the kernel driver allows reading cdda audio data via ioctl().
+	Currently only Eberhard Moenkeberg's sbpcd and Corey Minyard's
+	cdu31a driver do allow this. The sbpcd driver of kernels earlier than
+	2.0.30 and 2.1.57 needs a patch before satisfying output can be
+	obtained (see README.sbpcd).
+
+SCSI drives:
+	For these drives the SCSI library from Joerg Schilling is used.
+	Thus we need kernel support (compiled-in or as a module) for it.
+        The generic SCSI interface allows multi sector transfers (max. 128 KB)
+	which lowers cpu load considerably.
+
+	** NEW **
+	I added a script 'scsi_scan.linux' to find the generic devices for all
+	SCSI CDROM- or WORM-type drives.
+
+Configuration
+=============
+
+There are some adjustable parameters in the beginning of the Makefile
+(which is called local.cnf.in) . They describe default settings of icedax:
+
+INTERFACE: 	How the cdrom is accessed. Choose one method for INTERFACE.
+DEVICE:		The default cdrom device is set in DEF_DEVICE.
+
+SOUND FILE FORMAT DEFAULTS:
+The default format can be 'wav', 'sun pcm au', 'aiff', 'aifc', or
+'raw bigendian samples'.
+It is determined by the Makefile variable DEF_TYPE.
+
+AUDIO FILENAME:
+The default filename is given by DEF_FILE. Unless 'cdr' format is being used,
+this name is appended with '.wav', '.au', '.aiff' or '.aifc'.
+
+RATE: the default rate is given by setting DEF_UNDERSAMPLING to the divisor
+for the audio cd sampling frequency (44100 Hz).
+
+	RATE = 44100 Hz / DEF_UNDERSAMPLING
+
+DEF_UNDERSAMPLING can be any multiple of a half greater than one half.
+
+DYNAMIC: The default dynamic range of one sample in one channel is defined in 
+DEF_BITS which can be one of 8, 12 or 16.
+
+CHANNELS: set DEF_CHANNELS to 1 for mono and 2 for stereo.
+
+RECORDING TIME: set DEF_TIME to the amount of seconds to record (or 0 for
+the whole track).
+
+SOUND DEVICE: set SOUND_DEVICE to the device name of your sound card.
+		The line containing HAVESOUND should be 
+		uncommented also, if you want the option to hear
+		what you record.
+
+All of those values can be overridden by command line parameters.
+
+
+Compiling icedax
+==================
+
+Adjust the Makefile (named local.cnf.in) for your cdrom interface and
+device setting first.
+
+Then type
+	make
+and as root
+	make install
+
+This will compile icedax and copy the binary to /usr/local/bin and the
+man page to /usr/local/man/man1 (defaults).
+
+
+Privileges
+==========
+
+You can setgid the binary, if you want to allow access to a CDROM's
+scsi_generic interface for icedax but not for arbitrary programs.
+Giving away permissions to send SCSI commands directly to a device is
+not something you want to do lightly on a multi-user server system.
+The setgid privileges will only be used to access the scsi generic
+interface; for cooked_ioctl, the setgid privileges are not necessary
+and they are simply dropped.
+
+Previous versions of icedax had to be setuid to root.  Such privileges
+are no longer necessary and will be dropped if present.
+
+Select device
+=============
+
+By default icedax uses the generic SCSI interface and a device tripel for
+SCSI bus, id, and lun.
+This setting can be overridden by specifying '-Iinterface' and
+'-D cdromdevice'.
+The following command line example uses the generic_scsi interface and the 
+SCSI device with bus 1, id 2 and lun 3:
+icedax -Igeneric_scsi -D1,2,3
+
+The shell script 'scan_scsi.linux' will report the generic devices for
+all SCSI cdrom drives.
+
+If you need to use another interface, check the device setting also as they
+need to fit together.
+Here is an example for an ATAPI cdrom using the cooked_ioctl interface and
+the cdrom device /dev/hdb:
+icedax -Icooked_ioctl -D/dev/hdb
+
+
+Features
+========
+
+I added an optional on-the-fly correction for pre-emphasized samples
+(available for original CDDA format only).
+If the -T option is given, the samples will be filtered before they
+are written to disk. The samples then have a linear frequency response again.
+
+When recording in mono, both channels are summed with halved amplitude.
+
+Undersampling is done by summing several samples with reduced amplitude to
+prevent overflows. This damps higher freqencies as well. Compared to
+exact resampling icedax does not use a very sophisticated (expensive)
+filter algorithm. It currently uses quadratic interpolation for
+noninteger subsampling factors.
+
+Sampling can be aborted by pressing the Interrupt-Key (eg control-C)
+at anytime. Unless streaming to a pipe, the wav header will be updated
+to contain the actual length of the sample. The same will happen, if
+disk space becomes exhausted.
+
+Fast options
+============
+
+The options can also influence the performance greatly.
+The fastest case is given when the samples don't need to be changed from
+their original form or analysed, that is the output format uses the same
+parameters as the drive: 16-bit samples, stereo at 44100 Hz sample rate
+AND with the same endianess (-Cbig and -Ebig, or -Clittle and -Elittle).
+To be sure all parameters can be given explicitly on the command line.
+This avoids an analysis of icedax.
+
+icedax -P0 -q -S<maximum speed> 
+run as root will read with maximum speed and copy its output into the
+wav file, taking advantage of realtime scheduling as well.
+
+For throughput testing the additional option -N can be used. Write
+operations will be suppressed then.
+
+Options that slow down initially
+================================
+-v<level> needs some time for analysis before the actual sampling starts
+
+Options that slow down during sampling
+======================================
+-P1	causes overlap reading, the slowdown depends on the amount of jitter
+-e	synchronous output to a sound card slows down to onefold speed
+
+Options that need more cpu power
+================================
+-p<rate> resamples the output send to the sound card
+-M<count> calculates checksums
+-T	on-the-fly preemphasis filtering
+-F	checking for extremal samples
+-G	checking for differences in both channels
+-C<endianess>	if a conversion is required (see below)
+-E<endianess>	if a conversion is required (see below)
+-Oaudiotype	if a conversion is required (see below)
+-c 1
+-c s
+-m
+-b 8
+-b 12
+-a <not 1>
+-r <not 44100>
+
+When are one or two endianess (byte order) conversions required?
+================================================================
+There are three stages where the endianess matters:
+1.) on the input side the cd drive can deliver in two flavors (called F1).
+    When the flavor is unknown, icedax needs to find out the endianess.
+    A simple voting method is used. Successive samples are compared in both
+    flavors and the flavor with the statistically smaller changes is taken. 
+    The flavor can be defined with the -C option, avoiding the analysis. 
+2.) For any calculation with samples (and echoing to the sound card),
+    the samples are needed in the byte order of the machine (in this case
+    I set 'need_host_order' to yes). The flavor of the machine endianess
+    is called F2.
+3.) Finally, there are two flavors of output sound formats (called F3):
+    wav uses little endian samples
+    cdr and au use big endian samples
+    If the samples currently in memory have the wrong endianess a
+    (possibly second) conversion is required.
+
+This gives the following table:
+F1	F2	need_host_order	F3	conversions
+little	little	no		little		0
+little	little	yes		little		0
+little	little	no		big		1
+little	little	yes		big		1
+little	big	no		little		0
+little	big	yes		little		2
+little	big	no		big		1
+little	big	yes		big		1
+big	little	no		little		1
+big	little	yes		little		1
+big	little	no		big		0
+big	little	yes		big		2
+big	big	no		little		1
+big	big	yes		little		1
+big	big	no		big		0
+big	big	yes		big		0
+
+
+Known problems
+==============
+
+1. Sound quality
+
+Audible errors caused by hesitations:
+
+When recording the same audio track twice, recordings can slightly differ.
+Furthermore depending on the firmware in the cdrom drive, positioning
+errors can be so severe that they cannot be easily corrected by icedax.
+This will unfortunately lead to audible errors.
+
+In this case some overlap or even underlap between successive portions
+is introduced from the cdrom drive.
+Here is this case demonstrated graphically:
+
+Sec 1    ...       Sec n
+|----------------------|                          first  read delivered
+                       |------------------------| second read wanted
+                     |------------------------|   second read delivered
+                     |-|                          extra bogus bytes
+                                              |-| missing bytes
+
+This is due to synchronisation problems between sectors inside the cdrom 
+drive. When the drive has been forced to wait, these problems arise.
+
+Audio cds are lacking sector headers, so it's a difficult job to do the
+positioning right (in the firmware). The frequency of these errors is
+reduced when the reading process can continue undisturbed for longer periods.
+So, a high throughput is essential.
+
+You may want to fine-tune your update daemon to use shorter intervals
+(see 'man 8 update'). Shorter intervals are better because the update
+interruptions are shorter when not so much write requests can pile up.
+
+The plextor 4plexplus drive (PX-4XCE) and newer models, newer pioneer
+models as well as CD-writers with large buffers don't suffer from this
+errors. Here the default is to switch off overlap reading.
+
+If you cannot get good samples from your drives you might consider an
+alternative program. Monty's cdparanoia program goes to great lengths
+in order to seperate the good bits from the bad ones.
+
+2. The index scanner has caused timeouts on my toshiba 3401 due to fast
+   random accesses.
+
+3. Retrieval of media catalog numbers and International Standard Recording
+   Codes may fail due to firmware bugs.
+
+Audio Format Conversion
+=======================
+Currently wav, sun (au-pcm), Apple/SGI aiff/aifc, and raw formats are supported.
+
+I try to write correct wav files (little endian samples), but some
+cd-writers might swap them, which would result in sort of white noise
+instead of the original sounds.  icedax has an endianness detector
+for these cases, but as for all automatics, it might fail on bizarre samples.
+
+Hint: icedax can be forced to use a given input endianness with the
+-C option (arguments are 'little', 'big' or 'guess').
+
+The sun format is a pcm variant, and uses big endian samples.
+The other more common sun format with logarithmically scaled samples (au)
+is not supported but can be obtained from sox's conversion.
+
+The raw format is like the sun format except it has no header. I
+changed the endianness to big endian samples in order to comply
+with popular cd burning software like the wodim program.
+
+The sound converter 'sox' can be used to obtain other sound formats.
+(Note however, that the current sox player and a newer sound driver do not
+harmonize well, use the player from the wavplay package instead (available
+at sunsite)).
+
+
+Feedback
+========
+
+Tested patches, any hardware information regarding drives as well as success/
+failure reports are always welcome at heiko@colossus.escape.de.
+
+
+known cdda capable drives
+=========================
+Check out these web pages for uptodate information:
+
+<http://www.tardis.ed.ac.uk/~psyche/pc/cdrom/CDDA.html>
+
+and
+
+<http://www.anime.net/~goemon/linux-cd/cdda-list.html>
+
+From a news posting from Björn Wiberg
+
+> The following table was generated using the CDROM.CFG file from Nero
+> v3.0.4.2.
+> 
+> It shows different CD-ROM models and what speeds they can do DAE at. I
+> guess the values are "safe ones"; i.e. the speeds at which each drive
+> can perform DAE reliably.
+> 
+> A value of "0x" means the drive doesn't support DAE.
+> 
+> For your convenience, the maximum data transfer speed of the drives
+> (for reading conventional files and data from the CD-ROM) are also
+> included.
+> 
+> Hopefully, this will help some of you who are looking for a good
+> CD-ROM drive to choose a model which seems fast enough both for data
+> and DAE.
+> 
+> The models which support DAE:
+> (Sorted by DAE speed, data speed and model)
+> 
+> CD-ROM model                     DAE     Data   Interface
+> ---------------------------------------------------------
+> PLEXTOR  CD-ROM PX-32TS          16x     16x    SCSI
+> TEAC     CD-524E                 14x     24x    IDE
+> CREATIVE CD620E                  12x     5x     IDE
+> MITSUMI  CD-ROM FX320S !B        12x     32x    IDE
+> TEAC     CD-532E                 12x     32x    IDE
+> HITACHI  CDR-8335                12x     24x    IDE
+> PIONEER  CD-ROM DR-A02S          12x     24x    IDE
+> TEAC     CD-ROM CD-532S          12x     14x    SCSI
+> PIONEER  CD-ROM DR-A12X          12x     12x    IDE
+> PIONEER  CD-ROM DR-U06S          12x     12x    SCSI
+> PLEXTOR  CD-ROM PX-20TS          12x     12x    SCSI
+> MITSUMI  CD-ROM FX120T !B        11x     12x    IDE
+> PIONEER  CD-ROM DR-A04S          11x     32x    IDE
+> PIONEER  CD-ROM DR-U12X          10x     12x    SCSI
+> HITACHI  CDR-8330                9x      24x    IDE
+> SONY     CD-ROM CDU711           9x      14x    IDE
+> MATSHITA CD-ROM CR-584           9x      12x    IDE
+> MATSHITA CD-ROM CR-586           8x      32x    IDE
+> CDM-T531         Ver1.041        8x      18x    IDE
+> TEAC     CD-516E                 8x      16x    IDE
+> TOSHIBA  CD-ROM XM-6201TA        8x      16x    SCSI
+> PLEXTOR  CD-ROM PX-12CS          8x      12x    SCSI
+> PLEXTOR  CD-ROM PX-12TS          8x      12x    SCSI
+> PIONEER  CD-ROM DR-U10X          8x      10x    SCSI
+> SONY     CD-ROM CDU611           8x      10x    IDE
+> FUNAI    E285X                   8x      8x     IDE
+> MITSUMI  CD-ROM FX810T4!B        8x      8x     IDE
+> SONY     CD-ROM CDU511           8x      8x     IDE
+> SONY     CD-ROM CDU571-Q         8x      8x     IDE
+> TEAC     CD-C68E                 8x      8x     IDE
+> MITSUMI  CD-ROM FX400E !B        8x      4x     IDE
+> HITACHI  CDR-8130                7x      16x    IDE
+> MATSHITA CD-ROM CR-585           6x      24x    IDE
+> CREATIVE CD2422E  MC102          6x      12x    IDE
+> MATSHITA CD-ROM CR-508           6x      12x    SCSI
+> IBM      PD-1 LF-1195            6x      6x     IDE
+> PLEXTOR  CD-ROM PX-6XCS          6x      6x     SCSI
+> LITEON   CD-ROM LTN301           5x      32x    IDE
+> LITEON   CD-ROM LTN242F          5x      24x    IDE
+> HITACHI  CDR-7930                5x      8x     IDE
+> ASUS     CD-S340                 4x      34x    IDE
+> E-IDE    CD-ROM 32X/AKU          4x      32x    IDE
+> ATAPI CDROM                      4x      24x    IDE
+> LITEON   CD-ROM LTN244           4x      24x    IDE
+> PHILIPS  PCA248CD                4x      24x    IDE
+> TEAC     CD-524EA                4x      24x    IDE
+> LITEON   CD-ROM LTN202           4x      21x    IDE
+> ATAPI    CD-ROM DRIVE-24X        4x      20x    IDE
+> CREATIVE CD2423E  NC101          4x      20x    IDE
+> SAMSUNG  CD-ROM SCR-2431         4x      20x    IDE
+> TAE IL   CD-ROM CDD-7240J        4x      20x    IDE
+> TEAC     CD-220E                 4x      20x    IDE
+> CREATIVE CD1620E SL970404        4x      16x    IDE
+> LITEON   CD-ROM LTN262           4x      16x    IDE
+> TEAC     CD-ROM CD-516S          4x      16x    SCSI
+> ATAPI    CD-ROM DRIVE            4x      15x    IDE
+> BCD 16XA  CD-ROM                 4x      10x    IDE
+> MATSHITA CD-ROM CR-506           4x      8x     SCSI
+> SONY     CD-ROM CDU311           4x      8x     IDE
+> MATSHITA CD-ROM CR-504-J         4x      4x     SCSI
+> MITSBISH CDRW226                 4x      4x     SCSI
+> SONY     CD-ROM CDU625-S         4x      4x     SCSI
+> SONY     CD-ROM CDU-76S          4x      4x     SCSI
+> SONY     CD-ROM CDU77E           4x      4x     IDE
+> PLEXTOR  CD-ROM PX-4XCE          4x      4x     SCSI
+> SONY     CD-ROM CDU55E           4x      2x     IDE
+> PIONEER  CD-ROM DR-U24X          3x      24x    SCSI
+> LITEON   CD-ROM LTN204           3x      21x    IDE
+> PIONEER  CD-ROM DR-A01S          3x      20x    IDE
+> PIONEER  CD-ROM DR-A24X          3x      20x    IDE
+> FUNAI    E295X                   3x      16x    IDE
+> PIONEER  CD-ROM DR-U03S          3x      12x    SCSI
+> BTC      24X CD-ROM SLL24        3x      10x    IDE
+> PLEXTOR  CD-ROM PX-8XCS          3x      4x     SCSI
+> CyberDrv  CD-ROM TW240S          3x      3x     SCSI
+> COMPAQ   CRD-8320B               2x      32x    IDE
+> LG    CD-ROM CRD-8320B           2x      32x    IDE
+> TOSHIBA  CD-ROM XM-6202B         2x      32x    IDE
+> CREATIVE DVD-ROM DVD2240E        2x      24x    IDE
+> TOSHIBA  CD-ROM XM-6102D         2x      24x    IDE
+> BTC      16X CD-ROM SLL16        1x      10x    IDE
+> NEC      CD-ROM DRIVE:282        2x      8x     IDE
+> HITACHI  GD-2000                 2x      4x     IDE
+> MATSHITA CD-ROM CR-581           2x      4x     IDE
+> NEC      CD-ROM DRIVE:222        2x      4x     SCSI
+> MATSHITA CD-ROM CR-8004          2x      2x     SCSI
+> GoldStar CD-ROM CRD-8240B        1x      24x    IDE
+> TOSHIBA  CD-ROM XM-6102B         1x      24x    IDE
+> CyberDrv  IDE CD-ROM 120D        1x      12x    IDE
+> I DE CD-ROM TW120D               1x      12x    IDE
+> NEC      CD-ROM DRIVE:464        1x      12x    SCSI
+> TORiSAN  CD-ROM CDR_U112         1x      12x    IDE
+> TOSHIBA  CD-ROM XM-5701TA        1x      12x    SCSI
+> TOSHIBA  CD-ROM XM-5702B         1x      12x    IDE
+> CyberDrv SCSI CD-ROM 120S        1x      10x    IDE
+> NEC      CD-ROM DRIVE:463        1x      10x    SCSI
+> COMPAQ   DVD-ROM SD-M1002        1x      8x     IDE
+> MATSHITA CD-ROM CR-583           1x      8x     IDE
+> NEC      CD-ROM DRIVE:462        1x      8x     SCSI
+> TEAC     CD-58E                  1x      8x     IDE
+> OPTICS_S 8622 SCSI               1x      8x     SCSI
+> TOSHIBA  CD-ROM XM-5602B         1x      8x     IDE
+> TOSHIBA  CD-ROM XM-3801TA        1x      7x     SCSI
+> NEC      CD-ROM DRIVE:461        1x      6x     SCSI
+> IBM      CDRM00203               1x      6x     SCSI
+> TEAC     CD-46E                  1x      6x     IDE
+> TEAC     CD-56E                  1x      6x     IDE
+> TEAC     CD-ROM CD-56S           1x      6x     SCSI
+> TOSHIBA  CD-ROM XM-5502TA        1x      6x     IDE
+> TOSHIBA  CD-ROM XM-3701TA        1x      6x     SCSI
+> NEC      CD-ROM DRIVE:502        1x      4x     SCSI
+> TOSHIBA  CD-ROM XM-1502BN        1x      4x     IDE
+> TOSHIBA  CD-ROM XM-5302TA        1x      4x     IDE
+> TOSHIBA  CD-ROM XM-5401TA        1x      4x     SCSI
+> TOSHIBA  CD-ROM XM-5402TA        1x      4x     IDE
+> TOSHIBA  CD-ROM XM-1502B         1x      4x     IDE
+> TOSHIBA  CD-ROM XM-3501TA        1x      4x     SCSI
+> TOSHIBA  CD-ROM XM-5301TA        1x      4x     SCSI
+> TOSHIBA  CD-ROM XM-5201TA        1x      2x     SCSI
+
+known cdda uncapable drives
+===========================
+
+Pioneer		DRM-602X, DRM-604X
+Teac		CD-55A		(panasonic bus)
+Philips		CM206/10	serial RS-422
+		CM207
+		CM226/10	serial RS-422
+		CDD462/01	serial RS-422
+Orchid		CDS3110
+
+Additions to the tables above are welcome.
+
+and now catch your sounds,
+Heiko 		heiko@colossus.escape.de (Original author)
+Changes for the Cdrkit project by Christian Fromme <kaner@strace.org>, Eduard Bloch