AudioNimbus

AudioNimbus provides spatial audio capabilities for games and VR applications by simulating realistic sound propagation. Key features include:

• Sound propagation: Models distance attenuation and how sound interacts with physical obstacles of varying materials.
• Reflections & reverb: Simulates sound wave reflections off geometry to create realistic acoustics.
• Head-Related Transfer Function (HRTF): Simulates how the listener's head and ears shape incoming sound to convey direction and distance.
• Ambisonics & surround sound: Encodes spatial information across multiple channels to reproduce directional sound fields.

AudioNimbus is designed to integrate with audio engines like FMOD Studio and Wwise, as well as game engines like Bevy.

Spatial audio simulation in audionimbus is compute-intensive (reflections passes can take 50-500ms) and cannot run directly on the real-time audio thread without causing glitches.

To handle this, the library uses a decoupled architecture, often managed via the wiring module:

1. Game Loop: Publishes new source positions to simulation threads every frame.
2. Simulation Threads: Run asynchronously (one dedicated thread per simulation type) to calculate complex effects like reflections.
3. Audio Thread: Renders audio using the latest available simulation output. This thread never blocks, ensuring smooth playback even if simulation updates are delayed.

audionimbus-sys

audionimbus-sys provides raw, unsafe Rust bindings to the Steam Audio C library. It is intended for low-level access and is inherently unsafe because it interfaces directly with external C code. Most users should not use this crate directly.

audionimbus

audionimbus is a safe Rust wrapper built on top of audionimbus-sys. It is the recommended crate for general use as it provides a safe API for interacting with Steam Audio.

The bevy module provides ECS wrappers around AudioNimbus types.

Architecture

• Threading: It uses the wiring module to run simulations on dedicated threads, ensuring that the Bevy world can keep scene and source state up to date without blocking.
• Output Boundary: The integration provides simulation outputs. It does not automatically apply these outputs to audio buffers; the developer is responsible for applying the simulation results to their chosen playback backend.

Compatibility

AudioNimbus is split into two crates to separate high-level safety from low-level bindings:

• audionimbus: The primary crate for end-users. It provides a high-level, safe Rust wrapper around Steam Audio. This is the crate you should typically use for your application logic.
• audionimbus-sys: Contains raw, automatically generated bindings to the Steam Audio C API. This is intended for internal use by the audionimbus crate and is generally not meant for direct interaction by developers.

The integration relies on the audionimbus::bevy module to synchronize the spatial audio simulation state with the Bevy ECS world.

Key architectural characteristics:

• Asynchronous Simulation: The audio simulation runs on dedicated background threads, separate from the main Bevy application loop.
• Non-blocking Audio Graph: The audio backend (using Firewheel via bevy_seedling) consumes simulation outputs (direct sound, reflections, and reverb) without blocking the main simulation or the engine.
• Ownership: Bevy manages the scene and source transforms, while the simulation threads produce spatial audio data in the background.

To see a practical implementation of the audionimbus library, you can run the core-demo package. This demo simulates a sound source orbiting a listener in a reflective room using direct path spatialization, early reflections, and late reverb.

cargo run --release -p core-demo

When running the demo, you can navigate the spatial environment using the following freecam controls:

To use AudioNimbus in your Rust project, add the audionimbus crate to your Cargo.toml. It is highly recommended to enable the auto-install feature, which automatically handles the downloading and installation of the underlying Steam Audio dependencies.

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

To run the demonstration of audionimbus integrated with the Bevy engine, use the following cargo command. It is recommended to run in --release mode to ensure proper performance for audio processing and spatialization.

cargo run --release -p bevy-demo

To manually integrate FMOD or Wwise, you must link against both the Steam Audio library and the specific integration library provided in the respective Steam Audio zip files.

FMOD Manual Setup

1. Download steamaudio_fmod_4.8.1.zip.
2. Locate both phonon and phonon_fmod libraries for your platform (e.g., libphonon.so and libphonon_fmod.so on Linux).
3. Set FMODSDK to your FMOD SDK path.
4. Enable the fmod feature in Cargo.toml.

Wwise Manual Setup

1. Download steamaudio_wwise_4.8.1.zip.
2. Locate the Wwise integration libraries for your platform.
3. Set WWISESDK to your Wwise SDK path.
4. Enable the wwise feature in Cargo.toml.

# FMOD manual dependency
[dependencies]
audionimbus-sys = { version = "4.8.2-rc.3", features = ["fmod"] }

# Wwise manual dependency
[dependencies]
audionimbus-sys = { version = "4.8.2-rc.3", features = ["wwise"] }