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++14 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     -- Found Threads: TRUE
  88     -- Found OGG: C:/msys64/mingw64/lib/libogg.dll.a
  89     -- Found VORBIS: C:/msys64/mingw64/lib/libvorbisfile.dll.a
  90     -- Found OPUS: C:/msys64/mingw64/lib/libopusfile.dll.a
  91     -- Found SndFile: C:/msys64/mingw64/lib/libsndfile.dll.a
  92     -- Found PhysFS: C:/msys64/mingw64/lib/libphysfs.dll.a
  93     -- Found DUMB: C:/msys64/mingw64/lib/libdumb.dll.a
  94     -- Configuring done
  95     -- Generating done
  96     -- Build files have been written to: .../alure/build
  97
  98 Now you may compile the library and examples by running `cmake --build .`.
  99 Use `cmake --install .`, which probably requires administrative privilege,
 100 to install Alure library in `C:\Program Files (x86)` for it to be available
 101 on your system.
 102
 103 ### On GNU/Linux
 104 On Debian-based systems, the library's dependencies can be installed using
 105
 106     apt install libopenal-dev libvorbis-dev libopusfile-dev libsndfile1-dev
 107
 108 Optional dependencies for examples might be install via
 109
 110     apt install libphysfs-dev libdumb1-dev
 111
 112 On other distributions, the packages names can be adapted similarly.
 113
 114 Then inside `build`, the output of `cmake ..` should contains lines similar to
 115 the following
 116
 117     -- Found OpenAL: /usr/lib/x86_64-linux-gnu/libopenal.so
 118     -- Found Threads: TRUE
 119     -- Found OGG: /usr/lib/x86_64-linux-gnu/libogg.so
 120     -- Found VORBIS: /usr/lib/x86_64-linux-gnu/libvorbisfile.so
 121     -- Found OPUS: /usr/lib/libopusfile.so
 122     -- Found SndFile: /usr/lib/x86_64-linux-gnu/libsndfile.so
 123     -- Found PhysFS: /usr/lib/x86_64-linux-gnu/libphysfs.so
 124     -- Found DUMB: /usr/lib/x86_64-linux-gnu/libdumb.so
 125     -- Configuring done
 126     -- Generating done
 127     -- Build files have been written to: .../alure/build
 128
 129 To build the library and each example you have the dependencies for,
 130 run `cmake --build . --parallel $(nproc)`.  Use `sudo cmake --install .`
 131 to install Alure library on your system.
 132
 133 ### On macOS
 134 OpenAL is provided by Apple via [Core Audio], while optional codecs and
 135 examples' dependencies are available on [Homebrew](https://brew.sh/):
 136
 137     brew install libvorbis opusfile libsndfile
 138     brew install phyfs dumb
 139
 140 Then inside `build`, the output of `cmake ..` should contains lines similar to
 141 the following
 142
 143     -- Found OpenAL: /System/Library/Frameworks/OpenAL.framework
 144     -- Found Threads: TRUE
 145     -- Found OGG: /usr/local/lib/libogg.dylib
 146     -- Found VORBIS: /usr/local/lib/libvorbisfile.dylib
 147     -- Found OPUS: /usr/local/lib/libopusfile.dylib
 148     -- Found SndFile: /usr/local/lib/libsndfile.dylib
 149     -- Found PhysFS: /usr/local/lib/libphysfs.dylib
 150     -- Found DUMB: /usr/local/lib/libdumb.a
 151     -- Configuring done
 152     -- Generating done
 153     -- Build files have been written to: .../alure/build
 154
 155 If OpenAL Soft is preferred, one may install it from Homebrew and specify
 156 CMake prefix path accordingly
 157
 158     brew install openal-soft
 159     OPENALDIR=`brew --prefix openal-soft` cmake -DCMAKE_FIND_FRAMEWORK=NEVER ..
 160
 161 and get
 162
 163     -- Found OpenAL: /usr/local/opt/openal-soft/lib/libopenal.dylib
 164
 165 To build the library and each example you have the dependencies for,
 166 run `cmake --build . --parallel $(sysctl -n hw.ncpu)`.
 167 Use `sudo cmake --install .` to install Alure library on your system.
 168
 169 [Core Audio]: https://developer.apple.com/library/archive/documentation/MusicAudio/Conceptual/CoreAudioOverview/WhatsinCoreAudio/WhatsinCoreAudio.html