# cdrustanoia

`cdrustanoia` is a Rust port of cdparanoia III 10.2 for Linux.  It is intended
to be a drop-in replacement for the `cdparanoia` command line tool and for the
`libcdda_interface` / `libcdda_paranoia` C libraries.

The port includes:

- the cdparanoia command line interface and span grammar,
- the two-stage verification, overlap, drift and rift-reconstruction engine,
- the Linux SG_IO and cooked-ioctl CD-ROM backends,
- TOC query and drive/endianness probing,
- WAV, AIFF, AIFF-C and raw output,
- batch mode, stdout output, sample/TOC offsets, logging and progress display,
- source- and ABI-compatible C libraries and headers,
- a synthetic image backend and fault-injection tests that do not need a CD
  drive.

## Building

```sh
cargo build --release --workspace
```

The binaries are written to `target/release/cdrustanoia` and
`target/release/cdparanoia`.  Both run the same code; `cdparanoia` exists so
existing scripts and packages can invoke the expected name.

## Installing

```sh
sudo make install PREFIX=/usr/local
# or
sudo ./install.sh
```

This installs:

- `bin/cdrustanoia` and the `bin/cdparanoia` symlink,
- `man/man1/cdparanoia.1` and `cdrustanoia.1`,
- `include/cdda_interface.h`, `cdda_paranoia.h` and `utils.h`,
- `lib/libcdda_interface.{so,a}` and `lib/libcdda_paranoia.{so,a}`,
- the original `.so.0` SONAME symlinks.

`DESTDIR` is supported for package builds.

## Usage

The command line is compatible with cdparanoia 10.2:

```sh
cdrustanoia -Q
cdrustanoia -B
cdrustanoia "1[:30.12]-1[1:10]" track.wav
cdrustanoia -r -- "-3" out.raw
```

Use `cdrustanoia --help` for the full option and span documentation.  The man
page is the original cdparanoia man page.

## Benchmarks

The core crate contains a small synthetic benchmark for the paranoia read path
and the sample index:

```sh
cargo run --release -p cdrustanoia_core --example bench_paranoia -- 5000
```

It reports index setup/query times, a comparison with the old `HashMap`
index, and overall synthetic read throughput.  The image backend is
memory-backed, so the absolute numbers are useful for regression tracking
rather than as a prediction of physical drive speed.

## C API

The two C libraries export the traditional symbols and use the original
public structure layout.  The headers are installed under `include/`; link
programs the same way as with cdparanoia:

```sh
cc app.c -lcdda_paranoia -lcdda_interface
```

The public `cdrom_drive` layout, `TOC` layout, function-pointer fields, error
codes and `paranoia_*` entry points match cdparanoia 10.2 on 64-bit Linux.

## Testing without a CD drive

Set `CDRUSTANOIA_TEST_IMAGE` to a raw CDDA image (2352-byte sectors).  A
sidecar file named `<image>.<ext>.toc` may contain one line per track:

```text
start_sector end_sector flags_hex
```

For example:

```text
0 99 0
100 199 0
```

Then use the normal command line:

```sh
CDRUSTANOIA_TEST_IMAGE=/tmp/disc.raw ./target/debug/cdparanoia -Q
CDRUSTANOIA_TEST_IMAGE=/tmp/disc.raw ./target/debug/cdparanoia -B
```

The backend is intentionally not advertised in `--help`; it exists for tests
and development.

Run the automated suite with:

```sh
cargo test --workspace
```

The suite covers span parsing, output headers, command-line parsing, the
paranoia engine (including jitter and fragmented reads), the C ABI layout, and
the C libraries.

## Hardware checklist

The SG_IO and cooked ioctl paths cannot be exercised in a machine without a
CD-ROM drive.  When hardware is available, verify:

1. `cdrustanoia -Q` lists the TOC.
2. `cdrustanoia -v -Q` shows SG_IO or cooked autosense.
3. `cdrustanoia -B` produces `trackNN.cdda.wav` and the audio matches the disc.
4. A deliberately scratched disc produces the expected `:-(`/`;-(` progress
   and either reconstructs audio or removes the aborted file with `-X`.
5. `-A` completes and writes `cdparanoia.log`.
6. `-e` produces the `##:` callback lines for wrapper scripts.
7. A small C program using `cdda_identify`, `cdda_open`, `paranoia_init`,
   `paranoia_read` and `cdda_close` works.

## Compatibility notes

- Linux is the only supported platform, matching cdparanoia 10.2.
- Modern SG_IO and legacy cooked ioctl access are implemented.  The obsolete
  `/dev/sg` SG2/SG3 packet transport is not; `-g` uses SG_IO on the named
  generic device where the kernel supports it.
- `-i/--output-info` is accepted but is a no-op, matching the 10.2 source.
- 64-bit Linux ABI is the primary target.
- The `-A` cache analysis is a compact functional port; its timing
  recommendations should be treated as advisory.

## Licence

The port is derived from cdparanoia III 10.2.  The command line program is
GPL-2.0-or-later; the libraries are LGPL-2.1-or-later, following the original
distribution.  See `LICENSE-GPL-2.0`, `LICENSE-LGPL-2.1` and the copyright
notices in the original headers.