1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
//! A Rust wrapper around [Steam Audio](https://valvesoftware.github.io/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`](https://github.com/MaxenceMaire/audionimbus/tree/master/audionimbus-sys), which provides raw bindings to the Steam Audio C API.
//!
//! To experience AudioNimbus in action, play the [interactive demo](https://github.com/MaxenceMaire/audionimbus-demo) or watch the [walkthrough video](https://www.youtube.com/watch?v=zlhW1maG0Is).
//!
//! `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:
//!
//! ```toml
//! [dependencies]
//! audionimbus = { version = "0.13.0", features = ["auto-install"] }
//! ```
//!
//! #### With FMOD Studio Integration
//!
//! ```toml
//! [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
//!
//! ```toml
//! [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:
//!
//! 1. Automatically detects your target platform and architecture
//! 2. Downloads the appropriate Steam Audio release zip file (cached to avoid re-downloading)
//! 3. Extracts only the required shared libraries for your platform
//! 4. 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](https://github.com/ValveSoftware/steam-audio/releases).
//!
//! 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](https://doc.rust-lang.org/cargo/reference/environment-variables.html#dynamic-library-paths) (e.g., `/usr/local/lib`).
//!
//! Finally, add `audionimbus` to your `Cargo.toml`:
//!
//! ```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:
//!
//! 1. Download `steamaudio_fmod_4.8.1.zip` from the [release page](https://github.com/ValveSoftware/steam-audio/releases).
//!
//! 2. 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` |
//!
//! 3. Ensure the libraries are placed in a location listed in the [dynamic library search paths](https://doc.rust-lang.org/cargo/reference/environment-variables.html#dynamic-library-paths) (e.g., `/usr/local/lib`).
//!
//! 4. Finally, add `audionimbus` with the `fmod` feature enabled to your `Cargo.toml`:
//!
//! ```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:
//!
//! 1. Download `steamaudio_wwise_4.8.1.zip` from the [release page](https://github.com/ValveSoftware/steam-audio/releases).
//!
//! 2. Locate the two relevant libraries for your target platform and place them in a location listed in [dynamic library search paths](https://doc.rust-lang.org/cargo/reference/environment-variables.html#dynamic-library-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`:
//!
//! ```toml
//! [dependencies]
//! audionimbus = { version = "0.13.0", features = ["wwise"] }
//! ```
//!
//! ## Example
//!
//! This example demonstrates how to spatialize sound using the `audionimbus` library:
//!
//! ```rust
//! 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.
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! To implement real-time audio processing and playback in your game, check out the [demo crate](https://github.com/MaxenceMaire/audionimbus/tree/master/audionimbus/demo) for a basic example.
//!
//! For a complete demonstration featuring HRTF, Ambisonics, reflections and reverb in an interactive environment, see the [AudioNimbus Interactive Demo repository](https://github.com/MaxenceMaire/audionimbus-demo).
//!
//! For additional examples, you can explore the [tests](https://github.com/MaxenceMaire/audionimbus/tree/master/audionimbus/tests).
//!
//! ## Documentation
//!
//! Documentation is available at [docs.rs](https://docs.rs/audionimbus/latest).
//!
//! For more details on Steam Audio's concepts, see the [Steam Audio SDK documentation](https://valvesoftware.github.io/steam-audio/doc/capi/index.html).
//!
//! 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](https://github.com/MaxenceMaire/audionimbus/blob/master/LICENSE-MIT) and the [Apache-2.0 License](https://github.com/MaxenceMaire/audionimbus/blob/master/LICENSE-APACHE).
//! You may choose either license when using the software.
const NUM_BANDS: u32 = 3;
pub use *;
pub use SteamAudioError;
pub use SerializedObject;
use Sealed;