=========================================================================

SoundFile -- soundfile reading/writing library for soundfiles in the
    Microsoft WAVE format and the Sun/NeXT audio file formats.
    See programs in the examples directory for sample usage of the library.

The primary classes, SoundFileRead and SoundFileWrite, are designed
to interface with standard digital signal processing techniques by
normalizing the audio data into the range from -1.0 to +1.0.  16-Bit
functions are added to access the data as integer values, but only as a
courtesy since they are reconverted from the normalized double values.
The SoundFileRead and SoundFileWrite can handle almost all possible input
and output sound file data types, such as 8-bit mulaw, 8-bit linear,
16-bit linear, 24-bit linear, 32-bit linear, 32-bit float, and 64-bit
double float types.  All of the actual reading/writing of soundfiles
is done with soundfilehelpers.cpp.

Before compiling the library/programs, you should change the 
OSTYPE variable in Makefile.library and Makefile.examples to one
of the following values:
    * use LINUX  for linux computers (on Intel CPUs)
    * use VISUAL for Windows computers
    * use SUN    for Sun computers
    * use OSX    for Apple OS X computers (on Motorola CPUs)

Then type "make library" to compile the soundfile library.
And then type "make examples" to compile all of the example programs.


Operating systems known to compile the code successfully:
    * Linux on Intel architecture with GCC 2.7.2 or higher
    * Apple OS X 10.2 or higher
    * Microsoft Windows 95 with Visual C++ 5.0 or higher

If you use the Cygwin (cygwin.com) linux terminal for Windows, you
should comment out the strip command when making the example programs.

The library and example programs should compile on any other platform,
although the endianness of the computer will have to be specified in
include/sigConfiguration.h which is used by the FileIO class to figure
out the correct order to write multi-byte numbers.

Mon Oct 17 03:28:58 PDT 2005
Craig Stuart Sapp <craig@ccrma.stanford.edu>


=========================================================================


00README		-- This file.
examples		-- Example programs which use the library.
include			-- Header files for use with library file.
lib			-- Location for the library file.
Makefile		-- Makefile for creating library and example programs.
Makefile.library	-- Makefile for creating library.
Makefile.examples	-- Makefile for creating exmaple programs.
src			-- Source code directory for library.

-------------------------------------------------------------------------

Example programs in the examples/ directory:
        badsplice.cpp       -- Chop up a soundfile into random pieces.
	extractChannel.cpp  -- Take one channel out of a multi-channel file.
        extractrange.cpp    -- Extract a segment from a larger soundfile.
        looptest.cpp        -- Demonstration and testing of the looping 
                                  feature of the SoundFileRead class.
        makemulti.cpp       -- Take several input soundfiles and write
                                  out a single multi-channel soundfile.
	multi2mono.cpp	    -- Example program to convert multi-channel files
   			          to mono files by adding all channels together.
	readtest.cpp	    -- Soundfile reading test program.
        sndcopy.cpp         -- Program that reads a file and outputs
                                  the an exact copy of the same soundfile.
        sndinfo.cpp         -- Print out the soundfile's vital statistics.
        sndreverse.cpp      -- Reverses a soundfile.
        sndsubtract.cpp     -- Subtract two sound files and store
                                  results in a third soundfile.  Useful
                                  for debugging.
	writetest.cpp	    -- Soundfile writing test program.

	clicktrack.cpp	    -- Create a click track for an existing soundfile.
	cutoff.cpp	    --
	extractclicks.cpp   -- Extract click track times from audio clicktrack.
	printbits.cpp       --
	snd16.cpp           --
	sndpower.cpp	    -- Calculate power information for a soundfile.
	sndscale.cpp        --




Library files in lib/, include/, and src/ directories:
	soundfile.h         -- API interface for soundio library.
	lib/libsoundfile.a  -- soundfile library file (when created w/ makefile)

	Array.cpp	    -- Class for arrays of numbers.
	Array.h		
	Collection.cpp	    -- Base class for Array.
	Collection.h
	FileIO.cpp	    -- Class for handling endian outputs to files.
	FileIO.h
	Options.cpp	    -- Handy command-line option processor.
	Options.h
	Options_private.cpp -- Used by Options class.
	Options_private.h
	sigConfiguration.h  -- Miscellaneous preprocessor define setups.
	SoundFileRead.cpp   -- Class which reads soundfiles.
	SoundFileRead.h
	SoundFileWrite.cpp  -- Class which writes soundfiles.
	SoundFileWrite.h
	SoundHeader.cpp	    -- Class for soundfile formatting parameters.
	SoundHeader.h
        soundfilehelpers.cpp-- Helping function which do the actual soundfile
        soundfilehelpers.h     reading/writing.


---------------------------------------------------------------------------

To test the basic reading and writing of soundfiles, type "make runtest" 
which should generate this output:

