Hi dear cdrom drive users,

This README describes hardware related matters as well as the installation of 
cdda2wav, the sampling utility.

NOTE:
Since the inclusion of cdda2wav in Joerg Schillings cdrecord package
all newer development will take place in this new place. For the latest
cdda2wav look for this or a newer release:
ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/alpha/cdrecord-1.8a15.tar.gz

This is probably the last stand-alone release.

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 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 Linux and Solaris
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 cdda2wav 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 cdda2wav
	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.
They describe default settings of cdda2wav:

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' or 'raw bigendian samples'.
It is determined by the Makefile variable DEF_TYPE.

AUDIO FILENAME:
The default filename is given by DEF_FILE. In case of 'wav' or 'sun' format
this name is appended with '.wav' rsp. '.au'.

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 cdda2wav
==================

Adjust the Makefile for your cdrom interface and device setting first.

Then type
	./configure
	make
and as root
	make install

This will compile cdda2wav 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 cdda2wav 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 cdda2wav had to be setuid to root.  Such privileges
are no longer necessary and will be dropped if present.

Select device
=============

By default cdda2wav 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:
cdda2wav -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:
cdda2wav -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 cdda2wav 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.


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 cdda2wav.
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) 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. Cdda2wav has an endianness detector
for these cases, but as for all automatics, it might fail on bizarre samples.

Hint: Cdda2wav can be forced to use a given input endianness with the
-C option (possible 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 following call produces mono, 8-bit samples at about
8 KHz sample rate piped into /dev/dsp:

	cdda2wav -mb8 -Osun -a5.5 - >/dev/dsp

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 cdrecord 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>

known cdda uncapable drives
===========================
Mitsumi		FX001D(E)
		LU00x
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
