Crate audionimbus

Expand description

A Rust wrapper around Steam Audio that provides spatial audio capabilities with realistic occlusion, reverb, and HRTF effects, accounting for physical attributes and scene geometry.

§Overview

audionimbus simplifies the integration of Steam Audio into Rust projects by offering a safe, idiomiatic API.

It builds upon audionimbus-sys, which provides raw bindings to the Steam Audio C API.

To experience AudioNimbus in action, play the interactive demo or watch the walkthrough video.

audionimbus can also integrate with FMOD and Wwise.

§Version compatibility

audionimbus currently tracks Steam Audio 4.8.1.

Unlike audionimbus-sys, which mirrors Steam Audio’s versioning, audionimbus introduces its own abstractions and is subject to breaking changes. As a result, it uses independent versioning.

§Installation

§Automatic Installation (Recommended)

The easiest way to use audionimbus is with automatic installation. This will automatically download and set up the required Steam Audio libraries for your target platform.

§Requirements

curl or wget (for downloading)
Clang 9.0 or later

§Basic Usage

Add audionimbus to your Cargo.toml with the auto-install feature:

[dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install"] }

§With FMOD Studio Integration

[dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install", "fmod"] }

You also need to set the FMODSDK environment variable to the path of the FMOD SDK installed on your system (e.g. export FMOD="/path/to/FMOD").

§With Wwise Integration

[dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install", "wwise"] }

You also need to set the WWISESDK environment variable to the path of the Wwise SDK installed on your system (e.g. export WWISESDK="/path/to/Audiokinetic/Wwise2024.1.3.8749/SDK").

§How It Works

When you build your project with the auto-install feature, the build script:

Automatically detects your target platform and architecture
Downloads the appropriate Steam Audio release zip file (cached to avoid re-downloading)
Extracts only the required shared libraries for your platform
Sets up the library search paths automatically

The downloaded files are cached in $OUT_DIR/steam_audio_cache and won’t be re-downloaded unless the version changes. If you need to force a re-download, you can delete this directory.

Note The initial download can be quite large (≈180 MB for Steam Audio, ≈140 MB for the FMOD integration ≈52MB for the Wwise integration). During this step, cargo build may look like it is stuck - it’s just downloading in the background. The files are cached, so this only happens the first time (or when the version changes).

§Manual Installation

If you prefer manual installation or the automatic installation doesn’t work for your setup, you can still install Steam Audio manually.

§Requirements

Before installation, make sure that Clang 9.0 or later is installed on your system.

§Steps

audionimbus requires linking against the Steam Audio library during compilation.

To do so, download steamaudio_4.8.1.zip from the release page.

Locate the relevant library for your target platform (SDKROOT refers to the directory in which you extracted the zip file):

Platform	Library Directory	Library To Link
Windows 32-bit	`SDKROOT/lib/windows-x86`	`phonon.dll`
Windows 64-bit	`SDKROOT/lib/windows-x64`	`phonon.dll`
Linux 32-bit	`SDKROOT/lib/linux-x86`	`libphonon.so`
Linux 64-bit	`SDKROOT/lib/linux-x64`	`libphonon.so`
macOS	`SDKROOT/lib/osx`	`libphonon.dylib`
Android ARMv7	`SDKROOT/lib/android-armv7`	`libphonon.so`
Android ARMv8/AArch64	`SDKROOT/lib/android-armv8`	`libphonon.so`
Android x86	`SDKROOT/lib/android-x86`	`libphonon.so`
Android x64	`SDKROOT/lib/android-x64`	`libphonon.so`
iOS ARMv8/AArch64	`SDKROOT/lib/ios`	`libphonon.a`

Ensure the library is placed in a location listed in the dynamic library search paths (e.g., /usr/local/lib).

Finally, add audionimbus to your Cargo.toml:

[dependencies]
audionimbus = "0.13.0"

§Manual FMOD Studio Integration

audionimbus can be used to add spatial audio to an FMOD Studio project.

It requires linking against both the Steam Audio library and the FMOD integration library during compilation:

Download steamaudio_fmod_4.8.1.zip from the release page.
Locate the two relevant libraries for your target platform (SDKROOT refers to the directory in which you extracted the zip file):

Platform	Library Directory	Library To Link
Windows 32-bit	`SDKROOT/lib/windows-x86`	`phonon.dll`, `phonon_fmod.dll`
Windows 64-bit	`SDKROOT/lib/windows-x64`	`phonon.dll`, `phonon_fmod.dll`
Linux 32-bit	`SDKROOT/lib/linux-x86`	`libphonon.so`, `libphonon_fmod.so`
Linux 64-bit	`SDKROOT/lib/linux-x64`	`libphonon.so`, `libphonon_fmod.so`
macOS	`SDKROOT/lib/osx`	`libphonon.dylib`, `libphonon_fmod.dylib`
Android ARMv7	`SDKROOT/lib/android-armv7`	`libphonon.so`, `libphonon_fmod.so`
Android ARMv8/AArch64	`SDKROOT/lib/android-armv8`	`libphonon.so`, `libphonon_fmod.so`
Android x86	`SDKROOT/lib/android-x86`	`libphonon.so`, `libphonon_fmod.so`
Android x64	`SDKROOT/lib/android-x64`	`libphonon.so`, `libphonon_fmod.so`
iOS ARMv8/AArch64	`SDKROOT/lib/ios`	`libphonon.a`, `libphonon_fmod.a`

Ensure the libraries are placed in a location listed in the dynamic library search paths (e.g., /usr/local/lib).
Finally, add audionimbus with the fmod feature enabled to your Cargo.toml:

[dependencies]
audionimbus = { version = "0.13.0", features = ["fmod"] }

§Manual Wwise Integration

audionimbus can be used to add spatial audio to a Wwise project.

It requires linking against both the Steam Audio library and the Wwise integration library during compilation:

Download steamaudio_wwise_4.8.1.zip from the release page.
Locate the two relevant libraries for your target platform and place them in a location listed in dynamic library search paths (e.g., /usr/local/lib).
Set the WWISESDK environment variable to the path of the Wwise SDK installed on your system (e.g. export WWISESDK="/path/to/Audiokinetic/Wwise2024.1.3.8749/SDK").
Finally, add audionimbus with the wwise feature enabled to your Cargo.toml:

[dependencies]
audionimbus = { version = "0.13.0", features = ["wwise"] }

§Example

This example demonstrates how to spatialize sound using the audionimbus library:

use audionimbus::*;

// Initialize the audio context.
let context = Context::default();

let audio_settings = AudioSettings {
    sampling_rate: 48000,
    frame_size: 1024,
};

// Set up HRTF for binaural rendering.
let hrtf = Hrtf::try_new(&context, &audio_settings, &HrtfSettings::default())?;

// Create a binaural effect.
let mut binaural_effect = BinauralEffect::try_new(
    &context,
    &audio_settings,
    &BinauralEffectSettings { hrtf: &hrtf },
)?;

// Generate an input frame (in this case, a single-channel sine wave).
let input: Vec<Sample> = (0..audio_settings.frame_size)
    .map(|i| {
        (i as f32 * 2.0 * std::f32::consts::PI * 440.0 / audio_settings.sampling_rate as f32)
            .sin()
    })
    .collect();
// Create an audio buffer over the input data.
let input_buffer = AudioBuffer::try_with_data(&input)?;

let num_channels: u32 = 2; // Stereo
// Allocate memory to store processed samples.
let mut output = vec![0.0; (audio_settings.frame_size * num_channels) as usize];
// Create another audio buffer over the output container.
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output,
    AudioBufferSettings::with_num_channels(num_channels),
)?;

// Apply a binaural audio effect.
let binaural_effect_params = BinauralEffectParams {
    direction: Direction::new(
        1.0, // Right
        0.0, // Up
        0.0, // Behind
    ),
    interpolation: HrtfInterpolation::Nearest,
    spatial_blend: 1.0,
    hrtf: &hrtf,
    peak_delays: None,
};
let _effect_state =
    binaural_effect.apply(&binaural_effect_params, &input_buffer, &output_buffer);

// `output` now contains the processed samples in a deinterleaved format (i.e., left channel
// samples followed by right channel samples).

// Note: most audio engines expect interleaved audio (alternating samples for each channel). If
// required, use the `AudioBuffer::interleave` method to convert the format.

To implement real-time audio processing and playback in your game, check out the demo crate for a basic example.

For a complete demonstration featuring HRTF, Ambisonics, reflections and reverb in an interactive environment, see the AudioNimbus Interactive Demo repository.

For additional examples, you can explore the tests.

§Documentation

Documentation is available at docs.rs.

For more details on Steam Audio’s concepts, see the Steam Audio SDK documentation.

Note that because the Wwise integration depends on files that are local to your system, documentation for the wwise module is not available on docs.rs. However, it can be generated locally using cargo doc --open --features wwise.

§License

audionimbus is dual-licensed under the MIT License and the Apache-2.0 License. You may choose either license when using the software.

Re-exports§

pub use prelude::*;

Modules§

audio_buffer: Types and utilities for working with audio buffers.
audio_settings: Global audio signal processing settings.
baking: Baking of compute-intensive processes (reflections, pathing).
callback: Callback definitions.
context: Global context management and configuration.
device: Audio simulation compute devices and backends.
effect: Audio effects for spatial audio processing.
energy_field: Types and utilities for working with energy fields.
geometry: 3D geometry and scene management for acoustic simulation.
hrtf: Head-Related Transfer Function (HRTF) for spatial audio rendering.
impulse_response: Impulse responses and related operations.
model: Acoustic models (air absorption, deviation, directivity, distance attenuation).
prelude: Convenient re-exports of commonly used types and traits.
probe: Sound probe generation and storage.
ray_tracing: Ray tracing implementations.
reconstructor: Reconstruction of impulse responses from simulation data.
simulation: Spatial audio simulation (direct simulation, reflections, pathing).
version: Steam Audio version information.

Macros§

allocate_callback: Creates a memory allocation callback.
free_callback: Creates a memory deallocation callback.
log_callback: Creates a log callback.

Structs§

SerializedObject: A serialized representation of an API object, like a Scene or ProbeBatch.

Enums§

SteamAudioError: A Steam Audio error.