; Sample count = 20
; Channels     = 1
; samp  16-bit  double
0:      -5      (-0.000152588)
1:      -4      (-0.00012207)
2:      -3      (-9.15527e-05)
3:      -2      (-6.10352e-05)
4:      -1      (-3.05176e-05)
5:      0       (0)
6:      1       (3.05176e-05)
7:      2       (6.10352e-05)
8:      3       (9.15527e-05)
9:      4       (0.00012207)
10:     -5      (-0.000152588)
11:     -4      (-0.00012207)
12:     -3      (-9.15527e-05)
13:     -2      (-6.10352e-05)
14:     -1      (-3.05176e-05)
15:     0       (0)
16:     1       (3.05176e-05)
17:     2       (6.10352e-05)
18:     3       (9.15527e-05)
19:     4       (0.00012207)


To test the looping feature of the SoundFileRead class, type "make runloop" 
which should generate this output:

; Sample count = 100
; Channels     = 1
; samp	16-bit	double
; The first 10 samples:
0:	0	(0)	
1:	1	(3.05176e-05)	
2:	2	(6.10352e-05)	
3:	3	(9.15527e-05)	
4:	4	(0.00012207)	
5:	5	(0.000152588)	
6:	6	(0.000183105)	
7:	7	(0.000213623)	
8:	8	(0.000244141)	
9:	9	(0.000274658)	

; The last 10 samples:
90:	90	(0.00274658)	
91:	91	(0.0027771)	
92:	92	(0.00280762)	
93:	93	(0.00283813)	
94:	94	(0.00286865)	
95:	95	(0.00289917)	
96:	96	(0.00292969)	
97:	97	(0.00296021)	
98:	98	(0.00299072)	
99:	99	(0.00302124)	

; The first 10 samples again via looping:
0:	0	(0)	
1:	1	(3.05176e-05)	
2:	2	(6.10352e-05)	
3:	3	(9.15527e-05)	
4:	4	(0.00012207)	
5:	5	(0.000152588)	
6:	6	(0.000183105)	
7:	7	(0.000213623)	
8:	8	(0.000244141)	
9:	9	(0.000274658)	


A useful debugging sound file can be generated with the 
following command:
 bin/writetest -n 65536 -s -32768 fullrange.wav
This should write a sound file which contains exactly one sound sample
at every possible amplitude level.  This file can also be created
in the bin directory by typing "make fullrange".



========================================================================

CHANGES from version to version:


Version 2.2  --  Mon Oct 17 03:28:12 PDT 2005
Version 2.1  --  Sun Aug 29 03:11:48 PDT 2004
Version 2.0  --  Fri Jan 10 12:23:42 EST 2003
Version 1.2  --  Sat Feb  2 12:08:56 PST 2002
Version 1.1  --  Wed Jan 23 19:53:50 PST 2002
Version 1.0  --  Sun Jan 20 13:26:42 PST 2002

Changes from version 2.1 to 2.2
   * Updated template classes to compile in GCC 3.4.
   * Added clicktrack.cpp and extractclicks.cpp example programs.

Changes from version 2.0 to 2.1
   * Updated include-file style in example programs to compile without
     deprecation warnings in GCC3.
   * Changed seekp to seekg in SoundFileRead (to work properly with latest GCC).
   * Added a function to SoundFileRead for 24-bit values.
   * Fixed 24-bit sample reading by changing char variables to unsigned char.
   * Added the example programs printbits.cpp, sndpower.cpp, extractrange.cpp

Changes from version 1.2 to 2.0:
   * Rename library from soundio to soundfile
   * Added example programs sndscale.cpp, reverse.cpp and badsplice.cpp
   * Generalized Makefiles for library and example programs

Changes from version 1.1 to 1.2:
   * INCOMPATABLE CHANGE from previous version of SoundFileRead class:
     The first sample in the sound file is read into the current array.
     Therefore, you do not have to incrementSample() at the start to
     get the first sample.  All example programs have been changed so
     that they will work properly with the new sample reading convention.
   * fixed SoundFileRead::gotoSample() by removing -1 in seekp().
   * fixed SoundFileRead::reset()
   * added looptest.cpp example program to demonstrating the looping 
     feature of SoundFileRead class.
   * added function SoundFileRead::getCurrentSampleIndex() so that you
     can ask a SoundFileRead object what is the index of the current
     sample being read with the getCurrentSample*() functions.

Changes from version 1.0 to 1.1:
   * changed filename parameters in SoundFileRead from char* to const char*.
   * changed filename parameters in SoundFileWrite from char* to const char*.
   * added example programs: multi2mono.cpp extractChannel.cpp sndcopy.cpp 
     sndinfo.cpp and makemulti.cpp
   * fixed SoundFileRead::getNextSample16Bit function.
   * changed normalization factor in SampleToShort() from 0x7fff to 0x8000.


