Basic spatial audio (#6028)

# Objective

- Add basic spatial audio support to Bevy
  - this is what rodio supports, so no HRTF, just simple stereo channel manipulation
  - no "built-in" ECS support: `Emitter` and `Listener` should be components that would automatically update the positions

This PR goal is to just expose rodio functionality, made possible with the recent update to rodio 0.16. A proper ECS integration opens a lot more questions, and would probably require an RFC

Also updates rodio and fixes #6122

Author: mockersf

Cargo.toml

@@ -830,6 +830,26 @@ description = "Shows how to create and register a custom audio source by impleme
 category = "Audio"
 wasm = true
 
+[[example]]
+name = "spatial_audio_2d"
+path = "examples/audio/spatial_audio_2d.rs"
+
+[package.metadata.example.spatial_audio_2d]
+name = "Spatial Audio 2D"
+description = "Shows how to play spatial audio, and moving the emitter in 2D"
+category = "Audio"
+wasm = true
+
+[[example]]
+name = "spatial_audio_3d"
+path = "examples/audio/spatial_audio_3d.rs"
+
+[package.metadata.example.spatial_audio_3d]
+name = "Spatial Audio 3D"
+description = "Shows how to play spatial audio, and moving the emitter in 3D"
+category = "Audio"
+wasm = true
+
 # Diagnostics
 [[example]]
 name = "log_diagnostics"

crates/bevy_audio/Cargo.toml

@@ -13,19 +13,21 @@ keywords = ["bevy"]
 bevy_app = { path = "../bevy_app", version = "0.9.0" }
 bevy_asset = { path = "../bevy_asset", version = "0.9.0" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.9.0" }
+bevy_math = { path = "../bevy_math", version = "0.9.0" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.9.0", features = ["bevy"] }
+bevy_transform = { path = "../bevy_transform", version = "0.9.0" }
 bevy_utils = { path = "../bevy_utils", version = "0.9.0" }
 
 # other
 anyhow = "1.0.4"
-rodio = { version = "0.16", default-features = false }
+rodio = { version = "0.17", default-features = false }
 parking_lot = "0.12.1"
 
 [target.'cfg(target_os = "android")'.dependencies]
-oboe = { version = "0.4", optional = true }
+oboe = { version = "0.5", optional = true }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-rodio = { version = "0.16", default-features = false, features = ["wasm-bindgen"] }
+rodio = { version = "0.17", default-features = false, features = ["wasm-bindgen"] }
 
 
 [features]

crates/bevy_audio/src/audio.rs

@@ -1,6 +1,8 @@
-use crate::{AudioSink, AudioSource, Decodable};
+use crate::{AudioSink, AudioSource, Decodable, SpatialAudioSink};
 use bevy_asset::{Asset, Handle, HandleId};
 use bevy_ecs::system::Resource;
+use bevy_math::Vec3;
+use bevy_transform::prelude::Transform;
 use parking_lot::RwLock;
 use std::{collections::VecDeque, fmt};
 
@@ -60,7 +62,7 @@ where
     ///
     /// Returns a weak [`Handle`] to the [`AudioSink`]. If this handle isn't changed to a
     /// strong one, the sink will be detached and the sound will continue playing. Changing it
-    /// to a strong handle allows for control on the playback through the [`AudioSink`] asset.
+    /// to a strong handle allows you to control the playback through the [`AudioSink`] asset.
     ///
     /// ```
     /// # use bevy_ecs::system::Res;
@@ -83,6 +85,7 @@ where
             settings: PlaybackSettings::ONCE,
             sink_handle: id,
             source_handle: audio_source,
+            spatial: None,
         };
         self.queue.write().push_back(config);
         Handle::<AudioSink>::weak(id)
@@ -115,14 +118,141 @@ where
             settings,
             sink_handle: id,
             source_handle: audio_source,
+            spatial: None,
         };
         self.queue.write().push_back(config);
         Handle::<AudioSink>::weak(id)
     }
