README.md

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