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.). For other 6compilers/systems, it is often possible to manually construct a custom 7`soxconfig.h' and `Makefile' for that system (the minimum requirements 8are 32-bit CPU, 64-bit FPU, C89 compiler). 9 10Note that the `play', `rec', and `soxi' programs are in fact just 11copies-of or links-to (depending on OS) `sox'. 12 13SoX optionally makes use of some external libraries to obtain support 14for additional file formats and/or effects. Optional libraries should 15be installed before compiling SoX. The current list of supported 16libraries, where to get them (if not from your OS distribution), and 17their licence types, is as follows: 18 19OpencoreAMR-NB/WB http://sourceforge.net/projects/opencore-amr Apache 20VisualOn AMR-WB http://sourceforge.net/projects/opencore-amr Apache 21AO http://xiph.org/ao GPL 22FLAC http://flac.sourceforge.net BSD 23LADSPA http://www.ladspa.org LGPL + plugins' licence 24Lame MP3 encoder http://lame.sourceforge.net LGPL 25Twolame MP2 enc. http://www.twolame.org LGPL 26libltdl http://www.gnu.org/software/libtool LGPL 27MAD MP3 decoder http://www.underbit.com/products/mad GPL 28MP3 ID3 tags http://www.underbit.com/products/mad GPL 29Magic http://www.darwinsys.com/file BSD 30Ogg Vorbis http://www.vorbis.com BSD 31Opus http://www.opus-codec.org/ BSD 32PNG http://www.libpng.org/pub/png zlib (BSD-like) 33Sndfile http://www.mega-nerd.com/libsndfile LGPL 34WavPack http://www.wavpack.com BSD 35 36 37 38Compiling and installing on a POSIX system 39------------------------------------------ 40 41First install any optional libraries that you need for SoX. Some 42libraries may require pkg-config to be installed to be properly 43detected by SoX. 44 45[Only if you're compiling the git sources, first make sure you have 46the GNU autotools (automake >= 1.9, autoconf >= 2.62, autoconf-archive) 47installed, then run 48 49 autoreconf -i 50] 51 52To compile and install SoX (executables, libraries, manual pages) with 53a default configuration for your platform, run the following commands: 54 55 ./configure 56 make 57 make install 58 59There should be no errors and few, if any, warnings during the `make' 60stage. Any warnings about pointer mismatch or conversion should 61be treated with deep suspicion. 62 63The `make install' command may require `root' priviliges. 64 65To run a selection of tests on the installed sox executable: 66 67 make installcheck 68 69Optionally, HTML & PDF versions of the manual pages can be built and 70installed as follows: 71 72 make html 73 make install-html 74 make pdf 75 make install-pdf 76 77Again, `root' priviliges may be needed at the install stages. 78 79 80 81Custom build options 82-------------------- 83 84Selection of optional libraries and of other build options can be made 85by adding parameters to the `./configure' command line (above). Run 86 87 ./configure --help 88 89for a complete list of options. 90 91Each optional file-format may be configured to be loaded statically 92(the default) or dynamically. The dynamic option may be useful for 93distribution packaging reasons -- for example, to keep separate `free' 94and `non-free' software. 95 96If you are building SoX for a `distribution' (i.e. the build will be 97used by others), please use --with-distro to identify the distribution 98as this information is useful in helping to diagnose SoX bug reports. 99For example, 100 101 ./configure --with-distro='Super Linux OS 6.1' 102 103If any libraries are installed in a non-standard locations in your 104system, the compiler and linker must be informed of this. Often, 105environment variables can be used for this purpose. For example, if 106using the GNU or Clang/LLVM toolchains, the following might be used in 107a Bourne-compatible shell: 108 109export CPATH=/usr/local/include 110export LIBRARY_PATH=/usr/local/lib 111 112For other compilers and shells, consult their respective manuals. 113 114Optional features 115----------------- 116 117Support for some file formats is optional and controlled by --enable-* 118flags to configure. If the value "dyn" is passed to these flags, 119e.g. --enable-flac=dyn, the corresponding code is built as a module 120and loaded at runtime. 121 122Use of external libraries is controlled by --with-* flags. Some of 123these accept the value "dyn" to enable runtime loading of the library. 124 125The runtime loading feature is mainly useful for distributing the 126"sox" executable to systems that may not have all the external 127libraries installed. 128 129For a complete list of optional formats and libraries, including which 130support runtime loading, refer to the "configure --help" output. 131 132Testing 133------- 134 135N.B.: If SoX is configured and compiled to load some file-formats 136dynamically, then it will not be able to load them when running SoX 137executables from within the source file directory until after SoX has 138been installed (temporarily configuring with --without-libltdl removes 139this restriction). 140 141After successfully compiling SoX, try translating a sound file. You 142should also playback the new file to make sure it sounds like the 143original. You can either use an external program or SoX itself 144if compiled with playback support. 145 146To work with widest range of playback programs, you should chose a 147format that is native to your OS; such as .wav for Windows or .aiff for 148MacOS. In the following example, we'll use .xxx as the extension of 149your preferred format. 150 151 cd src 152 ./sox monkey.wav monkey.xxx 153 154You may have to give the sample format and rate for the file. For example, 155this command will make a sound file with a data rate of 12,500 samples 156per 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 160If playback support was compiled in then it can be played like this: 161 162 ./play monkey.xxx 163 164or, equivalently: 165 166 ./sox monkey.xxx -d 167 168If monkey.xxx plays properly (it's a very short monkey screech), 169congratulations! SoX works. 170 171If you're adding new features to SoX or want to perform advance tests 172on a new platform then you can use the scripts "tests.sh" and 173"testall.sh" to stress SoX. 174