Hi dear cdrom drive users,

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

Some cdrom drives are capable of sending audio data in digital form to the
host (cdda). One of the first drives with this capability was the toshiba 3401
SCSI cdrom drive.

cdda2wav reads audio data given by the cdrom drive and dumps it into 
a wav sound file. The sampling format can be controlled by options.
See cdda2wav.1 or cdda2wav.doc for details.


Requirements
============

1. IPC support from the kernel
   Check for IPC support with the 'ipcs' utility. It will tell you
   if IPC is not available. In that case you have to reconfigure the
   kernel and include it. This kernel has to be used then with cdda2wav.

For SCSI cdroms and CD-writers
2s. kernel support for SCSI, the host adapter, SCSI cdroms and the
    generic SCSI interface. You need to have the proper device
    descriptors (get them under Linux with the MAKEDEV script from /dev).
    Cdda2wav now relies on Jrg Schillings SCSI library for
    better portability.

    For Sun workstations Jrg Schillings scg driver is needed too.
    See http:// for binary versions.

For ATAPI cdroms under Linux
2a. kernel support for the ATAPI cdrom driver. You need to have the
    proper device descriptors (get them with the MAKEDEV script from
    /dev).

For cdrom drives with proprietary busses under Linux
2p. Please check the CDROM-HOWTO for features of the respective
    drivers. The sbpcd driver is very demanded due to the lack of
    interrupts.

optionally for Linux and Solaris
3. kernel sound card support. The Linux pc speaker driver is limited to
   mono formats.


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.
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 drives
================

generic ATAPI/EIDE drives (Linux only):
	The kernel since 2.0 and cdda2wav support all drives that are able
	to read cdda via the standardized command set.
	Instead of an outdated list, have a look into the file cdda_links
	for more uptodate cdrom drive information.

SCSI:
	Toshiba 3401 and newer
	Sony CDU-8003 and newer
	NEC MultiSpin 2Xi (CDR-201) and newer
	Chinon CDS-535 Rev. Q20 and newer
	Plextor drives PX-45CE, PX-63CS and newer
	Devices with multimedia command sets (MMC)
	But better have a look in the web (see file cdda_links).

CD-Writers:
	Philips/Grundig/IMS/Mitsumi
	HP 4020i
	Devices with multimedia command sets (MMC)

Drives with proprietary interface (Linux only)
	CDU31a, CDU33
	Jochen Karrer supplied useful information for these drives.
	It is best to run no other processes while cdda2wav is sampling.
	If the host has to do other tasks as well, use an initial
	value of 14 for NSECTORS in interface.h. This will slow down
	the sampling process considerably :-(, but it should work.
	Otherwise the defaults NSECTORS = 75, overlap = 10 and
	retry_count upto 30 should be ok.

The above mentioned drives have been tested successfully under Linux.

Untested drives (should work, but feedback is needed):
	other Sony command set compatible SCSI drives

Problem drives:
	Panasonic Matsushita CR-56x and newer with proprietary interface
	A newer kernel is necessary to use cdda2wav with them (see README.sbpcd).

(Feedback on other drives is welcome, too).


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.
        Support for this interface is slowly evolving...

	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 generic SCSI interface 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. Furthermore support for all
	vendor specific commands is build in and it is documented :-). 

	** NEW **
	I added a script 'scsi_scan.linux' to find the generic devices for all SCSI
	CDROM- or WORM-type drives.


Notes on kernel SCSI drivers
============================

Cdda2wav has been tested on numerous 1.2, 1.3, 2.0 and preliminary 2.1
Linux kernels. I use the excellent UltraStor u14_34f driver from Dario Ballabio.


Configuration
=============

There are some adjustable parameters in the beginning of the Makefile. They
describe default settings of cdda2wav:

INTERFACE: 	How is the cdrom 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 lowendian 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 dsp (compatible)
		sound device. The line containing HAVESOUND should be 
		uncommented also, if you want the option to have monitoring.

All of those values can be overridden by command line parameters.

