README.md

   1 Alure
   2 =====
   3
   4 [![Build Status](https://api.travis-ci.org/kcat/alure.svg)](https://travis-ci.org/kcat/alure)
   5
   6 Alure is a C++ 3D audio API. It uses OpenAL for audio rendering, and provides
   7 common higher-level features such as file loading and decoding, buffer caching,
   8 background streaming, and source management for virtually unlimited sound
   9 source handles.
  10
  11 Features
  12 --------
  13
  14 Alure supports 3D sound rendering based on standard OpenAL features. Extra 3D
  15 sound features may be available depending on the extensions supported by OpenAL
  16 (newer versions of OpenAL Soft provide the necessary extensions and is thus
  17 recommended, but is not required if those features aren't of interest).
  18
  19 Environmental audio effects are supported with the ALC_EXT_EFX extension. This
  20 provides multi-zone reverb, sound occlusion and obstruction (simulating sounds
  21 being behind doors or walls), and atmospheric air absorption.
  22
  23 Binaural (HRTF) rendering is provided with the ALC_SOFT_HRTF extension. When
  24 used with headphones, this provides an unparalleled sense of 3D sound
  25 positioning. Multiple and custom profiles can also be select from to get a
  26 closer match for different people.
  27
  28 Alure supports decoding audio files using external libraries: VorbisFile,
  29 OpusFile, libFLAC, libsndfile, and libmpg123. A built-in standard wave file
  30 reader is also available, supporting basic PCM formats. Application-defined
  31 decoders are also supported in case the default set are insufficient.
  32
  33 And much more...
  34
  35 Building
  36 --------
  37
  38 #### - Dependencies -
  39 Before even building, Alure requires the OpenAL development files installed,
  40 for example, through Creative's OpenAL SDK (available from openal.org) or from
  41 OpenAL Soft. Additionally you will need a C++11 or above compliant compiler to
  42 be able to build Alure.
  43
  44 These following dependencies are only needed to *automatically* support the
  45 formats they handle;
  46
  47 * [ogg](https://xiph.org/ogg/) : ogg playback
  48 * [vorbis](https://xiph.org/vorbis/) : ogg vorbis playback
  49 * [flac](https://xiph.org/flac/) : flac playback
  50 * [opusfile](http://opus-codec.org/) : opus playback
  51 * [SndFile](http://www.mega-nerd.com/libsndfile/) : various multi-format playback
  52 * [mpg123](https://www.mpg123.de/) : mpeg audio playback
  53
  54 Two of the packaged examples require the following dependencies to be built.
  55
  56 * [PhysFS](https://icculus.org/physfs/) : alure-physfs
  57 * [dumb](https://github.com/kode54/dumb) : alure-dumb
  58
  59 If any dependency isn't found at build time the relevant decoders or examples
  60 will be disabled and skipped during build.
  61
  62 #### - Windows -
  63
  64 If your are using [MinGW-w64](https://mingw-w64.org/doku.php), the easiest way
  65 to get all of the dependencies above is to use [MSYS2](http://www.msys2.org/),
  66 which has up-to-date binaries for all of the optional and required dependencies
  67 above (so you don't need to build each from scratch).
  68
  69 Follow the MSYS2 installation guide and then look for each dependency on MSYS2
  70 package repo and `pacman -S [packagename]` each package to acquire all
  71 dependencies.
  72
  73 After acquiring all dependencies, you will need to make sure that the includes,
  74 libraries, and binaries for each file are in your path. For most dependencies
  75 this isn't a big deal, if you are using msys these directories are simply
  76 `msys/mingw64/bin`, `msys/mingw64/lib` and `msys/mingw64/include`. However the
  77 cmake file for Alure requires you to use the direct directory where OpenAL Soft
  78 headers are located (so instead of `msys/mingw64/include`, it's
  79 `msys/mingw64/include/AL`).
  80
  81 After cmake generation you should have something that looks like the following
  82 output if you have every single dependency:
  83
  84     -- Found OpenAL: C:/msys64/mingw64/lib/libopenal.dll.a
  85     -- Performing Test HAVE_STD_CXX11
  86     -- Performing Test HAVE_STD_CXX11 - Success
  87     -- Performing Test HAVE_WALL_SWITCH
  88     -- Performing Test HAVE_WALL_SWITCH - Success
  89     -- Performing Test HAVE_WEXTRA_SWITCH
  90     -- Performing Test HAVE_WEXTRA_SWITCH - Success
  91     -- Found OGG: C:/msys64/mingw64/lib/libogg.dll.a
  92     -- Found VORBIS: C:/msys64/mingw64/lib/libvorbisfile.dll.a
  93     -- Found FLAC: C:/msys64/mingw64/lib/libFLAC.dll.a
  94     -- Found OPUS: C:/msys64/mingw64/lib/libopusfile.dll.a
  95     -- Found SndFile: C:/msys64/mingw64/lib/libsndfile.dll.a
  96     -- Found MPG123: C:/msys64/mingw64/lib/libmpg123.dll.a
  97     -- Found PhysFS: C:/msys64/mingw64/lib/libphysfs.dll.a
  98     -- Found DUMB: C:/msys64/mingw64/lib/libdumb.dll.a
  99     -- Configuring done
 100     -- Generating done
 101     -- Build files have been written to: .../alure/cmake-build-debug
 102
 103
 104 Use `make install` to install Alure library in `C:\Program Files (x86)` for it
 105 to be available on your system. Otherwise simply run `make` to build the
 106 library and each example you have the dependencies for. Note if you use mingw
 107 (or mingw-w64, the name is the same for both) you may need to use
 108 `mingw32-make.exe` instead of `make`, and make sure that file is located in
 109 your path.  Note you may need to run `make install` as admin.
 110
 111 #### - Linux -
 112
 113 If you are using Ubuntu, many of the pre-requisites may be installed, however
 114 you may find that many of the header files are not.  Here is the full list of
 115 packages that must be installed. The list is in the format:
 116
 117 >[dependency name]: [library package name], [header package name]
 118
 119 * openal-soft : libopenal1, libopenal-dev
 120 * ogg : libogg0, libogg-dev
 121 * vorbis : libvorbis0a, libvorbis-dev
 122 * flac : libflac8, and libflac-dev
 123 * opusfile : libopusfule0, libopusfile-dev
 124 * SndFile : libsndfile1, libsndfile1-dev
 125 * mpg123 : libmpg123-0, libmpg123-dev
 126 * physfs : libphysfs1, libphysfs1-dev
 127 * dumb : libdumb1, libdumb1-dev
 128
 129 For each package pair, run `sudo apt-get install [packagename]`. After doing so
 130 you should get a cmake output that looks something like:
 131
 132
 133     -- Found OpenAL: /usr/lib/x86_64-linux-gnu/libopenal.so
 134     -- Performing Test HAVE_STD_CXX11
 135     -- Performing Test HAVE_STD_CXX11 - Success
 136     -- Performing Test HAVE_WALL_SWITCH
 137     -- Performing Test HAVE_WALL_SWITCH - Success
 138     -- Performing Test HAVE_WEXTRA_SWITCH
 139     -- Performing Test HAVE_WEXTRA_SWITCH - Success
 140     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY
 141     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY - Success
 142     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH
 143     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH - Success
 144     -- Found OGG: /usr/lib/x86_64-linux-gnu/libogg.so
 145     -- Found VORBIS: /usr/lib/x86_64-linux-gnu/libvorbisfile.so
 146     -- Found FLAC: /usr/lib/x86_64-linux-gnu/libFLAC.so
 147     -- Found OPUS: /usr/lib/libopusfile.so
 148     -- Found SndFile: /usr/lib/x86_64-linux-gnu/libsndfile.so
 149     -- Found MPG123: /usr/lib/x86_64-linux-gnu/libmpg123.so
 150     -- Found PhysFS: /usr/lib/x86_64-linux-gnu/libphysfs.so
 151     -- Found DUMB: /usr/lib/x86_64-linux-gnu/libdumb.so
 152     -- Configuring done
 153     -- Generating done
 154     -- Build files have been written to: .../alure/cmake-build-debug
 155
 156 Use `sudo make install` to install Alure library on your system. Otherwise
 157 simply run `make` to build the library and each example you have the
 158 dependencies for.
 159
 160 #### - OSX -
 161
 162 TODO
 163