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.).  Some
   6 non-POSIX compilers (such as MSVC) are supported via the `CMake' build
   7 utility.  For other compilers/systems, it is often possible to
   8 manually construct a custom `soxconfig.h' and `Makefile' for that
   9 system (the minimum requirements are 32-bit CPU, 64-bit FPU, C89
  10 compiler).
  11
  12 Note that the `play', `rec', and `soxi' programs are in fact just
  13 copies-of or links-to (depending on OS) `sox'.
  14
  15 SoX optionally makes use of some external libraries to obtain support
  16 for additional file formats and/or effects.  Optional libraries should
  17 be installed before compiling SoX.  The current list of supported
  18 libraries, where to get them (if not from your OS distribution), and
  19 their licence types, is as follows:
  20
  21 OpencoreAMR-NB/WB http://sourceforge.net/projects/opencore-amr  Apache
  22 AMR-NB/WB         http://www.penguin.cz/~utx/amr        See library web page
  23 AO                http://xiph.org/ao                    GPL
  24 FLAC              http://flac.sourceforge.net           BSD
  25 LADSPA            http://www.ladspa.org                 LGPL + plugins' licence
  26 Lame MP3 encoder  http://lame.sourceforge.net           LGPL
  27 Twolame MP2 enc.  http://www.twolame.org                LGPL
  28 libltdl           http://www.gnu.org/software/libtool   LGPL
  29 MAD MP3 decoder   http://www.underbit.com/products/mad  GPL
  30 MP3 ID3 tags      http://www.underbit.com/products/mad  GPL
  31 Magic             http://www.darwinsys.com/file         BSD
  32 Ogg Vorbis        http://www.vorbis.com                 BSD
  33 Opus              http://www.opus-codec.org/            BSD
  34 PNG               http://www.libpng.org/pub/png         zlib (BSD-like)
  35 Sndfile           http://www.mega-nerd.com/libsndfile   LGPL
  36 WavPack           http://www.wavpack.com                BSD
  37
  38
  39
  40 Compiling and installing on a POSIX system
  41 ------------------------------------------
  42
  43 First install any optional libraries that you need for SoX.  Some
  44 libraries may require pkg-config to be installed to be properly
  45 detected by SoX.
  46
  47 [Only if you're compiling the git sources, first make sure you have
  48 the GNU autotools installed (automake >= 1.9, autoconf >= 2.62) and
  49 run
  50
  51         autoreconf -i
  52 ]
  53
  54 To compile and install SoX (executables, libraries, manual pages) with
  55 a default configuration for your platform, run the following commands:
  56
  57         ./configure
  58         make -s
  59         make install
  60
  61 There should be no errors and few, if any, warnings during the `make
  62 -s' stage.  Any warnings about pointer mismatch or conversion should
  63 be treated with deep suspicion.
  64
  65 The `make install' command may require `root' priviliges; for example,
  66 on some systems, the following modification to the command is needed:
  67
  68         sudo make install
  69
  70 To run a selection of tests on the installed sox executable:
  71
  72         make installcheck
  73
  74 Optionally, HTML & PDF versions of the manual pages can be built and
  75 installed as follows:
  76
  77         make html
  78         make install-html
  79         make pdf
  80         make install-pdf
  81
  82 Again, `root' priviliges may be needed at the install stages.
  83
  84
  85
  86 Custom build options on a POSIX system
  87 --------------------------------------
  88
  89 Selection of optional libraries and of other build options can be made
  90 by adding parameters to the `./configure' command line (above).  Run
  91
  92         ./configure --help
  93
  94 for a complete list of options.
  95
  96 Each optional file-format may be configured to be loaded statically
  97 (the default) or dynamically.  The dynamic option may be useful for
  98 distribution packaging reasons -- for example, to keep separate `free'
  99 and `non-free' software.
 100
 101 If you are building SoX for a `distribution' (i.e. the build will be
 102 used by others), please use --with-distro to identify the distribution
 103 as this information is useful in helping to diagnose SoX bug reports.
 104 For example,
 105
 106         ./configure --with-distro='Super Linux OS 6.1'
 107
 108 If any libraries are installed in a non-standard locations in your
 109 system then you can use the CPPFLAGS and LDFLAGS variables to allow
 110 configure to find them. For example:
 111
 112 ./configure CPPFLAGS="-I/home/sox/include -I/usr/local/multimedia/include" LDFLAGS="-L/home/sox/lib -L/usr/local/multimedia/lib"
 113
 114 If you are compiling under cygwin and would like to create a static
 115 sox.exe using mingw libraries then you can use the following:
 116
 117 ./configure CC="gcc -mno-cygwin" --disable-shared
 118
 119 The next cygwin example is used to build the cygwin version of SoX that is
 120 distributed by the project.  It tells gcc to prefer static libraries
 121 over dynamic ones and to use some static libraries compiled manually
 122 and installed under /usr/local.
 123
 124 ./configure LDFLAGS="-static -L/usr/local/lib" CPPFLAGS=-I/usr/local/include
 125
 126 You can run "cygcheck.exe src/sox.exe" after compiling to see which
 127 dynamic DLL's will be required to be distributed with the cygwin
 128 executable.
 129
 130 Alternatively, you can make use of the "cygbuild" script distributed
 131 with SoX source that is used to automate all steps of building
 132 a win32 package.  "osxbuild" script is used to automate all steps
 133 of building a MacOS X package.
 134
 135 Newer versions of SoX include support for loading libraries for
 136 file formats at runtime.  The main usage of this feature is to
 137 allow shipping SoX without dependencies on external libraries
 138 that are not globally used or have redistribution restrictions.
 139 If you experience problems with this then you may wish to disable
 140 this feature:
 141
 142 ./configure --without-libltdl
 143
 144 Also, the default behavior even when libltdl is used is to link
 145 all file format handlers into libsox as there is a performance
 146 hit when dynamically loading external libraries.  To force a format
 147 handler to be built as a dynamically loaded module, pass "dyn" to
 148 its --with-* option.  For example, to build pulseaudio handler as
 149 an external dynamic library:
 150
 151 ./configure --with-pulseaudio=dyn
 152
 153 A subset of external libraries can be configured to be dlopen()'ed
 154 at run time instead of being linked in.  This will allow one to
 155 distribute a binary with optional features that only require
 156 a user to install the missing libraries into their system.  This
 157 can be enabled using:
 158
 159 --enable-dl-lame
 160 --enable-dl-mad
 161 --enable-dl-sndfile
 162 --enable-dl-amrnb
 163 --enable-dl-amrwb
 164
 165 Testing
 166 -------
 167
 168 N.B.: If SoX is configured and compiled to load some file-formats
 169 dynamically, then it will not be able to load them when running SoX
 170 executables from within the source file directory until after SoX has
 171 been installed (temporarily configuring with --without-libltdl removes
 172 this restriction).
 173
 174 After successfully compiling SoX, try translating a sound file.  You
 175 should also playback the new file to make sure it sounds like the
 176 original.  You can either use an external program or SoX itself
 177 if compiled with playback support.
 178
 179 To work with widest range of playback programs, you should chose a
 180 format that is native to your OS; such as .wav for Windows or .aiff for
 181 MacOS.  In the following example, we'll use .xxx as the extension of
 182 your preferred format.
 183
 184         cd src
 185         ./sox monkey.wav monkey.xxx
 186
 187 You may have to give the word size and rate for the file. For example,
 188 this command will make a sound file with a data rate of 12,500 samples
 189 per second and the data formatted as 2-byte (16-bit) signed integers:
 190
 191         ./sox monkey.wav -r 12500 -2 -s monkey.xxx
 192
 193 If playback support was compiled in then it can be played like this:
 194
 195         ./play monkey.xxx
 196
 197 or, equivalently:
 198
 199         ./sox monkey.xxx -d
 200
 201 If monkey.xxx plays properly (it's a very short monkey screech),
 202 congratulations! SoX works.
 203
 204 If you're adding new features to SoX or want to perform advance tests
 205 on a new platform then you can use the scripts "tests.sh" and
 206 "testall.sh" to stress SoX.
 207
 208
 209
 210 Compiling using Microsoft's Visual C
 211 ------------------------------------
 212
 213 To compile a full-featured build of SoX with Visual Studio 2008 (msvc9),
 214 Visual Studio 2010 (msvc10), or the Windows SDK 7.1, you may be able to use the
 215 preconfigured solution found in the sox\msvc9 (VS2008) or sox\msvc10 (VS2010 or
 216 Windows SDK 7.1) folder. See sox\msvc9\readme.txt or sox\msvc10\readme.txt for
 217 details on building using the corresponding Microsoft C compiler. If the
 218 preconfigured solution doesn't work for you, build with CMake as follows:
 219
 220 o Install cmake (http://www.cmake.org/HTML/Download.html)
 221 o Install any optional libraries to use with SoX
 222 o Unpack the SoX sources (...tar.gz) to say c:\sox
 223 o Type cd c:\sox
 224 o Type cmake -G "compiler" .   (type cmake --help for list of compilers)
 225
 226 This should generate project build files for use with Visual C.
 227
 228
 229
 230 Appendix: How To Compile SoX with MP3 Support on Win32
 231 ------------------------------------------------------
 232
 233 The solution files in msvc9 and msvc10 will build SoX to dynamically load
 234 libmad.dll and libmp3lame.dll at runtime.
 235
 236 The following text, untested by the SoX team, was originally written
 237 by `Enter AG' and released to the public domain. It includes instructions for
 238 building SoX with MP3 support linked directly into the SoX executable.
 239
 240 = How To Compile Sox with MP3 Support =
 241
 242 == Requirements ==
 243
 244 The following requirements have been tested. Nevertheless, other
 245 versions may work as well.
 246
 247 o Microsoft Windows (Win32, Win2000, XP, Win2003, Vista, etc.).
 248
 249 o CMake (Cross Platform Make) version 2.4
 250   available on [http://www.cmake.org]
 251
 252 o Microsoft Visual Stuio 2008 (earlier versions should also work).
 253
 254 o SoX source distribution version 14.0.1
 255   available on [http://sox.sourceforge.net]
 256
 257 o LAME source distribution version 3.97. LAME 3.98 is required for full ID3 tag
 258   support. Available on [http://lame.sourceforge.net]
 259
 260 o MAD source distribution version 0.15.1b
 261   available on [http://www.underbit.com/products/mad/]
 262
 263 == Compilation Procedure ==
 264
 265 === Compilation of the LAME libraries ===
 266
 267 o Extract the LAME source distribution and open it as a Visual Studio project
 268   using the VS file in the top directory.
 269
 270 o Set the ''libmp3lame'' "Configuration Properties -> C/C++ -> Code Generation
 271   -> Runtime Library" to Multi-threaded DLL (/MD).
 272
 273 o Do the same for ''mpglib'' .
 274
 275 o Build ''libmp3lame'' and ''mpglib.''
 276
 277 o Rename the static library libmp3lame.lib to mp3lame.lib.
 278
 279 o Create a folder somewhere with an arbitrary name. We used the name
 280   "lameforsox". Create in this folder a new folder called "lame" and copy the
 281   lame.h header file into it. Copy mp3lame.lib and mpglib.lib in the lameforsox
 282   folder. Now you should have prepared the lame components for further use like
 283   this:
 284         ...\[somewhere]\lameforsox\
 285                 mp3lame.lib
 286                 mpglib.lib
 287                         \lame\
 288                                 lame.h
 289
 290 === Compilation of the MAD library ===
 291
 292 o Compile ''libmad'' with the same "Runtime Library" settings as described for
 293   LAME (previous section Compilation of the LAME libraries).
 294
 295 o Rename the static library libmad.lib to mad.lib.
 296
 297 === Compilation of SoX with the LAME and MAD libraries ===
 298
 299 o Open Visual Studio and add in "Tools -> Options -> Projects and Solutions ->
 300   VC++ Directories" in the "Include Directories" collection the folder
 301   containing the MAD header file mad.h and the folder containing lame/lame.h
 302   (...\[somewhere]\lameforsox).  Add in the "Library files" collection the
 303   folder containing mad.lib and the folder containing the lame libraries
 304   mp3lame.lib and mpglib.lib (...\[somewhere]\lameforsox).
 305
 306 o Edit the CMakeLists.txt in the SoX top directory:
 307   Add
 308   set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} mpglib)
 309   after some blank lines beneath the statement
 310   if(NEED_LIBM)
 311   set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} -lm)
 312   endif(NEED_LIBM)
 313
 314 o Open the windows command line console and change into the SoX top directory.
 315
 316 o Execute cmake like this:
 317   cmake.exe ./ -G "Visual Studio 9 2008"
 318
 319 o If the Visual Studio settings are done as described above the following cmake
 320   output should appear:
 321   ...
 322   include files HAVE_MAD_H1 - found
 323   mad_stream_buffer in madmad_stream_buffer in mad - found
 324   ...
 325   include files HAVE_LAME_LAME_H1 - found
 326   lame_init in mp3lamelame_init in mp3lame - found
 327   ...
 328
 329 o If not check CMakeFiles\CMakeError.log.
 330
 331 o Open Visual Studio and open the SoX solution file in the SoX top directory
 332   (sox.sln).
 333
 334 o Rebuild "ALL_BUILD" and confirm all "File Modification Detected" dialogs
 335   with "Reload".
 336
 337 o Add in the libsox "Preprocessor Definitions" (right click on libsox ->
 338   Properties -> Configuration Properties -> C/C++ -> Preprocessor) HAVE_STRING_H
 339   before the first line.  Set the "Runtime Library" to Multi-threaded DLL (/MD)
 340   as described above.
 341
 342 o Do the same for sox and add in the "Additional Dependencies" (Linker -> Input)
 343   after the last line mpglib.lib.
 344
 345 o Now build libsox
 346
 347 o and then sox.
 348
 349 o Sox now prompts "mp3, mp2" in the usage output in the section "SUPPORTED FILE
 350   FORMATS".