INSTALL

   1                            SoX Installation
   2                            ----------------
   3
   4 SoX should compile and run on any POSIX compatible system (Linux, BSD,
   5 Solaris, Xcode on Mac OS X, Cygwin on MS-Windows, etc.).  For other
   6 compilers/systems, it is often possible to manually construct a custom
   7 `soxconfig.h' and `Makefile' for that system (the minimum requirements
   8 are 32-bit CPU, 64-bit FPU, C89 compiler).
   9
  10 Note that the `play', `rec', and `soxi' programs are in fact just
  11 copies-of or links-to (depending on OS) `sox'.
  12
  13 SoX optionally makes use of some external libraries to obtain support
  14 for additional file formats and/or effects.  Optional libraries should
  15 be installed before compiling SoX.  The current list of supported
  16 libraries, where to get them (if not from your OS distribution), and
  17 their licence types, is as follows:
  18
  19 OpencoreAMR-NB/WB http://sourceforge.net/projects/opencore-amr  Apache
  20 VisualOn AMR-WB   http://sourceforge.net/projects/opencore-amr  Apache
  21 AO                http://xiph.org/ao                    GPL
  22 FLAC              http://flac.sourceforge.net           BSD
  23 LADSPA            http://www.ladspa.org                 LGPL + plugins' licence
  24 Lame MP3 encoder  http://lame.sourceforge.net           LGPL
  25 Twolame MP2 enc.  http://www.twolame.org                LGPL
  26 libltdl           http://www.gnu.org/software/libtool   LGPL
  27 MAD MP3 decoder   http://www.underbit.com/products/mad  GPL
  28 MP3 ID3 tags      http://www.underbit.com/products/mad  GPL
  29 Magic             http://www.darwinsys.com/file         BSD
  30 Ogg Vorbis        http://www.vorbis.com                 BSD
  31 Opus              http://www.opus-codec.org/            BSD
  32 PNG               http://www.libpng.org/pub/png         zlib (BSD-like)
  33 Sndfile           http://www.mega-nerd.com/libsndfile   LGPL
  34 WavPack           http://www.wavpack.com                BSD
  35
  36
  37
  38 Compiling and installing on a POSIX system
  39 ------------------------------------------
  40
  41 First install any optional libraries that you need for SoX.  Some
  42 libraries may require pkg-config to be installed to be properly
  43 detected by SoX.
  44
  45 [Only if you're compiling the git sources, first make sure you have
  46 the GNU autotools (automake >= 1.9, autoconf >= 2.62, autoconf-archive)
  47 installed, then run
  48
  49         autoreconf -i
  50 ]
  51
  52 To compile and install SoX (executables, libraries, manual pages) with
  53 a default configuration for your platform, run the following commands:
  54
  55         ./configure
  56         make -s
  57         make install
  58
  59 There should be no errors and few, if any, warnings during the `make
  60 -s' stage.  Any warnings about pointer mismatch or conversion should
  61 be treated with deep suspicion.
  62
  63 The `make install' command may require `root' priviliges; for example,
  64 on some systems, the following modification to the command is needed:
  65
  66         sudo make install
  67
  68 To run a selection of tests on the installed sox executable:
  69
  70         make installcheck
  71
  72 Optionally, HTML & PDF versions of the manual pages can be built and
  73 installed as follows:
  74
  75         make html
  76         make install-html
  77         make pdf
  78         make install-pdf
  79
  80 Again, `root' priviliges may be needed at the install stages.
  81
  82
  83
  84 Custom build options on a POSIX system
  85 --------------------------------------
  86
  87 Selection of optional libraries and of other build options can be made
  88 by adding parameters to the `./configure' command line (above).  Run
  89
  90         ./configure --help
  91
  92 for a complete list of options.
  93
  94 Each optional file-format may be configured to be loaded statically
  95 (the default) or dynamically.  The dynamic option may be useful for
  96 distribution packaging reasons -- for example, to keep separate `free'
  97 and `non-free' software.
  98
  99 If you are building SoX for a `distribution' (i.e. the build will be
 100 used by others), please use --with-distro to identify the distribution
 101 as this information is useful in helping to diagnose SoX bug reports.
 102 For example,
 103
 104         ./configure --with-distro='Super Linux OS 6.1'
 105
 106 If any libraries are installed in a non-standard locations in your
 107 system then you can use the CPPFLAGS and LDFLAGS variables to allow
 108 configure to find them. For example:
 109
 110 ./configure CPPFLAGS="-I/home/sox/include -I/usr/local/multimedia/include" LDFLAGS="-L/home/sox/lib -L/usr/local/multimedia/lib"
 111
 112 If you are compiling under cygwin and would like to create a static
 113 sox.exe using mingw libraries then you can use the following:
 114
 115 ./configure CC="gcc -mno-cygwin" --disable-shared
 116
 117 The next cygwin example is used to build the cygwin version of SoX that is
 118 distributed by the project.  It tells gcc to prefer static libraries
 119 over dynamic ones and to use some static libraries compiled manually
 120 and installed under /usr/local.
 121
 122 ./configure LDFLAGS="-static -L/usr/local/lib" CPPFLAGS=-I/usr/local/include
 123
 124 You can run "cygcheck.exe src/sox.exe" after compiling to see which
 125 dynamic DLL's will be required to be distributed with the cygwin
 126 executable.
 127
 128 Alternatively, you can make use of the "cygbuild" script distributed
 129 with SoX source that is used to automate all steps of building
 130 a win32 package.  "osxbuild" script is used to automate all steps
 131 of building a MacOS X package.
 132
 133 Newer versions of SoX include support for loading libraries for
 134 file formats at runtime.  The main usage of this feature is to
 135 allow shipping SoX without dependencies on external libraries
 136 that are not globally used or have redistribution restrictions.
 137 If you experience problems with this then you may wish to disable
 138 this feature:
 139
 140 ./configure --without-libltdl
 141
 142 Also, the default behavior even when libltdl is used is to link
 143 all file format handlers into libsox as there is a performance
 144 hit when dynamically loading external libraries.  To force a format
 145 handler to be built as a dynamically loaded module, pass "dyn" to
 146 its --with-* option.  For example, to build pulseaudio handler as
 147 an external dynamic library:
 148
 149 ./configure --with-pulseaudio=dyn
 150
 151 A subset of external libraries can be configured to be dlopen()'ed
 152 at run time instead of being linked in.  This will allow one to
 153 distribute a binary with optional features that only require
 154 a user to install the missing libraries into their system.  This
 155 can be enabled using:
 156
 157 --enable-dl-lame
 158 --enable-dl-mad
 159 --enable-dl-sndfile
 160 --enable-dl-amrnb
 161 --enable-dl-amrwb
 162
 163 Testing
 164 -------
 165
 166 N.B.: If SoX is configured and compiled to load some file-formats
 167 dynamically, then it will not be able to load them when running SoX
 168 executables from within the source file directory until after SoX has
 169 been installed (temporarily configuring with --without-libltdl removes
 170 this restriction).
 171
 172 After successfully compiling SoX, try translating a sound file.  You
 173 should also playback the new file to make sure it sounds like the
 174 original.  You can either use an external program or SoX itself
 175 if compiled with playback support.
 176
 177 To work with widest range of playback programs, you should chose a
 178 format that is native to your OS; such as .wav for Windows or .aiff for
 179 MacOS.  In the following example, we'll use .xxx as the extension of
 180 your preferred format.
 181
 182         cd src
 183         ./sox monkey.wav monkey.xxx
 184
 185 You may have to give the sample format and rate for the file. For example,
 186 this command will make a sound file with a data rate of 12,500 samples
 187 per second and the data formatted as 16-bit signed integers:
 188
 189         ./sox monkey.wav -r 12500 -b 16 -e signed-integer monkey.xxx
 190
 191 If playback support was compiled in then it can be played like this:
 192
 193         ./play monkey.xxx
 194
 195 or, equivalently:
 196
 197         ./sox monkey.xxx -d
 198
 199 If monkey.xxx plays properly (it's a very short monkey screech),
 200 congratulations! SoX works.
 201
 202 If you're adding new features to SoX or want to perform advance tests
 203 on a new platform then you can use the scripts "tests.sh" and
 204 "testall.sh" to stress SoX.