                           SoX Installation
                           ----------------

This distribution will compile and run on most commonly-used systems.
It was originally developed on a UNIX/386 machine running AT&T V3.2 but
it's currently developed under Linux.  With a little work it should work
with most POSIX systems.


Compiling using a POSIX system
------------------------------

[Only if you're compiling the CVS sources, first make sure you have
the GNU autotools installed (automake >= 1.9, autoconf >= 2.59) and
run

	autoreconf -i
]

The preferred method for compiling SoX is to use the "configure"
scripts compatible with most UNIX systems that contain "/bin/sh" or
equivalent (it can also be used on Windows with Cygwin).

To compile and install SoX on these platforms run the following
commands:

	./configure
	make
	make install

Optionally:

	make installcheck

(At the moment you can't run "make check", because when built
modularly SoX can't use its format and effect modules until
it is installed.)

There are several optional parameters that you may pass to the
configure script to customize SoX for your applications. Run

	./configure --help

for a complete list of options.


Compiling using Microsoft's Visual C
------------------------------------

o Install cmake (http://www.cmake.org/HTML/Download.html)
o Install any optional libraries to use with SoX
o Install the SoX sources to say c:\sox
o Type cd c:\sox
o Type cmake .

This should generate project build files for use with Visual C.


Optional Compile Features
-------------------------

SoX can make use of some external libraries to obtain support
for additional file formats and/or effects.  Some optional libraries
may require pkg-config to be installed to be properly detected.

SoX can detect and use the following libraries:

  Ogg Vorbis - http://www.vorbis.com

  Lame MP3 encoder - http://lame.sourceforge.net

  MAD MP3 decoder - http://www.underbit.com/products/mad

  FLAC - http://flac.sourceforge.net

  Secret Rabbit Code - http://www.mega-nerd.com/SRC

  libsndfile - http://www.mega-nerd.com/libsndfile

  ffmpeg - http://ffmpeg.mplayerhq.hu

  AMR-NB/WB - http://www.penguin.cz/~utx/amr

  LADSPA - http://www.ladspa.org
  
If any libraries are installed in a non-standard locations in your
system then you can use the CPPFLAGS and LDFLAGS variables to allow
configure to find them. For example:

./configure CPPFLAGS="-I/home/sox/include -I/usr/local/multimedia/include" LDFLAGS="-L/home/sox/lib -L/usr/local/multimedia/lib"

If you are compiling under cygwin and would like to create a static
sox.exe using mingw libraries then you can use the following:

./configure CC="gcc -mno-cygwin" --disable-shared

If you get compile failures during linking on your platform, you may need to
pass "-no-undefined" to libtool.  Trying compiling with this:

./configure LDFLAGS="-no-undefined"

Newer versions of SoX include support for loading libraries for
file formats at runtime.  If you experience problems with this
then you may wish to revert back to the older compile-time support.
To stick with old behavior use:

./configure --without-libltdl

Testing
-------

After successfully compiling SoX, try translating a sound file. If you
can play one of the supported sound file formats, translate
'monkey.wav' to your format (we'll use 'xxx'):

        cd src
	./sox monkey.wav monkey.xxx

You may have to give the word size and rate for the file. For example,
this command will make a sound file with a data rate of 12,500 samples
per second and the data formatted as signed shorts:

	./sox monkey.voc -r 12500 -s -w monkey.xxx 

If monkey.xxx plays properly (it's a very short monkey screech),
congratulations! SoX works.

If your adding new features to SoX or want to perform advance tests
on a new platform then you can use the scripts "tests.sh" and
"testall.sh" to stress SoX.
