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