README.md

   1 OpenAL Soft
   2 ===========
   3
   4 `master` branch CI status : [![GitHub Actions Status](https://github.com/kcat/openal-soft/actions/workflows/ci.yml/badge.svg)](https://github.com/kcat/openal-soft/actions) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/kcat/openal-soft?branch=master&svg=true)](https://ci.appveyor.com/api/projects/status/github/kcat/openal-soft?branch=master&svg=true)
   5
   6 OpenAL Soft is an LGPL-licensed, cross-platform, software implementation of the OpenAL 3D audio API. It's forked from the open-sourced Windows version available originally from openal.org's SVN repository (now defunct).
   7 OpenAL provides capabilities for playing audio in a virtual 3D environment. Distance attenuation, doppler shift, and directional sound emitters are among the features handled by the API. More advanced effects, including air absorption, occlusion, and environmental reverb, are available through the EFX extension. It also facilitates streaming audio, multi-channel buffers, and audio capture.
   8
   9 More information is available on the [official website](http://openal-soft.org/).
  10
  11 Source Install
  12 -------------
  13 To install OpenAL Soft, use your favorite shell to go into the build/
  14 directory, and run:
  15
  16 ```bash
  17 cmake ..
  18 ```
  19
  20 Alternatively, you can use any available CMake front-end, like cmake-gui,
  21 ccmake, or your preferred IDE's CMake project parser.
  22
  23 Assuming configuration went well, you can then build it. The command
  24 `cmake --build .` will instruct CMake to build the project with the toolchain
  25 chosen during configuration (often GNU Make or NMake, although others are
  26 possible).
  27
  28 Please Note: Double check that the appropriate backends were detected. Often,
  29 complaints of no sound, crashing, and missing devices can be solved by making
  30 sure the correct backends are being used. CMake's output will identify which
  31 backends were enabled.
  32
  33 For most systems, you will likely want to make sure PipeWire, PulseAudio, and
  34 ALSA were detected (if your target system uses them). For Windows, make sure
  35 WASAPI was detected.
  36
  37
  38 Building openal-soft - Using vcpkg
  39 ----------------------------------
  40
  41 You can download and install openal-soft using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
  42
  43     git clone https://github.com/Microsoft/vcpkg.git
  44     cd vcpkg
  45     ./bootstrap-vcpkg.sh
  46     ./vcpkg integrate install
  47     ./vcpkg install openal-soft
  48
  49 The openal-soft port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
  50
  51 Utilities
  52 ---------
  53 The source package comes with an informational utility, openal-info, and is
  54 built by default. It prints out information provided by the ALC and AL sub-
  55 systems, including discovered devices, version information, and extensions.
  56
  57
  58 Configuration
  59 -------------
  60
  61 OpenAL Soft can be configured on a per-user and per-system basis. This allows
  62 users and sysadmins to control information provided to applications, as well
  63 as application-agnostic behavior of the library. See alsoftrc.sample for
  64 available settings.
  65
  66
  67 Language Bindings
  68 -----------------
  69
  70 As a C API, OpenAL Soft can be used directly by any language that can use
  71 functions with C linkage. For languages that can't directly use C-style
  72 headers, bindings may be developed to allow code written in that language to
  73 call into the library. Some bindings for some languages are listed here.
  74
  75 C# Bindings:
  76 * [OpenTK](https://opentk.net/) includes low-level C# bindings for the OpenAL
  77 API, including some extensions. It also includes utility libraries for math and
  78 linear algebra, which can be useful for 3D calculations.
  79
  80 Java Bindings:
  81 * [JOAL](https://jogamp.org/joal/www/), part of the JogAmp project, includes
  82 Java bindings for the OpenAL API, usable with OpenAL Soft. It also includes a
  83 higher level Sound3D Toolkit API and utility functions to make easier use of
  84 OpenAL features and capabilities.
  85
  86 Python Bindings:
  87 * [PyOpenAL](https://pypi.org/project/PyOpenAL/). Also includes methods to play
  88 wave files and, with PyOgg, also Vorbis, Opus, and FLAC.
  89
  90 Other bindings for these and other languages also exist. This list will grow as
  91 more bindings are found.
  92
  93
  94 Acknowledgements
  95 ----------------
  96
  97 Special thanks go to:
  98
  99  - Creative Labs for the original source code this is based off of.
 100  - Christopher Fitzgerald for the current reverb effect implementation, and
 101 helping with the low-pass and HRTF filters.
 102  - Christian Borss for the 3D panning code previous versions used as a base.
 103  - Ben Davis for the idea behind a previous version of the click-removal code.
 104  - Richard Furse for helping with my understanding of Ambisonics that is used by
 105 the various parts of the library.