WAVDifference 1.1
=================

This application allows you to obtain the sample-by-sample
differences between two input WAV files. The two input files
must meet the following requirements

 A) In Stereo LPCM format with the standard 44-byte header

 B) Have either 16 or 24 bits per sample

 C) Sample rate no greater than 192k samples/sec

 D) Share the sample sample rate value, etc, and have the same duration
 
for the files to be comparable by WAVDifference.


Given two comparable files the application generates an output WAV
LPCM file with the same sample rate, etc, as the input files.
The sound waveforms in this output file are the results of
subtracting the waveform in one of the input files from the
waveform in the other on a sample-by-sample basis.

Setup
=====

Before running the application for the first time you may need
to alter the contents of the 'Settings' file inside the application
directory. This contains two lines:
  
  <pathname of the directory from which input WAV files are to be read>
  <pathname of the directory into which an output WAV file will be written>

Change these to point to the directories you wish to use for the input and
output.


Use
===

When you have two WAV files you wish to compare in the input directory,
run the application in the usual way. It will then open a terminal and
ask you to type in the name of each input WAV file.

Given the two names it will first read their file headers to check that they
are comparable. i.e. it will check that they are both Stereo LPCM, and that
they share the same Sampling Rate, Number of Bytes per sample, and duration. 

If the two input files are comparable, the application will ask for a name
for the output file it will create. Given this it will read through the
samples they contain and subtract the values in second input file you named
from those in the first. These sample-by-sample difference results will be
written into the output WAV file.

As processing is carried out the application will report progress in
the terminal window. It processes the data in 0.1 second chunks until the
end of the input files is reached.


Example of use
==============

The application is designed to show any small differences between the
waveforms in the two 'similar' input files. To illustrate, comnsider the
following example.

An mp3 encoder is used to produce an mp3 file 'music.mp3' from an original
LPCM WAV file 'music.wav'. To see how much the mp3 encoding and decoding
processes may affect the result, 'music.mp3' is decoded to generate a new
LPCM WAV file, 'new.wav'.

If the mp3 compression and decoding were 'lossless' then 'music.wav' and
'new.wav' would be identical. But since mp3 is lossy, we can expect them
to be different.

Using WAVDifference we can obtain a new WAV file which contains the
sample-by-sample difference between 'music.wav' and 'new.wav'. If the two
input files are identical the difference WAV file will simply contain a
steam of zeros after its WAV header, and would be totally silent if played. 
But more generally, we find that the output 'difference' file will let us
examine or hear how much the mp3 encode-decode process has altered the
original music.


Note
====

If the values being subtracted are large and of opposite signs, then
the result may exceed the range that can be conveyed by 16-bit (2 bytes
per sample) values or 24-bit (3 bytes per sample). The results are
therefore clipped to keep within the appropriate range for the files
being processed. If clipping occurs the application will report
"clipping!" in the terminal window as an affected 0.1 sec block of data
is processed.

ROX and choice of terminal
==========================

This is provided as a ROX application suited for use with the ROX
filer and session manager. However if you don't use ROX it should
still be possible to run the application by executing the 'AppRun'
file inside the application's directory.

By default this version uses the standard xterm terminal. However
you can easily alter the contents of the AppRun file to use another
terminal if you prefer. As an example the contents of the file
'AppRun_xfceterminal' show the command to place in 'AppRun'
if you have the xfce4 terminal and wish to use that.


You are welcome to modify and use the source code in this file if you
wish. You are also welcome to distribute it to others if they wish a
copy. However please note that I'm not a very good programmer so I
give no warranty that the program as provided by me will work correctly
and safely in all circumstances. Use at your own risk!

Jim Lesurf
28th October 2010

