Ahwoo.BRUTAL.OpenAl 2026.10.2

Brutal OpenAl

Modern C# bindings for OpenAL Soft, the cross-platform software implementation of the OpenAL 3D audio API, for use with the BRUTAL framework.

• Platform Support
• Links
  • NuGet Packages
• For Users
  • Prerequisites
  • Installation
  • Quick Start
  • Extension Coverage
• For Developers
  • Prerequisites
  • Layout
  • Compilation and Testing
  • License and Third-Party Notices
  • Contributing

Brutal.OpenAl opens a device, creates a context, uploads PCM audio to a buffer, attaches it to a source, and plays it. Generated [LibraryImport] P/Invoke over al.h/alc.h/efx.h (constants, enums, raw entry points, capture, effects) plus a hand-written facade (Al, Alc, Efx) so callers never touch raw handles, uint object names, or return codes. Device/context lifetime operations throw on failure; most other errors latch for the caller to poll explicitly (see Errors). Ships native openal-soft binaries for the platforms below inside the NuGet package.

Platform Support

Brutal.OpenAl vendors openal-soft as a git submodule; the native shared library is built from source for each platform via CMake, not downloaded as a prebuilt binary.

Links

• GitHub
• API Reference - the OpenAL 1.1 specification and the EFX extension guide
• OpenAL Soft - the implementation this package binds and ships
• BRUTAL Docs

NuGet Packages

• Ahwoo.BRUTAL.OpenAl - C# bindings for OpenAL Soft

For Users

Prerequisites

• .NET SDK (version 10.0 or later)

Installation

To install the package via NuGet, run the following command in your project directory:

dotnet add package Ahwoo.BRUTAL.OpenAl

Quick Start

Open the default device, create and activate a context, upload PCM data, and play it:

using Brutal.OpenAlApi;

using var device = Alc.OpenDevice();    // null/omitted name -> the default device
using var context = device.CreateContext();
context.MakeCurrent();

var buffer = Al.GenBuffer();
buffer.SetData(AlFormat.Mono16, pcmBytes, sampleRate: 44100);

var source = Al.GenSource();
source.Buffer = buffer;
source.Play();

Context.MakeCurrent(null);

Run a sample:

just sample playback

Please refer to src/Brutal.OpenAl/README.md for the index of topic-by-topic guides (QuickStart, Devices, Playback, Efx, CaptureDevice, Callbacks, Extensions, and Errors), and the BRUTAL Documentation for the full API reference. Every code sample in those guides is compiled and run as a test in test/Brutal.OpenAl via RocketWerkz.Brutal.DocTest, so documented usage is guaranteed to build against the current API.

Extension Coverage

Core OpenAL 1.1 (al.h) and ALC 1.1 (alc.h) are bound in full, including capture and device enumeration. The EFX extension (efx.h) is bound with typed wrappers for every effect and filter type, plus the generated reverb presets from efx-presets.h. The full stable OpenAL-Soft extension surface (alext.h) is bound as well, as first-class members of the same types rather than a separate opt-in surface - headline extensions include loopback rendering, device clock/latency and HRTF control, source latency and scheduled playback, callback buffers, async events, and KHR-style debug (message log/callback, groups, object labels). The raw IsExtensionPresent / GetProcAddress escape hatch is retained for anything not bound. AL_EXT_direct_context, EAX, and vendor SOFTX extensions are deliberately excluded. See Extensions for the guide.

For Developers

Prerequisites

• .NET SDK (version 10.0 or later)
• Just
• CMake
• Ninja
• A C++ compiler:
  • Windows: Visual Studio 2022 (x64)
  • Linux: GCC (x64)
  • Mac: Xcode and Xcode Command Line Tools (Apple Silicon)
• The vendored openal-soft source is a git submodule; clone with --recurse-submodules or run git submodule update --init submodules/openal-soft after cloning.

Layout

• src/Brutal.OpenAl/ - main library; generated bindings plus the hand-written facade.
• src/Brutal.OpenAl.Generate/ - binding generator (CLI), parses al.h/alc.h/efx.h/efx-presets.h.
• src/Brutal.OpenAl.Native/ - native CMake project; wraps the upstream openal-soft submodule.
• samples/ - runnable examples.
• test/ - xUnit tests, including the DocTest-compiled documentation samples.
• docs/ - docfx site source.

Compilation and Testing

To build the solution locally, run the following command in the repository root:

just build

To run the tests, run the following command in the repository root:

just test

just test covers the runtime suite only. The generator's own tests (test/Brutal.OpenAl.Generate.Test) are opt-in via just test-gen: run them whenever you change src/Brutal.OpenAl.Generate or bump the openal-soft submodule. They parse the OpenAL headers with libclang, which currently only works on macOS (Brutal.Ast resolves clang's builtin headers via xcrun); on Windows and Linux they fail to parse however they are invoked - IDE test runners such as Rider included, since those discover the tests regardless of the opt-in switch.

The remaining recipes:

just test-gen       # run the generator's tests (opt-in, macOS only; see above)
just pack           # dotnet pack
just sample <name>  # run one sample (playback, devices, efx, reverb, comparison, loopback, ocarina);
                    # omit the name to run them all
just generate       # regenerate the bindings from the upstream headers
just docfx serve    # build and serve the docs site locally

Native binaries are built via CMake on demand. RocketWerkz.Brutal.Interop.NativeBuild installs OpenAL Soft into the package's RID-specific native directory.

License and Third-Party Notices

Brutal.OpenAl links dynamically, at runtime, against an unmodified build of OpenAL Soft, which is distributed under the GNU Library General Public License, Version 2, June 1991 (the "Library GPL", predecessor of LGPL 2.1 - not LGPL 2.1 itself). The shipped binary is built from the public, pinned upstream commit unmodified.

This README packs into the NuGet package, so both pointers below are given for both readers. The full license text and the notices for every third-party component in the shipped library are in LICENSES/, at the root of the package and at src/Brutal.OpenAl/LICENSES/ in this repository. The submodule pin, the build configuration and the derivation of the component list are in THIRD-PARTY.md, which is not packed.

Contributing

If you find a bug or have a feature request, please open an issue on GitHub. If you'd like to contribute code, feel free to fork the repository and submit a pull request.