first draft
This commit is contained in:
@@ -0,0 +1,141 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user