README.interface
1/*
2 * @(#)README.interface 1.2 19/04/16 Copyright 2002-2019 J. Schilling
3 *
4 * Exports (libparanoia) cdda_paranoia.h
5 */
6
7/*
8 * The paranoia_init() function with callback funtions has been introduced in
9 * February 2007. It is used since the interface version SCHILY_1.0
10 *
11 * The opaque "d" pointer is typically a SCSI * from libscg, but it may be
12 * anything as long as the callback functions use it.
13 *
14 * The variable "nsectors" is the max. # of sectors to read per request
15 *
16 * The function returns a cdrom_paranoia * that has been allocated inside
17 * paranoia_init().
18 *
19 * The original interface from Monty (from 1997) called the functions
20 * cdda_disc_firstsector()
21 * cdda_disc_lastsector()
22 * cdda_read()
23 * cdda_sector_gettrack()
24 * cdda_track_audiop()
25 * cdda_track_firstsector()
26 * cdda_track_lastsector()
27 * cdda_tracks()
28 * directly from libparanoia into the main program, but this was not portable
29 * as this is not supported by the Apple linker.
30 */
31cdrom_paranoia *paranoia_init __PR((void * d, int nsectors,
32 long (*d_read) __PR((void *d,
33 void *buffer,
34 long beginsector,
35 long sectors)),
36
37 long (*d_disc_firstsector) __PR((void *d)),
38 long (*d_disc_lastsector) __PR((void *d)),
39 int (*d_tracks) __PR((void *d)),
40 long (*d_track_firstsector) __PR((void *d,
41 int track)),
42 long (*d_track_lastsector) __PR((void *d,
43 int track)),
44 int (*d_sector_gettrack) __PR((void *d,
45 long sector)),
46 int (*d_track_audiop) __PR((void *d,
47 int track)) ));
48
49/*
50 * The paranoia_dynoverlapset() function has been introduced in
51 * February 2004. It is used since the interface version SCHILY_1.0
52 * and allows top set the range used for dynamic overlapping.
53 */
54void paranoia_dynoverlapset __PR((cdrom_paranoia * p,
55 int minoverlap, int maxoverlap));
56/*
57 * Free the result from a paranoia_init() call.
58 * Introduced in April 1998 by Monty (cdparanoia-III-alpha3).
59 * It is used since the interface version SCHILY_1.0.
60 */
61void paranoia_free __PR((cdrom_paranoia * p));
62
63/*
64 * Set the mode of operation.
65 * Mode is a bitmap, see definitions below.
66 * Introduced in April 1998 by Monty (cdparanoia-III-alpha3).
67 * It is used since the interface version SCHILY_1.0.
68 */
69void paranoia_modeset __PR((cdrom_paranoia * p, int mode));
70
71/*
72 * Set static overlap.
73 * Introduced in December 1998 by Monty (cdparanoia-III-alpha9.4).
74 * It is used since the interface version SCHILY_1.0.
75 */
76void paranoia_overlapset __PR((cdrom_paranoia * p, long overlap));
77
78/*
79 * Read a single sector of audio data from CD.
80 * Calls: paranoia_read_limited(p, callback, 20)
81 * Returns: Pointer to read data.
82 *
83 * Introduced in April 1998 by Monty (cdparanoia-III-alpha3).
84 * It is used since the interface version SCHILY_1.0.
85 */
86Int16_t *paranoia_read __PR((cdrom_paranoia * p,
87 void (*callback) (long, int)));
88
89/*
90 * Read a single sector of audio data from CD.
91 * Calls: callback function for statistics if != NULL
92 * Returns: Pointer to read data.
93 *
94 * Introduced in March 2001 by Monty (cdparanoia-III-alpha9.8).
95 * It is used since the interface version SCHILY_1.0.
96 */
97Int16_t *paranoia_read_limited __PR((cdrom_paranoia * p,
98 void (*callback) (long, int),
99 int maxretries));
100
101/*
102 * Set sector number to continue reading from.
103 * Parameters: "seek" -> sector number, "mode" -> SEEK_SET, SEEK_END, SEEK_CUR
104 * Returns: Previous sector position.
105 *
106 * Introduced in April 1998 by Monty (cdparanoia-III-alpha3).
107 * It is used since the interface version SCHILY_1.0.
108 */
109long paranoia_seek __PR((cdrom_paranoia * p, long seek, int mode));
110
111
112/*
113 * Exports defined in libparanoia overlap.h
114 */
115
116/*
117 * Reset the complete state of libparanoia.
118 *
119 * Introduced in June 1998 by Monty (cdparanoia-III-alpha7).
120 * It is used since the interface version SCHILY_1.0.
121 */
122void paranoia_resetall __PR((cdrom_paranoia * p));
123
124/*
125 * Reset the cache of libparanoia.
126 *
127 * Introduced in April 1998 by Monty (cdparanoia-III-alpha3).
128 * It is used since the interface version SCHILY_1.0.
129 */
130void paranoia_resetcache __PR((cdrom_paranoia * p));
131
132
133
134/*
135 * New interfaces introdiced with interface version SCHILY_1.1:
136 */
137
138/*
139 * Get the mode of operation.
140 * Mode is a bitmap, see definitions below.
141 * Introduced in December 2013.
142 * It is used since the interface version SCHILY_1.1.
143 */
144int paranoia_modeget __PR((cdrom_paranoia * p));
145
146/*
147 * Get the number of sectors to read ahead.
148 *
149 * Introduced in December 2013.
150 * It is used since the interface version SCHILY_1.1.
151 */
152int paranoia_get_readahead __PR((cdrom_paranoia * p));
153
154/*
155 * Set the number of sectors to read ahead.
156 * Readead should be larger than the size of the RAM in the drive.
157 *
158 * Introduced in December 2013.
159 * It is used since the interface version SCHILY_1.1.
160 */
161void paranoia_set_readahead __PR((cdrom_paranoia * p, int readahead));
162
163Mode flags:
164
165Supported:
166
167PARANOIA_MODE_VERIFY
168PARANOIA_MODE_OVERLAP
169PARANOIA_MODE_NEVERSKIP
170PARANOIA_MODE_C2CHECK
171
172Unsupported:
173
174PARANOIA_MODE_FRAGMENT
175PARANOIA_MODE_SCRATCH
176PARANOIA_MODE_REPAIR
177
178
179
180/*
181 * Imports (via callback definition from paranoia_init())
182 */
183d_disc_firstsector (cdrom_drive *d) -> long sector
184d_disc_lastsector (cdrom_drive *d) -> long sector
185d_read (cdrom_drive *d, void *buffer, long beginsector, long sectors) -> long sectors
186d_sector_gettrack (cdrom_drive *d, long sector) -> int trackno
187d_track_audiop (cdrom_drive *d, int track) -> int ??? /* Is audiotrack */
188d_track_firstsector (cdrom_drive *d, int track) -> long sector
189d_track_lastsector (cdrom_drive *d, int track) -> long sector
190d_tracks (cdrom_drive *d) -> int tracks
191
192callback (long inpos, int function)
193
194/*
195 * Imports (libc)
196 */
197calloc
198free
199malloc
200realloc
201
202memcmp
203memcpy
204memmove
205memset
206
207qsort
208
209/*--------------------------------------------------------------------------*/
210#define SEC_SIZE 2352
211scgp = scg_open();
212bufsize = scg_bufsize(scgp, CDR_BUF_SIZE);
213nsecs = bufsize / SEC_SIZE;
214
215cdp = paranoia_init(scgp, nsecs);
216# paranoia_modeset(cdp, mode);
217# paranoia_overlapset(cdp, overlap);
218
219paranoia_seek((cdp, 0L, int SEEK_SET);
220while (not ready) {
221 bp = paranoia_read(cdp, NULL);
222 write(f, bp, SEC_SIZE);
223}
224
225paranoia_free(cdp);
226
README.paranoia
1# @(#)README.paranoia 1.1 97/04/04 J. Schilling from Monty (xiphmont@mit.edu)
2README.paranoia
3
4Paranoia II:
5(c) Monty
6xiphmont@mit.edu
7
8Hi there.
9
10All CDROM drives are not created equal. You're probably using this
11patch because yours is a little less equal than others-- or maybe you
12just keep your CD collection in a box of full of gravel. Jewel cases
13are for wimps; you know what I'm talking about.
14
15This patch adds extra-robust interframe syncronization, code to detect
16scratches (and hold sync across the scratch) and finally routines to
17filter out scratches as best possible. These are all handled
18automatically by fairly modular code.
19
201) extra interframe syncronization -------------------------------------
21
22Some CD drives can read audio data from an exact starting point to an
23exact ending point flawlessly; these are rare. A larger number of
24drives read from only an approximately correct starting point, but do
25manage to get all the data in-tact from wherever they manage to begin
26the read. Stock cdda2wav is coded with this in mind.
27
28More drives, especially IDE-like and recent ATAPI drives, suffer from
29framing misalignments within atomic multi-sector read operations.
30Cdda2wav is also set, by default, to read 75 sectors at a time from
31ATAPI drives, which Linux's IDE driver breaks into multiple 8 sector
32reads to conserve kernel memory. Both of these things will break
33cdda2wav; the symptoms include cracks or pops within the read sample.
34
35The "Paranoia" patch will verify the alignment of *every* byte read by
36cdda2wav. The goal is data integrity, not performance: a minimum 50%
37speed hit will result from the patch, likely more if your CDROM
38suffers from the framing bugs the patch corrects.
39
402) scratch detection and tolerance ------------------------------------
41
42Because overlap syncronization requires matching exact, perfect sample
43sections, scratched CDs typically cause normal cdda2wav to bail when
44overlap syncronization is turned on. The second part of the
45"Paranoia" patch ignores scratches in the read bitstream and
46syncronizes using the data that can still be "trusted". This step
47also collects first-pass scratch detection information used by the
48third section of the patch.
49
50Expect performance to drop through the floor on a badly scratched CD;
51the code can no longer use a simple case of exact matching for speedy
52correlation. Maintaining solid sync across a scratch is processor
53bound; later I'll add speedier algorithms for correlation than the
54brute force method currently used. Scratch detection imposes little
55additional overhead on a non-scratched CD.
56
573) scratch repair -----------------------------------------------------
58
59Scratches are an irrevocable loss of data. Still, it's usually
60possible to reconstruct a sample closer to the original data than the
61raw hissing, fluttering and crackling that severe scratches in the CD
62surface produce.
63
64Scratch filtering is the 'hard part' of this patch. It needs to do
65two things; first, find the 'pops' that escaped detection in section 2
66of the patch and secondly fill in the gaps. Both are acheived using
67delta (slew) averaging and forward and backward linear predictive
68interpolation (with IIR filters) to fill in known gaps as well as look
69for 'problem values' in stretches of sample known to be scratched.
70
71THE SCRATCH DETECTION IS NOT PERFECT. Nor is the repair perfect,
72although it is easier than detecting scratches reliably. Both are
73cases of coming arbitrarily close to perfection; Paranoia is designed
74with light to moderate damage in mind, but will still recover a
75listenable sample from heavy damage.
76
77Paranoia still has quite a bit of room for improvement in the scratch
78repair code... If cdda2wav + Paranoia is not doing an acceptable job
79on CDs that you just gotta have, drop me a line; I didn't want to sink
80months into a project I wasn't certain anyone would ever use :-)
81
82Monty
83
84