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, libsndfile, and libmpg123. A built-in standard wave file reader is
  30 also available to support basic PCM formats, as well as built-in decoders for
  31 FLAC (dr_flac) and MP3 (minimp3). Application-defined decoders are also
  32 supported in case the default set are insufficient.
  33
  34 And much more...
  35
  36 Building
  37 --------
  38
  39 #### - Dependencies -
  40 Before even building, Alure requires the OpenAL development files installed,
  41 for example, through Creative's OpenAL SDK (available from openal.org) or from
  42 OpenAL Soft. Additionally you will need a C++11 or above compliant compiler to
  43 be able to build Alure.
  44
  45 These following dependencies are only needed to *automatically* support the
  46 formats they handle;
  47
  48 * [ogg](https://xiph.org/ogg/) : ogg playback
  49 * [vorbis](https://xiph.org/vorbis/) : ogg vorbis 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 OPUS: C:/msys64/mingw64/lib/libopusfile.dll.a
  94     -- Found SndFile: C:/msys64/mingw64/lib/libsndfile.dll.a
  95     -- Found MPG123: C:/msys64/mingw64/lib/libmpg123.dll.a
  96     -- Found PhysFS: C:/msys64/mingw64/lib/libphysfs.dll.a
  97     -- Found DUMB: C:/msys64/mingw64/lib/libdumb.dll.a
  98     -- Configuring done
  99     -- Generating done
 100     -- Build files have been written to: .../alure/cmake-build-debug
 101
 102
 103 Use `make install` to install Alure library in `C:\Program Files (x86)` for it
 104 to be available on your system. Otherwise simply run `make` to build the
 105 library and each example you have the dependencies for. Note if you use mingw
 106 (or mingw-w64, the name is the same for both) you may need to use
 107 `mingw32-make.exe` instead of `make`, and make sure that file is located in
 108 your path.  Note you may need to run `make install` as admin.
 109
 110 #### - Linux -
 111
 112 If you are using Ubuntu, many of the pre-requisites may be installed, however
 113 you may find that many of the header files are not.  Here is the full list of
 114 packages that must be installed. The list is in the format:
 115
 116 >[dependency name]: [library package name], [header package name]
 117
 118 * openal-soft : libopenal1, libopenal-dev
 119 * ogg : libogg0, libogg-dev
 120 * vorbis : libvorbis0a, libvorbis-dev
 121 * opusfile : libopusfule0, libopusfile-dev
 122 * SndFile : libsndfile1, libsndfile1-dev
 123 * mpg123 : libmpg123-0, libmpg123-dev
 124 * physfs : libphysfs1, libphysfs1-dev
 125 * dumb : libdumb1, libdumb1-dev
 126
 127 For each package pair, run `sudo apt-get install [packagename]`. After doing so
 128 you should get a cmake output that looks something like:
 129
 130
 131     -- Found OpenAL: /usr/lib/x86_64-linux-gnu/libopenal.so
 132     -- Performing Test HAVE_STD_CXX11
 133     -- Performing Test HAVE_STD_CXX11 - Success
 134     -- Performing Test HAVE_WALL_SWITCH
 135     -- Performing Test HAVE_WALL_SWITCH - Success
 136     -- Performing Test HAVE_WEXTRA_SWITCH
 137     -- Performing Test HAVE_WEXTRA_SWITCH - Success
 138     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY
 139     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY - Success
 140     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH
 141     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH - Success
 142     -- Found OGG: /usr/lib/x86_64-linux-gnu/libogg.so
 143     -- Found VORBIS: /usr/lib/x86_64-linux-gnu/libvorbisfile.so
 144     -- Found OPUS: /usr/lib/libopusfile.so
 145     -- Found SndFile: /usr/lib/x86_64-linux-gnu/libsndfile.so
 146     -- Found MPG123: /usr/lib/x86_64-linux-gnu/libmpg123.so
 147     -- Found PhysFS: /usr/lib/x86_64-linux-gnu/libphysfs.so
 148     -- Found DUMB: /usr/lib/x86_64-linux-gnu/libdumb.so
 149     -- Configuring done
 150     -- Generating done
 151     -- Build files have been written to: .../alure/cmake-build-debug
 152
 153 Use `sudo make install` to install Alure library on your system. Otherwise
 154 simply run `make` to build the library and each example you have the
 155 dependencies for.
 156
 157 #### - OSX -
 158
 159 TODO
 160