audionimbus

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 studio.

Version compatibility

audionimbus currently tracks Steam Audio 4.6.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

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

audionimbus requires linking against the Steam Audio library during compilation.

To do so, download steamaudio_4.6.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):

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.6.4"

Example

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

use audionimbus::*;

// Initialize the audio context.
let context = Context::try_new(&ContextSettings::default()).unwrap();

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()).unwrap();

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

// Generate an input frame (in thise 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).unwrap();

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

// 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, which closely follow Steam Audio's Programmer's Guide.

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:

1. Download steamaudio_fmod_4.6.1.zip from the release page.

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

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

4. Finally, add audionimbus with the fmod feature enabled to your Cargo.toml:

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

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:

1. Download steamaudio_wwise_4.6.1.zip from the release page.

2. 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).

3. 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").

4. Finally, add audionimbus with the wwise feature enabled to your Cargo.toml:

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

Documentation

Documentation is available at doc.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.