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
  57         make install
  58
  59 There should be no errors and few, if any, warnings during the `make'
  60 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.
  64
  65 To run a selection of tests on the installed sox executable:
  66
  67         make installcheck
  68
  69 Optionally, HTML & PDF versions of the manual pages can be built and
  70 installed as follows:
  71
  72         make html
  73         make install-html
  74         make pdf
  75         make install-pdf
  76
  77 Again, `root' priviliges may be needed at the install stages.
  78
  79
  80
  81 Custom build options
  82 --------------------
  83
  84 Selection of optional libraries and of other build options can be made
  85 by adding parameters to the `./configure' command line (above).  Run
  86
  87         ./configure --help
  88
  89 for a complete list of options.
  90
  91 Each optional file-format may be configured to be loaded statically
  92 (the default) or dynamically.  The dynamic option may be useful for
  93 distribution packaging reasons -- for example, to keep separate `free'
  94 and `non-free' software.
  95
  96 If you are building SoX for a `distribution' (i.e. the build will be
  97 used by others), please use --with-distro to identify the distribution
  98 as this information is useful in helping to diagnose SoX bug reports.
  99 For example,
 100
 101         ./configure --with-distro='Super Linux OS 6.1'
 102
 103 If any libraries are installed in a non-standard locations in your
 104 system, the compiler and linker must be informed of this.  Often,
 105 environment variables can be used for this purpose.  For example, if
 106 using the GNU or Clang/LLVM toolchains, the following might be used in
 107 a Bourne-compatible shell:
 108
 109 export CPATH=/usr/local/include
 110 export LIBRARY_PATH=/usr/local/lib
 111
 112 For other compilers and shells, consult their respective manuals.
 113
 114 Optional features
 115 -----------------
 116
 117 Support for some file formats is optional and controlled by --enable-*
 118 flags to configure.  If the value "dyn" is passed to these flags,
 119 e.g. --enable-flac=dyn, the corresponding code is built as a module
 120 and loaded at runtime.
 121
 122 Use of external libraries is controlled by --with-* flags.  Some of
 123 these accept the value "dyn" to enable runtime loading of the library.
 124
 125 The runtime loading feature is mainly useful for distributing the
 126 "sox" executable to systems that may not have all the external
 127 libraries installed.
 128
 129 For a complete list of optional formats and libraries, including which
 130 support runtime loading, refer to the "configure --help" output.
 131
 132 Testing
 133 -------
 134
 135 N.B.: If SoX is configured and compiled to load some file-formats
 136 dynamically, then it will not be able to load them when running SoX
 137 executables from within the source file directory until after SoX has
 138 been installed (temporarily configuring with --without-libltdl removes
 139 this restriction).
 140
 141 After successfully compiling SoX, try translating a sound file.  You
 142 should also playback the new file to make sure it sounds like the
 143 original.  You can either use an external program or SoX itself
 144 if compiled with playback support.
 145
 146 To work with widest range of playback programs, you should chose a
 147 format that is native to your OS; such as .wav for Windows or .aiff for
 148 MacOS.  In the following example, we'll use .xxx as the extension of
 149 your preferred format.
 150
 151         cd src
 152         ./sox monkey.wav monkey.xxx
 153
 154 You may have to give the sample format and rate for the file. For example,
 155 this command will make a sound file with a data rate of 12,500 samples
 156 per second and the data formatted as 16-bit signed integers:
 157
 158         ./sox monkey.wav -r 12500 -b 16 -e signed-integer monkey.xxx
 159
 160 If playback support was compiled in then it can be played like this:
 161
 162         ./play monkey.xxx
 163
 164 or, equivalently:
 165
 166         ./sox monkey.xxx -d
 167
 168 If monkey.xxx plays properly (it's a very short monkey screech),
 169 congratulations! SoX works.
 170
 171 If you're adding new features to SoX or want to perform advance tests
 172 on a new platform then you can use the scripts "tests.sh" and
 173 "testall.sh" to stress SoX.