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, and libsndfile. A built-in wave file reader is also available to
  30 support basic PCM formats, as well as built-in decoders for FLAC (dr_flac) and
  31 MP3 (minimp3). Application-defined decoders are also supported in case the
  32 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
  53 Two of the packaged examples require the following dependencies to be built.
  54
  55 * [PhysFS](https://icculus.org/physfs/) : alure-physfs
  56 * [dumb](https://github.com/kode54/dumb) : alure-dumb
  57
  58 If any dependency isn't found at build time the relevant decoders or examples
  59 will be disabled and skipped during build.
  60
  61 #### - Windows -
  62
  63 If your are using [MinGW-w64](https://mingw-w64.org/doku.php), the easiest way
  64 to get all of the dependencies above is to use [MSYS2](http://www.msys2.org/),
  65 which has up-to-date binaries for all of the optional and required dependencies
  66 above (so you don't need to build each from scratch).
  67
  68 Follow the MSYS2 installation guide and then look for each dependency on MSYS2
  69 package repo and `pacman -S [packagename]` each package to acquire all
  70 dependencies.
  71
  72 After acquiring all dependencies, you will need to make sure that the includes,
  73 libraries, and binaries for each file are in your path. For most dependencies
  74 this isn't a big deal, if you are using msys these directories are simply
  75 `msys/mingw64/bin`, `msys/mingw64/lib` and `msys/mingw64/include`. However the
  76 cmake file for Alure requires you to use the direct directory where OpenAL Soft
  77 headers are located (so instead of `msys/mingw64/include`, it's
  78 `msys/mingw64/include/AL`).
  79
  80 After cmake generation you should have something that looks like the following
  81 output if you have every single dependency:
  82
  83     -- Found OpenAL: C:/msys64/mingw64/lib/libopenal.dll.a
  84     -- Performing Test HAVE_STD_CXX11
  85     -- Performing Test HAVE_STD_CXX11 - Success
  86     -- Performing Test HAVE_WALL_SWITCH
  87     -- Performing Test HAVE_WALL_SWITCH - Success
  88     -- Performing Test HAVE_WEXTRA_SWITCH
  89     -- Performing Test HAVE_WEXTRA_SWITCH - Success
  90     -- Found OGG: C:/msys64/mingw64/lib/libogg.dll.a
  91     -- Found VORBIS: C:/msys64/mingw64/lib/libvorbisfile.dll.a
  92     -- Found OPUS: C:/msys64/mingw64/lib/libopusfile.dll.a
  93     -- Found SndFile: C:/msys64/mingw64/lib/libsndfile.dll.a
  94     -- Found PhysFS: C:/msys64/mingw64/lib/libphysfs.dll.a
  95     -- Found DUMB: C:/msys64/mingw64/lib/libdumb.dll.a
  96     -- Configuring done
  97     -- Generating done
  98     -- Build files have been written to: .../alure/cmake-build-debug
  99
 100
 101 Use `make install` to install Alure library in `C:\Program Files (x86)` for it
 102 to be available on your system. Otherwise simply run `make` to build the
 103 library and each example you have the dependencies for. Note if you use mingw
 104 (or mingw-w64, the name is the same for both) you may need to use
 105 `mingw32-make.exe` instead of `make`, and make sure that file is located in
 106 your path.  Note you may need to run `make install` as admin.
 107
 108 #### - Linux -
 109
 110 If you are using Ubuntu, many of the pre-requisites may be installed, however
 111 you may find that many of the header files are not.  Here is the full list of
 112 packages that must be installed. The list is in the format:
 113
 114 >[dependency name]: [library package name], [header package name]
 115
 116 * openal-soft : libopenal1, libopenal-dev
 117 * ogg : libogg0, libogg-dev
 118 * vorbis : libvorbis0a, libvorbis-dev
 119 * opusfile : libopusfule0, libopusfile-dev
 120 * SndFile : libsndfile1, libsndfile1-dev
 121 * physfs : libphysfs1, libphysfs1-dev
 122 * dumb : libdumb1, libdumb1-dev
 123
 124 For each package pair, run `sudo apt-get install [packagename]`. After doing so
 125 you should get a cmake output that looks something like:
 126
 127
 128     -- Found OpenAL: /usr/lib/x86_64-linux-gnu/libopenal.so
 129     -- Performing Test HAVE_STD_CXX11
 130     -- Performing Test HAVE_STD_CXX11 - Success
 131     -- Performing Test HAVE_WALL_SWITCH
 132     -- Performing Test HAVE_WALL_SWITCH - Success
 133     -- Performing Test HAVE_WEXTRA_SWITCH
 134     -- Performing Test HAVE_WEXTRA_SWITCH - Success
 135     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY
 136     -- Performing Test HAVE_GCC_DEFAULT_VISIBILITY - Success
 137     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH
 138     -- Performing Test HAVE_VISIBILITY_HIDDEN_SWITCH - Success
 139     -- Found OGG: /usr/lib/x86_64-linux-gnu/libogg.so
 140     -- Found VORBIS: /usr/lib/x86_64-linux-gnu/libvorbisfile.so
 141     -- Found OPUS: /usr/lib/libopusfile.so
 142     -- Found SndFile: /usr/lib/x86_64-linux-gnu/libsndfile.so
 143     -- Found PhysFS: /usr/lib/x86_64-linux-gnu/libphysfs.so
 144     -- Found DUMB: /usr/lib/x86_64-linux-gnu/libdumb.so
 145     -- Configuring done
 146     -- Generating done
 147     -- Build files have been written to: .../alure/cmake-build-debug
 148
 149 Use `sudo make install` to install Alure library on your system. Otherwise
 150 simply run `make` to build the library and each example you have the
 151 dependencies for.
 152
 153 #### - OSX -
 154
 155 TODO
 156