+
+    /// Play audio from a [`Handle`] to the audio source, placing the listener at the given
+    /// transform, an ear on each side separated by `gap`. The audio emitter will placed at
+    /// `emitter`.
+    ///
+    /// `bevy_audio` is not using HRTF for spatial audio, but is transforming the sound to a mono
+    /// track, and then changing the level of each stereo channel according to the distance between
+    /// the emitter and each ear by amplifying the difference between what the two ears hear.
+    ///
+    /// ```
+    /// # use bevy_ecs::system::Res;
+    /// # use bevy_asset::AssetServer;
+    /// # use bevy_audio::Audio;
+    /// # use bevy_math::Vec3;
+    /// # use bevy_transform::prelude::Transform;
+    /// fn play_spatial_audio_system(asset_server: Res<AssetServer>, audio: Res<Audio>) {
+    ///     // Sound will be to the left and behind the listener
+    ///     audio.play_spatial(
+    ///         asset_server.load("my_sound.ogg"),
+    ///         Transform::IDENTITY,
+    ///         1.0,
+    ///         Vec3::new(-2.0, 0.0, 1.0),
+    ///     );
+    /// }
+    /// ```
+    ///
+    /// Returns a weak [`Handle`] to the [`SpatialAudioSink`]. If this handle isn't changed to a
+    /// strong one, the sink will be detached and the sound will continue playing. Changing it
+    /// to a strong handle allows you to control the playback, or move the listener and emitter
+    /// through the [`SpatialAudioSink`] asset.
+    ///
+    /// ```
+    /// # use bevy_ecs::system::Res;
+    /// # use bevy_asset::{AssetServer, Assets};
+    /// # use bevy_audio::{Audio, SpatialAudioSink};
+    /// # use bevy_math::Vec3;
+    /// # use bevy_transform::prelude::Transform;
+    /// fn play_spatial_audio_system(
+    ///     asset_server: Res<AssetServer>,
+    ///     audio: Res<Audio>,
+    ///     spatial_audio_sinks: Res<Assets<SpatialAudioSink>>,
+    /// ) {
+    ///     // This is a weak handle, and can't be used to control playback.
+    ///     let weak_handle = audio.play_spatial(
+    ///         asset_server.load("my_sound.ogg"),
+    ///         Transform::IDENTITY,
+    ///         1.0,
+    ///         Vec3::new(-2.0, 0.0, 1.0),
+    ///     );
+    ///     // This is now a strong handle, and can be used to control playback, or move the emitter.
+    ///     let strong_handle = spatial_audio_sinks.get_handle(weak_handle);
+    /// }
+    /// ```
+    pub fn play_spatial(
+        &self,
+        audio_source: Handle<Source>,
+        listener: Transform,
+        gap: f32,
+        emitter: Vec3,
+    ) -> Handle<SpatialAudioSink> {
+        let id = HandleId::random::<SpatialAudioSink>();
+        let config = AudioToPlay {
+            settings: PlaybackSettings::ONCE,
+            sink_handle: id,
+            source_handle: audio_source,
+            spatial: Some(SpatialSettings {
+                left_ear: (listener.translation + listener.left() * gap / 2.0).to_array(),
+                right_ear: (listener.translation + listener.right() * gap / 2.0).to_array(),
+                emitter: emitter.to_array(),
+            }),
+        };
+        self.queue.write().push_back(config);
+        Handle::<SpatialAudioSink>::weak(id)
+    }
+
+    /// Play spatial audio from a [`Handle`] to the audio source with [`PlaybackSettings`] that
+    /// allows looping or changing volume from the start. The listener is placed at the given
+    /// transform, an ear on each side separated by `gap`. The audio emitter is placed at
+    /// `emitter`.
+    ///
+    /// `bevy_audio` is not using HRTF for spatial audio, but is transforming the sound to a mono
+    /// track, and then changing the level of each stereo channel according to the distance between
+    /// the emitter and each ear by amplifying the difference between what the two ears hear.
+    ///
+    /// ```
+    /// # use bevy_ecs::system::Res;
+    /// # use bevy_asset::AssetServer;
+    /// # use bevy_audio::Audio;
+    /// # use bevy_audio::PlaybackSettings;
+    /// # use bevy_math::Vec3;
+    /// # use bevy_transform::prelude::Transform;
+    /// fn play_spatial_audio_system(asset_server: Res<AssetServer>, audio: Res<Audio>) {
+    ///     audio.play_spatial_with_settings(
+    ///         asset_server.load("my_sound.ogg"),
+    ///         PlaybackSettings::LOOP.with_volume(0.75),
+    ///         Transform::IDENTITY,
+    ///         1.0,
+    ///         Vec3::new(-2.0, 0.0, 1.0),
+    ///     );
+    /// }
+    /// ```
+    ///
+    /// See [`Self::play_spatial`] on how to control playback once it's started, or how to move
+    /// the listener or the emitter.
+    pub fn play_spatial_with_settings(
+        &self,
+        audio_source: Handle<Source>,
+        settings: PlaybackSettings,
+        listener: Transform,
+        gap: f32,
+        emitter: Vec3,
+    ) -> Handle<SpatialAudioSink> {
+        let id = HandleId::random::<SpatialAudioSink>();
+        let config = AudioToPlay {
+            settings,
+            sink_handle: id,
+            source_handle: audio_source,
+            spatial: Some(SpatialSettings {
+                left_ear: (listener.translation + listener.left() * gap / 2.0).to_array(),
+                right_ear: (listener.translation + listener.right() * gap / 2.0).to_array(),
+                emitter: emitter.to_array(),
+            }),
+        };
+        self.queue.write().push_back(config);
+        Handle::<SpatialAudioSink>::weak(id)
+    }
 }
 
 /// Settings to control playback from the start.
-#[derive(Clone, Debug)]
+#[derive(Clone, Copy, Debug)]
 pub struct PlaybackSettings {
     /// Play in repeat
     pub repeat: bool,
@@ -166,6 +296,13 @@ impl PlaybackSettings {
     }
 }
 
+#[derive(Clone)]
+pub(crate) struct SpatialSettings {
+    pub(crate) left_ear: [f32; 3],
+    pub(crate) right_ear: [f32; 3],
+    pub(crate) emitter: [f32; 3],
+}
+
 #[derive(Clone)]
 pub(crate) struct AudioToPlay<Source>
 where
@@ -174,6 +311,7 @@ where
     pub(crate) sink_handle: HandleId,
     pub(crate) source_handle: Handle<Source>,
     pub(crate) settings: PlaybackSettings,
+    pub(crate) spatial: Option<SpatialSettings>,
 }
 
 impl<Source> fmt::Debug for AudioToPlay<Source>