README for declick v0.6.5, 9.5.1999

Sections:

- INTRODUCTION
- WHY THIS PROGRAM
- DESCRIPTION
- ADDITIONAL FEATURES
- INSTALL
- CONTRIBUTIONS
- COPYRIGHT, WARRANTY



INTRODUCTION:
-------------

declick is a dynamic digital declicker for audio sample files.

The main purpose of declick is the removal of digital clicks in the
input material.

It is intended for the automatic removal of clicks produced by scratched
CDs or poorly working CD grabbers, for example when using an IDE CD-ROM.

It is not designed to remove analogue clicks as from scratched LPs.

In its effect, one could describe it as a CD washer (where this is only
one of the purposes you could use it for).

It should compile on Linux, Windows, Macintosh (untested) and different
UN*X flavours (untested). See the Makefile for instructions.


WHY THIS PROGRAM:
-----------------

Over the years, I was so bothered of listening to some of my old CDs that
got accidentially scratched (no, have no cats, but there is still enough
potential danger left to my CDs - I will not go in further details ;-).
The internal correction of my CD player didnt manage to wipe the errors
out, as they were numerous for some of the oldest pieces. And unfortunately
some of the belovest. So I went to the music store to replace them with
newly bought, but had to learn that some were no more in the production
chain. Checking some second hand resellers was not successful, except that
I learned that there are people outside still caring less for their CDs than
I did in the past.

That was the moment where I began to grab my CDs into the computer and
to check the samples with a wave editor. What I saw was encouraging: The
awfully sounding clicks were very easy detectible to my eyes. It only took
some minutes to repair some songs with few errors.

But then I started to grab a CD that partially looked like a sieve. Correction
still was simple, but doing that on 548253 erroneous samples was a bit time
consuming.

That was the day I started to write this program.



DESCRIPTION:
------------

declick doesnt use sophisticated fourier transformations or similar, but
simply shifts a dynamic threshold detector through the sample data
(you could imagine it as a kind of window in which the sample values have
to fit). The window is very tight when stepping forward through the samples,
but it gets adapted to the current passage of sound, it "learns". To
reduce false alarms, passages with "broken" windows are scanned backward
again to reverse the time axis for adaption of the filter. If the window
remains too tight for the sample data, it is interpolated to fitting values.
This means, the clicks are removed.

This sounds somewhat too simple for a successful correction, but reality
proves it works. And it works much better than the analogue declickers I
have tried, because of the nature of digital clicks.

Digital clicks are very sharp and loud in sound, even if the overall
offset of a distorted sample value to its neighbour samples is not very
high. To get sufficient detection with analogue declickers, you have to
set their detection threshold very low. This results in any sharp sound
of the input material skipped - the result doesnt sound anymore like the
original, even in segments without any click.

The main goal while developing declick was to leave the original as much
untouched as possible. Segments without a click are untouched, due to the
dynamic adaption of the input window. It may, from time to time, happen
that a passage with high sample offsets (especially if preceeded by silence)
experiences some corrections, but as these corrections only affect one or
two samples, the difference to the original is not audible. This mostly
will happen with digitally created sound, and very seldom.

So, if you use declick with a file containing no digital clicks, in most
cases nothing gets changed. You can use it as a watchdog to prove everything
is OK with your data.

The input file is expected as stereo, 16 bit signed samples, in RIFF
(aka WAV) file format. If an input file does not match these
specifications, processing is aborted.

declick analyzes the RIFF headers accurately, skipping over playlists,
song descriptions or anything else that may be present except the sample
data itself.

The sample rate (samples per second) may have any value.



ADDITIONAL FEATURES:
--------------------

1)
Due to the intention to leave as much of the input untouched as possible,
in some cases clicks are not corrected. This happens when clicks (= errors)
in the input are starting with low offsets and then get higher and higher.
This may happen with heavily scratched CDs. In this case, the automatic
adaption of the input window opens that window wider and wider. To limit
this effect, you can apply an option that tells declick to limit the window
size to a fixed maximum. You should not use this feature unless you have
heavily erroneous input material, and a first run of declick did not remove
all clicks.
The option "-v[n]" enables this feature.

2)
To monitor operation of the declicker, you can switch "analyzer mode" on.
declick then corrects or checks one stereo channel, writing analysis
output to the other channel. You can use this feature if you want to find
out if the click declick detects is really a click. In most cases, it is.
You will be surprised how many clicks normally remain inaudible.
The option "-d[1..3]" enables this feature.

3)
Many programs working with RIFF/WAV files dont analyze the headers. They
expect the start of sample data after a fixed header offset, and the
remaining length to be the samples. This is not necessarily true. declick
can cut a RIFF/WAV file after the sample data to get rid of other
information in the file, such as playlists, song texts and the more.
The option "-c" enables this feature.

4)
When burning a track in Track-at-Once (as for example cdrecord does), the
CD writer adds two seconds of silence to each track. declick can delete
silent samples at the beginning and/or end of a song helping to preserve the
original duration of silence.
The options "-s" and "-e" enable this feature.
"-e2" deletes trailing silence up to two seconds.

5)
I use broadcast v2.1 from Adam Williams
(see http://www.geocities.com/Hollywood/3709/bcinstr.html)
for display and manual correction of sample data. Broadcast uses an index
file to speed up display. Creation of this index file on a new sample file
takes as long as one run of declick, as all data has to be analyzed.
declick can create this index file during its normal run without a speed
penalty.
The option "-i" enables this feature.

6)
All operations can be done with dummy writes to the sample file (leaving
the original file untouched). In conjunction with the index file creation
(reflecting the result of the declicking) you can easily watch what declick
would have changed when run in real mode.
The option "-t" enables this feature.




INSTALL:
--------

1) Unpack the .tar.gz archive.
2) If you are not using Linux, edit the Makefile.
3) Type "make all"
4) Type "make install" (this installs declick in /usr/local/bin )

You're done.



CONTRIBUTIONS:
--------------

Index file creation for broadcast follows the source code of broadcast.
Thank you, Adam Williams, for the fine program.
For audio grabbing, I use Monty's cdparanoia (xiphmont@mit.edu). It has
been a real help in getting the most possible out of scratched CDs.
Thank you, Monty!



COPYRIGHT, WARRANTY:
--------------------

declick is copyright 1999 by Joachim Schurig, jschurig@zedat.fu-berlin.de

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation.

This program is distributed WITHOUT ANY WARRANTY; even without the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