There are also installation directories for the binary and the man page.


Compiling cdda2wav
==================

Configure the package with ./configure, and adjust the
Makefile for your cdrom interface and device setting first.

Then type
	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 corresponding
SCSI device. If you need to use another interface, check the device
setting also as they need to fit together.
This setting can be overridden by specifying '-D cdromdevice'.

The shell script 'scan_scsi.linux' will report the generic devices for
all SCSI cdrom drives.


Features
========

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.

4. The last audio track of CD-Extra/Plus may have a wrong length.
   (This seems to be a design bug in the CD-Extra specs and can
    only be circumvented with cdrom drives that allow to read each
    session TOC independently).


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 cheap pcm variant, and uses big endian samples.
The more common sun format with logarithmically scaled samples (au)
is not supported but can be obtained from sox.
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)).

For MIDI users a filter/converter for the SDS/SDX sample format
would be nice. This would allow for easy downloading into synthesizers.
Docs are here, any volunteers?


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:

<http://www.tardis.ed.ac.uk/~psyche/pc/cdrom/CDDA.html>

and

<http://www.anime.net/~goemon/linux-cd/cdda-list.html>


The following list is pretty old and was combined from FAQS of
alt.cd-rom and comp.sys.mac.hardware:

  The following drives can do digital audio extraction:

  Apple		300, 300i (Sony CDU-8003, CDU-8003A)
  Apple		CD-600
  Apple's "New" CD (Matsushita CR-8004)

  Aztech 	CDA 268-01A

  Chinon	CDS-535 (note: needs at least v2.0 firmware "Q20" or "R20")

  Hitachi       atapi CDR-7730 (requires cdparanoia-III)
  Hitachi       atapi CDR-8130 (requires cdparanoia-III)

  Matsushita	(see Panasonic)
  Nakamichi MBR-7
  NEC CDR 500, CDR501, CDR 510, CDR 600 (MultiSpin 3x series)
  NEC CDR 400 (MultiSpin 3xp portable)
  NEC CDR 900 (MultiSpin 4x Pro quadruple speed)
  NEC CDR-251	(4 cd changer at 3fold speed)

  Panasonic 	CR-562B, CR-563B
  Pioneer	DR-UA124X ATAPI
  Plextor	PX-43CH, 45CH, 43CS, 45CS, 63CS, 65CS, 45CE, 83CS
  Sony		CDU-561 rev 1.8p and newer
  Sony 		CDU33A
		CDU8002 (Apple CD-150)
  Sony		CDU-55S          but NOT firmware release 1.0q
                CDU-561, 561SUNCD,  75S, 76S and 920S,

  TEAC CD516E Atapi (best with 2.0.32 or newer kernels)

  Toshiba XM 3301TE (Silicon Graphics version)
  Toshiba XM 3401TA, XM 3401B    but NOT firmware releases 2732 and 3593
  Toshiba XM 3401TE (Silicon Graphics, and Sun versions)
  Toshiba XM 3501B
  Toshiba XM 3601
  Toshiba XM 4100
  Toshiba XM 4101TA, XM 4101B
  Toshiba XM 5201B

  Yamaha	CDR-100
 
others?


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


totally unknown (may be)
========================
Aztech		CDA268-031 SE
Chinon		CDS-525S
Mitsumi		FX300
Pioneer		DR-U104X
Elitegroup	Vertos 100, 300
Wearnes		CDD-120A


Additions to the tables above are welcome.


How to find out whether your FOOBAR drive is capable of cdda reading
====================================================================
If feasible, contact your cdrom manufacturer. Supply firmware
release and version as well as manufacturing date on your request.
This is the most reliable way to determine.

If you have msdos, the cdrom driver and a mscdex.exe installed, you
could try some of the programs available from the simtel software collection.
This ftp server is mirrored very often.
Have a look at 00_index.txt in directory msdos/cdrom (dac, cdgrb, ...).

and now catch your sounds,
Heiko 		heiko@colossus.escape.de

