From 619c8951a606e1cfcebdf2848048a30a4a84e0c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Mon, 19 Sep 2022 23:21:26 +0200
Subject: [PATCH 01/26] basic spatial audio support from rodio

---
 Cargo.toml                            |  10 ++
 crates/bevy_audio/Cargo.toml          |   2 +
 crates/bevy_audio/src/audio.rs        | 129 ++++++++++++++-
 crates/bevy_audio/src/audio_output.rs | 174 +++++++-------------
 crates/bevy_audio/src/lib.rs          |   7 +-
 crates/bevy_audio/src/sinks.rs        | 224 ++++++++++++++++++++++++++
 examples/README.md                    |   1 +
 examples/audio/audio_control.rs       |   2 +-
 examples/audio/spatial_audio.rs       |  95 +++++++++++
 9 files changed, 521 insertions(+), 123 deletions(-)
 create mode 100644 crates/bevy_audio/src/sinks.rs
 create mode 100644 examples/audio/spatial_audio.rs

diff --git a/Cargo.toml b/Cargo.toml
index b810a3fa4aa2c..c5c19e0a0b082 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -814,6 +814,16 @@ description = "Shows how to create and register a custom audio source by impleme
 category = "Audio"
 wasm = true
 
+[[example]]
+name = "spatial_audio"
+path = "examples/audio/spatial_audio.rs"
+
+[package.metadata.example.spatial_audio]
+name = "Spatial Audio"
+description = "Shows how to play spacial audio, and moving the emitter"
+category = "Audio"
+wasm = true
+
 # Diagnostics
 [[example]]
 name = "log_diagnostics"
diff --git a/crates/bevy_audio/Cargo.toml b/crates/bevy_audio/Cargo.toml
index 8ea7dee8d63b9..bea3041c61c87 100644
--- a/crates/bevy_audio/Cargo.toml
+++ b/crates/bevy_audio/Cargo.toml
@@ -13,7 +13,9 @@ 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
diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index d7ac8d615795b..34d3fc1452967 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/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};
 
@@ -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,10 +118,126 @@ 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.
+    ///
+    /// ```
+    /// # use bevy_ecs::system::Res;
+    /// # use bevy_asset::AssetServer;
+    /// # use bevy_audio::Audio;
+    /// 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 for control on 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};
+    /// 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"));
+    ///     // 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.
+    ///
+    /// ```
+    /// # use bevy_ecs::system::Res;
+    /// # use bevy_asset::AssetServer;
+    /// # use bevy_audio::Audio;
+    /// # use bevy_audio::PlaybackSettings;
+    /// 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.
@@ -166,6 +285,13 @@ impl PlaybackSettings {
     }
 }
 
+#[derive(Clone, Debug)]
+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 +300,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>
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 31ee5f503adc3..ab0facaf6916c 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -1,11 +1,12 @@
-use crate::{Audio, AudioSource, Decodable};
+use crate::{Audio, AudioSource, Decodable, SpatialAudioSink, SpatialSettings};
 use bevy_asset::{Asset, Assets};
 use bevy_ecs::system::{Res, ResMut, Resource};
-use bevy_reflect::TypeUuid;
 use bevy_utils::tracing::warn;
-use rodio::{OutputStream, OutputStreamHandle, Sink, Source};
+use rodio::{OutputStream, OutputStreamHandle, Sink, Source, SpatialSink};
 use std::marker::PhantomData;
 
+use crate::AudioSink;
+
 /// Used internally to play audio on the current "audio device"
 ///
 /// ## Note
@@ -65,11 +66,35 @@ where
         })
     }
 
+    fn play_spatial_source(
+        &self,
+        audio_source: &Source,
+        repeat: bool,
+        spatial: SpatialSettings,
+    ) -> Option<SpatialSink> {
+        self.stream_handle.as_ref().map(|stream_handle| {
+            let sink = SpatialSink::try_new(
+                stream_handle,
+                spatial.emitter,
+                spatial.left_ear,
+                spatial.right_ear,
+            )
+            .unwrap();
+            if repeat {
+                sink.append(audio_source.decoder().repeat_infinite());
+            } else {
+                sink.append(audio_source.decoder());
+            }
+            sink
+        })
+    }
+
     fn try_play_queued(
         &self,
         audio_sources: &Assets<Source>,
         audio: &mut Audio<Source>,
         sinks: &mut Assets<AudioSink>,
+        spatial_sinks: &mut Assets<SpatialAudioSink>,
     ) {
         let mut queue = audio.queue.write();
         let len = queue.len();
@@ -77,12 +102,25 @@ where
         while i < len {
             let config = queue.pop_front().unwrap();
             if let Some(audio_source) = audio_sources.get(&config.source_handle) {
-                if let Some(sink) = self.play_source(audio_source, config.settings.repeat) {
-                    sink.set_speed(config.settings.speed);
-                    sink.set_volume(config.settings.volume);
-
-                    // don't keep the strong handle. there is no way to return it to the user here as it is async
-                    let _ = sinks.set(config.sink_handle, AudioSink { sink: Some(sink) });
+                if let Some(spatial) = config.spatial {
+                    if let Some(sink) =
+                        self.play_spatial_source(audio_source, config.settings.repeat, spatial)
+                    {
+                        sink.set_speed(config.settings.speed);
+                        sink.set_volume(config.settings.volume);
+
+                        // don't keep the strong handle. there is no way to return it to the user here as it is async
+                        let _ = spatial_sinks
+                            .set(config.sink_handle, SpatialAudioSink { sink: Some(sink) });
+                    }
+                } else {
+                    if let Some(sink) = self.play_source(audio_source, config.settings.repeat) {
+                        sink.set_speed(config.settings.speed);
+                        sink.set_volume(config.settings.volume);
+
+                        // don't keep the strong handle. there is no way to return it to the user here as it is async
+                        let _ = sinks.set(config.sink_handle, AudioSink { sink: Some(sink) });
+                    }
                 }
             } else {
                 // audio source hasn't loaded yet. add it back to the queue
@@ -99,118 +137,14 @@ pub fn play_queued_audio_system<Source: Asset + Decodable>(
     audio_sources: Option<Res<Assets<Source>>>,
     mut audio: ResMut<Audio<Source>>,
     mut sinks: ResMut<Assets<AudioSink>>,
+    mut spatial_sinks: ResMut<Assets<SpatialAudioSink>>,
 ) {
     if let Some(audio_sources) = audio_sources {
-        audio_output.try_play_queued(&*audio_sources, &mut *audio, &mut sinks);
+        audio_output.try_play_queued(
+            &*audio_sources,
+            &mut *audio,
+            &mut sinks,
+            &mut *spatial_sinks,
+        );
     };
 }
-
-/// Asset controlling the playback of a sound
-///
-/// ```
-/// # use bevy_ecs::system::{Local, Res};
-/// # use bevy_asset::{Assets, Handle};
-/// # use bevy_audio::AudioSink;
-/// // Execution of this system should be controlled by a state or input,
-/// // otherwise it would just toggle between play and pause every frame.
-/// fn pause(
-///     audio_sinks: Res<Assets<AudioSink>>,
-///     music_controller: Local<Handle<AudioSink>>,
-/// ) {
-///     if let Some(sink) = audio_sinks.get(&*music_controller) {
-///         if sink.is_paused() {
-///             sink.play()
-///         } else {
-///             sink.pause()
-///         }
-///     }
-/// }
-/// ```
-///
-#[derive(TypeUuid)]
-#[uuid = "8BEE570C-57C2-4FC0-8CFB-983A22F7D981"]
-pub struct AudioSink {
-    // This field is an Option in order to allow us to have a safe drop that will detach the sink.
-    // It will never be None during its life
-    sink: Option<Sink>,
-}
-
-impl Drop for AudioSink {
-    fn drop(&mut self) {
-        self.sink.take().unwrap().detach();
-    }
-}
-
-impl AudioSink {
-    /// Gets the volume of the sound.
-    ///
-    /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
-    /// will multiply each sample by this value.
-    pub fn volume(&self) -> f32 {
-        self.sink.as_ref().unwrap().volume()
-    }
-
-    /// Changes the volume of the sound.
-    ///
-    /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
-    /// will multiply each sample by this value.
-    pub fn set_volume(&self, volume: f32) {
-        self.sink.as_ref().unwrap().set_volume(volume);
-    }
-
-    /// Gets the speed of the sound.
-    ///
-    /// The value `1.0` is the "normal" speed (unfiltered input). Any value other than `1.0`
-    /// will change the play speed of the sound.
-    pub fn speed(&self) -> f32 {
-        self.sink.as_ref().unwrap().speed()
-    }
-
-    /// Changes the speed of the sound.
-    ///
-    /// The value `1.0` is the "normal" speed (unfiltered input). Any value other than `1.0`
-    /// will change the play speed of the sound.
-    pub fn set_speed(&self, speed: f32) {
-        self.sink.as_ref().unwrap().set_speed(speed);
-    }
-
-    /// Resumes playback of a paused sink.
-    ///
-    /// No effect if not paused.
-    pub fn play(&self) {
-        self.sink.as_ref().unwrap().play();
-    }
-
-    /// Pauses playback of this sink.
-    ///
-    /// No effect if already paused.
-    /// A paused sink can be resumed with [`play`](Self::play).
-    pub fn pause(&self) {
-        self.sink.as_ref().unwrap().pause();
-    }
-
-    /// Toggles the playback of this sink.
-    ///
-    /// Will pause if playing, and will be resumed if paused.
-    pub fn toggle(&self) {
-        if self.is_paused() {
-            self.play();
-        } else {
-            self.pause();
-        }
-    }
-
-    /// Is this sink paused?
-    ///
-    /// Sinks can be paused and resumed using [`pause`](Self::pause), [`play`](Self::play), and [`toggle`](Self::toggle).
-    pub fn is_paused(&self) -> bool {
-        self.sink.as_ref().unwrap().is_paused()
-    }
-
-    /// Stops the sink.
-    ///
-    /// It won't be possible to restart it afterwards.
-    pub fn stop(&self) {
-        self.sink.as_ref().unwrap().stop();
-    }
-}
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 14b410135df52..c196250aacf65 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -25,11 +25,14 @@
 mod audio;
 mod audio_output;
 mod audio_source;
+mod sinks;
 
 #[allow(missing_docs)]
 pub mod prelude {
     #[doc(hidden)]
-    pub use crate::{Audio, AudioOutput, AudioSource, Decodable, PlaybackSettings};
+    pub use crate::{
+        Audio, AudioOutput, AudioSink, AudioSinkExt, AudioSource, Decodable, PlaybackSettings,
+    };
 }
 
 pub use audio::*;
@@ -39,6 +42,7 @@ pub use audio_source::*;
 pub use rodio::cpal::Sample as CpalSample;
 pub use rodio::source::Source;
 pub use rodio::Sample;
+pub use sinks::*;
 
 use bevy_app::prelude::*;
 use bevy_asset::{AddAsset, Asset};
@@ -55,6 +59,7 @@ impl Plugin for AudioPlugin {
         app.init_resource::<AudioOutput<AudioSource>>()
             .add_asset::<AudioSource>()
             .add_asset::<AudioSink>()
+            .add_asset::<SpatialAudioSink>()
             .init_resource::<Audio<AudioSource>>()
             .add_system(play_queued_audio_system::<AudioSource>.in_base_set(CoreSet::PostUpdate));
 
diff --git a/crates/bevy_audio/src/sinks.rs b/crates/bevy_audio/src/sinks.rs
new file mode 100644
index 0000000000000..fe16eba79e31c
--- /dev/null
+++ b/crates/bevy_audio/src/sinks.rs
@@ -0,0 +1,224 @@
+use bevy_math::Vec3;
+use bevy_reflect::TypeUuid;
+use bevy_transform::prelude::Transform;
+use rodio::{Sink, SpatialSink};
+
+/// Common interactions with an audio sink.
+pub trait AudioSinkExt {
+    /// Gets the volume of the sound.
+    ///
+    /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
+    /// will multiply each sample by this value.
+    fn volume(&self) -> f32;
+
+    /// Changes the volume of the sound.
+    ///
+    /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
+    /// will multiply each sample by this value.
+    fn set_volume(&self, volume: f32);
+
+    /// Gets the speed of the sound.
+    ///
+    /// The value `1.0` is the "normal" speed (unfiltered input). Any value other than `1.0`
+    /// will change the play speed of the sound.
+    fn speed(&self) -> f32;
+
+    /// Changes the speed of the sound.
+    ///
+    /// The value `1.0` is the "normal" speed (unfiltered input). Any value other than `1.0`
+    /// will change the play speed of the sound.
+    fn set_speed(&self, speed: f32);
+
+    /// Resumes playback of a paused sink.
+    ///
+    /// No effect if not paused.
+    fn play(&self);
+
+    /// Pauses playback of this sink.
+    ///
+    /// No effect if already paused.
+    /// A paused sink can be resumed with [`play`](Self::play).
+    fn pause(&self);
+
+    /// Toggles the playback of this sink.
+    ///
+    /// Will pause if playing, and will be resumed if paused.
+    fn toggle(&self) {
+        if self.is_paused() {
+            self.play();
+        } else {
+            self.pause();
+        }
+    }
+
+    /// Is this sink paused?
+    ///
+    /// Sinks can be paused and resumed using [`pause`](Self::pause) and [`play`](Self::play).
+    fn is_paused(&self) -> bool;
+
+    /// Stops the sink.
+    ///
+    /// It won't be possible to restart it afterwards.
+    fn stop(&self);
+}
+
+/// Asset controlling the playback of a sound
+///
+/// ```
+/// # use bevy_ecs::system::{Local, Res};
+/// # use bevy_asset::{Assets, Handle};
+/// # use bevy_audio::AudioSink;
+/// // Execution of this system should be controlled by a state or input,
+/// // otherwise it would just toggle between play and pause every frame.
+/// fn pause(
+///     audio_sinks: Res<Assets<AudioSink>>,
+///     music_controller: Local<Handle<AudioSink>>,
+/// ) {
+///     if let Some(sink) = audio_sinks.get(&*music_controller) {
+///         if sink.is_paused() {
+///             sink.play()
+///         } else {
+///             sink.pause()
+///         }
+///     }
+/// }
+/// ```
+///
+#[derive(TypeUuid)]
+#[uuid = "8BEE570C-57C2-4FC0-8CFB-983A22F7D981"]
+pub struct AudioSink {
+    // This field is an Option in order to allow us to have a safe drop that will detach the sink.
+    // It will never be None during its life
+    pub(crate) sink: Option<Sink>,
+}
+
+impl Drop for AudioSink {
+    fn drop(&mut self) {
+        self.sink.take().unwrap().detach();
+    }
+}
+
+impl AudioSinkExt for AudioSink {
+    fn volume(&self) -> f32 {
+        self.sink.as_ref().unwrap().volume()
+    }
+
+    fn set_volume(&self, volume: f32) {
+        self.sink.as_ref().unwrap().set_volume(volume);
+    }
+
+    fn speed(&self) -> f32 {
+        self.sink.as_ref().unwrap().speed()
+    }
+
+    fn set_speed(&self, speed: f32) {
+        self.sink.as_ref().unwrap().set_speed(speed);
+    }
+
+    fn play(&self) {
+        self.sink.as_ref().unwrap().play();
+    }
+
+    fn pause(&self) {
+        self.sink.as_ref().unwrap().pause();
+    }
+
+    fn is_paused(&self) -> bool {
+        self.sink.as_ref().unwrap().is_paused()
+    }
+
+    fn stop(&self) {
+        self.sink.as_ref().unwrap().stop();
+    }
+}
+
+/// Asset controlling the playback of a sound, or the locations of its listener and emitter.
+///
+/// ```
+/// # use bevy_ecs::system::{Local, Res};
+/// # use bevy_asset::{Assets, Handle};
+/// # use bevy_audio::SpatialAudioSink;
+/// // Execution of this system should be controlled by a state or input,
+/// // otherwise it would just trigger every frame.
+/// fn pause(
+///     spatial_audio_sinks: Res<Assets<SpatialAudioSink>>,
+///     audio_controller: Local<Handle<SpatialAudioSink>>,
+/// ) {
+///     if let Some(spatial_sink) = spatial_audio_sinks.get(&*audio_controller) {
+///         spatial_sink.set_emitter_position(Vec3::new(1.0, 0.5, 1.0));
+///     }
+/// }
+/// ```
+///
+#[derive(TypeUuid)]
+#[uuid = "F3CA4C47-595E-453B-96A7-31C3DDF2A177"]
+pub struct SpatialAudioSink {
+    // This field is an Option in order to allow us to have a safe drop that will detach the sink.
+    // It will never be None during its life
+    pub(crate) sink: Option<SpatialSink>,
+}
+
+impl Drop for SpatialAudioSink {
+    fn drop(&mut self) {
+        self.sink.take().unwrap().detach();
+    }
+}
+
+impl AudioSinkExt for SpatialAudioSink {
+    fn volume(&self) -> f32 {
+        self.sink.as_ref().unwrap().volume()
+    }
+
+    fn set_volume(&self, volume: f32) {
+        self.sink.as_ref().unwrap().set_volume(volume);
+    }
+
+    fn speed(&self) -> f32 {
+        self.sink.as_ref().unwrap().speed()
+    }
+
+    fn set_speed(&self, speed: f32) {
+        self.sink.as_ref().unwrap().set_speed(speed);
+    }
+
+    fn play(&self) {
+        self.sink.as_ref().unwrap().play();
+    }
+
+    fn pause(&self) {
+        self.sink.as_ref().unwrap().pause();
+    }
+
+    fn is_paused(&self) -> bool {
+        self.sink.as_ref().unwrap().is_paused()
+    }
+
+    fn stop(&self) {
+        self.sink.as_ref().unwrap().stop();
+    }
+}
+
+impl SpatialAudioSink {
+    /// Set the two ears position.
+    pub fn set_ears_position(&self, left_position: Vec3, right_position: Vec3) {
+        let sink = self.sink.as_ref().unwrap();
+        sink.set_left_ear_position(left_position.to_array());
+        sink.set_right_ear_position(right_position.to_array());
+    }
+
+    /// Set the listener position, with an ear on each side separated by `gap`.
+    pub fn set_listener_position(&self, position: Transform, gap: f32) {
+        self.set_ears_position(
+            position.translation + position.left() * gap / 2.0,
+            position.translation + position.right() * gap / 2.0,
+        );
+    }
+
+    /// Set the emitter position.
+    pub fn set_emitter_position(&self, position: Vec3) {
+        self.sink
+            .as_ref()
+            .unwrap()
+            .set_emitter_position(position.to_array());
+    }
+}
diff --git a/examples/README.md b/examples/README.md
index cfa05e8b44756..525c2a3346ffb 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -182,6 +182,7 @@ Example | Description
 [Audio](../examples/audio/audio.rs) | Shows how to load and play an audio file
 [Audio Control](../examples/audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played
 [Decodable](../examples/audio/decodable.rs) | Shows how to create and register a custom audio source by implementing the `Decodable` type.
+[Spatial Audio](../examples/audio/spatial_audio.rs) | Shows how to play spacial audio, and moving the emitter
 
 ## Diagnostics
 
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index 85598082276a7..33c72147a073e 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -1,6 +1,6 @@
 //! This example illustrates how to load and play an audio file, and control how it's played.
 
-use bevy::{audio::AudioSink, prelude::*};
+use bevy::prelude::*;
 
 fn main() {
     App::new()
diff --git a/examples/audio/spatial_audio.rs b/examples/audio/spatial_audio.rs
new file mode 100644
index 0000000000000..1051cfb047e05
--- /dev/null
+++ b/examples/audio/spatial_audio.rs
@@ -0,0 +1,95 @@
+//! This example illustrates how to load and play an audio file, and control how it's played.
+
+use bevy::{audio::SpatialAudioSink, prelude::*};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_startup_system(setup)
+        .add_system(update_positions)
+        .run();
+}
+
+fn setup(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    audio: Res<Audio>,
+    audio_sinks: Res<Assets<SpatialAudioSink>>,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    let music = asset_server.load("sounds/Windless Slopes.ogg");
+    let handle = audio_sinks.get_handle(audio.play_spatial_with_settings(
+        music,
+        PlaybackSettings::LOOP,
+        Transform::IDENTITY,
+        4.0,
+        Vec3::ZERO,
+    ));
+    commands.insert_resource(AudioController(handle));
+
+    // left ear
+    commands.spawn(PbrBundle {
+        mesh: meshes.add(Mesh::from(shape::Cube { size: 0.2 })),
+        material: materials.add(Color::RED.into()),
+        transform: Transform::from_xyz(-2.0, 0.0, 0.0),
+        ..default()
+    });
+
+    // right ear
+    commands.spawn(PbrBundle {
+        mesh: meshes.add(Mesh::from(shape::Cube { size: 0.2 })),
+        material: materials.add(Color::GREEN.into()),
+        transform: Transform::from_xyz(2.0, 0.0, 0.0),
+        ..default()
+    });
+
+    // sound emitter
+    commands
+        .spawn(PbrBundle {
+            mesh: meshes.add(Mesh::from(shape::UVSphere {
+                radius: 0.2,
+                ..default()
+            })),
+            material: materials.add(Color::BLUE.into()),
+            transform: Transform::from_xyz(0.0, 0.0, 0.0),
+            ..default()
+        })
+        .insert(Emitter);
+
+    // light
+    commands.spawn(PointLightBundle {
+        point_light: PointLight {
+            intensity: 1500.0,
+            shadows_enabled: true,
+            ..default()
+        },
+        transform: Transform::from_xyz(4.0, 8.0, 4.0),
+        ..default()
+    });
+    // camera
+    commands.spawn(Camera3dBundle {
+        transform: Transform::from_xyz(0.0, 5.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
+        ..default()
+    });
+}
+
+#[derive(Component)]
+struct Emitter;
+
+#[derive(Resource)]
+struct AudioController(Handle<SpatialAudioSink>);
+
+fn update_positions(
+    audio_sinks: Res<Assets<SpatialAudioSink>>,
+    music_controller: Res<AudioController>,
+    time: Res<Time>,
+    mut emitter: Query<&mut Transform, With<Emitter>>,
+) {
+    if let Some(sink) = audio_sinks.get(&music_controller.0) {
+        let mut emitter_transform = emitter.single_mut();
+        emitter_transform.translation.x = (time.elapsed_seconds()).sin() as f32 * 3.0;
+        emitter_transform.translation.z = (time.elapsed_seconds()).cos() as f32 * 3.0;
+        sink.set_emitter_position(emitter_transform.translation);
+    }
+}

From 5deff32898b5fbd6e8745cf4f1192141b449db27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Mon, 19 Sep 2022 23:52:23 +0200
Subject: [PATCH 02/26] clippy

---
 crates/bevy_audio/src/audio.rs        |  4 ++--
 crates/bevy_audio/src/audio_output.rs | 12 +++++-------
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 34d3fc1452967..2358e8faed127 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -128,7 +128,7 @@ where
     /// 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
+    /// `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.
     ///
@@ -194,7 +194,7 @@ where
     /// 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
+    /// `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.
     ///
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index ab0facaf6916c..e645a294e180a 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -113,14 +113,12 @@ where
                         let _ = spatial_sinks
                             .set(config.sink_handle, SpatialAudioSink { sink: Some(sink) });
                     }
-                } else {
-                    if let Some(sink) = self.play_source(audio_source, config.settings.repeat) {
-                        sink.set_speed(config.settings.speed);
-                        sink.set_volume(config.settings.volume);
+                } else if let Some(sink) = self.play_source(audio_source, config.settings.repeat) {
+                    sink.set_speed(config.settings.speed);
+                    sink.set_volume(config.settings.volume);
 
-                        // don't keep the strong handle. there is no way to return it to the user here as it is async
-                        let _ = sinks.set(config.sink_handle, AudioSink { sink: Some(sink) });
-                    }
+                    // don't keep the strong handle. there is no way to return it to the user here as it is async
+                    let _ = sinks.set(config.sink_handle, AudioSink { sink: Some(sink) });
                 }
             } else {
                 // audio source hasn't loaded yet. add it back to the queue

From 7fec25014b64c52256189a38c16126998079c005 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 00:04:54 +0200
Subject: [PATCH 03/26] fix docs

---
 crates/bevy_audio/src/audio.rs | 13 ++++++++++++-
 crates/bevy_audio/src/sinks.rs |  3 ++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 2358e8faed127..4c5288d705306 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -136,6 +136,8 @@ where
     /// # 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(
@@ -156,13 +158,20 @@ where
     /// # 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"));
+    ///     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);
     /// }
@@ -203,6 +212,8 @@ where
     /// # 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"),
diff --git a/crates/bevy_audio/src/sinks.rs b/crates/bevy_audio/src/sinks.rs
index fe16eba79e31c..cf32163e55714 100644
--- a/crates/bevy_audio/src/sinks.rs
+++ b/crates/bevy_audio/src/sinks.rs
@@ -67,7 +67,7 @@ pub trait AudioSinkExt {
 /// ```
 /// # use bevy_ecs::system::{Local, Res};
 /// # use bevy_asset::{Assets, Handle};
-/// # use bevy_audio::AudioSink;
+/// # use bevy_audio::{AudioSink, AudioSinkExt};
 /// // Execution of this system should be controlled by a state or input,
 /// // otherwise it would just toggle between play and pause every frame.
 /// fn pause(
@@ -138,6 +138,7 @@ impl AudioSinkExt for AudioSink {
 /// # use bevy_ecs::system::{Local, Res};
 /// # use bevy_asset::{Assets, Handle};
 /// # use bevy_audio::SpatialAudioSink;
+/// # use bevy_math::Vec3;
 /// // Execution of this system should be controlled by a state or input,
 /// // otherwise it would just trigger every frame.
 /// fn pause(

From e1c10f15ac5c39fc0d79744d8b8ddaaddad6ba99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 00:12:27 +0200
Subject: [PATCH 04/26] update example doc

---
 crates/bevy_audio/src/lib.rs    | 1 +
 examples/audio/spatial_audio.rs | 5 ++---
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index c196250aacf65..ae38fd79346e4 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -32,6 +32,7 @@ pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
         Audio, AudioOutput, AudioSink, AudioSinkExt, AudioSource, Decodable, PlaybackSettings,
+        SpatialAudioSink,
     };
 }
 
diff --git a/examples/audio/spatial_audio.rs b/examples/audio/spatial_audio.rs
index 1051cfb047e05..4ed5879cf852d 100644
--- a/examples/audio/spatial_audio.rs
+++ b/examples/audio/spatial_audio.rs
@@ -1,6 +1,5 @@
-//! This example illustrates how to load and play an audio file, and control how it's played.
-
-use bevy::{audio::SpatialAudioSink, prelude::*};
+//! This example illustrates how to load and play an audio file, and control where the sounds seems to come from.
+use bevy::prelude::*;
 
 fn main() {
     App::new()

From b78ab0f4e050bf023b0365263031dba92a5a201b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 06:55:02 +0200
Subject: [PATCH 05/26] better explanation

Co-Authored-By: Griffin <33357138+DGriffin91@users.noreply.github.com>
---
 crates/bevy_audio/src/audio.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 4c5288d705306..309c9cafd2fc7 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -130,7 +130,7 @@ where
     ///
     /// `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.
+    /// the emitter and each ear by amplifying the difference between what the two ears hear.
     ///
     /// ```
     /// # use bevy_ecs::system::Res;
@@ -205,7 +205,7 @@ where
     ///
     /// `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.
+    /// the emitter and each ear by amplifying the difference between what the two ears hear.
     ///
     /// ```
     /// # use bevy_ecs::system::Res;

From 2428ed78f5082b595aa0c824a5305e26c970f595 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 22:56:00 +0200
Subject: [PATCH 06/26] adding 2d example

---
 Cargo.toml                                    | 20 +++-
 examples/README.md                            |  3 +-
 examples/audio/spatial_audio_2d.rs            | 94 +++++++++++++++++++
 .../{spatial_audio.rs => spatial_audio_3d.rs} |  8 +-
 4 files changed, 116 insertions(+), 9 deletions(-)
 create mode 100644 examples/audio/spatial_audio_2d.rs
 rename examples/audio/{spatial_audio.rs => spatial_audio_3d.rs} (94%)

diff --git a/Cargo.toml b/Cargo.toml
index c5c19e0a0b082..2c55c6a720436 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -815,12 +815,22 @@ category = "Audio"
 wasm = true
 
 [[example]]
-name = "spatial_audio"
-path = "examples/audio/spatial_audio.rs"
+name = "spatial_audio_2d"
+path = "examples/audio/spatial_audio_2d.rs"
 
-[package.metadata.example.spatial_audio]
-name = "Spatial Audio"
-description = "Shows how to play spacial audio, and moving the emitter"
+[package.metadata.example.spatial_audio_2d]
+name = "Spatial Audio 2D"
+description = "Shows how to play spacial 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 spacial audio, and moving the emitter in 3D"
 category = "Audio"
 wasm = true
 
diff --git a/examples/README.md b/examples/README.md
index 525c2a3346ffb..793a44e4aef3c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -182,7 +182,8 @@ Example | Description
 [Audio](../examples/audio/audio.rs) | Shows how to load and play an audio file
 [Audio Control](../examples/audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played
 [Decodable](../examples/audio/decodable.rs) | Shows how to create and register a custom audio source by implementing the `Decodable` type.
-[Spatial Audio](../examples/audio/spatial_audio.rs) | Shows how to play spacial audio, and moving the emitter
+[Spatial Audio 2D](../examples/audio/spatial_audio_2d.rs) | Shows how to play spacial audio, and moving the emitter in 2D
+[Spatial Audio 3D](../examples/audio/spatial_audio_3d.rs) | Shows how to play spacial audio, and moving the emitter in 3D
 
 ## Diagnostics
 
diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
new file mode 100644
index 0000000000000..ce902a2511917
--- /dev/null
+++ b/examples/audio/spatial_audio_2d.rs
@@ -0,0 +1,94 @@
+//! This example illustrates how to load and play an audio file, and control where the sounds seems to come from.
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_startup_system(setup)
+        .add_system(update_positions)
+        .run();
+}
+
+fn setup(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    audio: Res<Audio>,
+    audio_sinks: Res<Assets<SpatialAudioSink>>,
+) {
+    let gap = 4.0;
+
+    let music = asset_server.load("sounds/Windless Slopes.ogg");
+    let handle = audio_sinks.get_handle(audio.play_spatial_with_settings(
+        music,
+        PlaybackSettings::LOOP,
+        Transform::IDENTITY,
+        gap,
+        Vec3::ZERO,
+    ));
+    commands.insert_resource(AudioController(handle));
+
+    // Putting the visual presentation in a parent with a big scale as sound attenuation happens quite fast so distance are kept small
+    commands
+        .spawn(SpatialBundle {
+            transform: Transform::from_scale(Vec3::splat(100.0)),
+            ..default()
+        })
+        .with_children(|parent| {
+            // left ear
+            parent.spawn(SpriteBundle {
+                sprite: Sprite {
+                    color: Color::RED,
+                    custom_size: Some(Vec2::splat(0.2)),
+                    ..default()
+                },
+                transform: Transform::from_xyz(-gap / 2.0, 0.0, 0.0),
+                ..default()
+            });
+
+            // right ear
+            parent.spawn(SpriteBundle {
+                sprite: Sprite {
+                    color: Color::GREEN,
+                    custom_size: Some(Vec2::splat(0.2)),
+                    ..default()
+                },
+                transform: Transform::from_xyz(gap / 2.0, 0.0, 0.0),
+                ..default()
+            });
+
+            // sound emitter
+            parent
+                .spawn(SpriteBundle {
+                    sprite: Sprite {
+                        color: Color::BLUE,
+                        custom_size: Some(Vec2::new(0.3, 0.3)),
+                        ..default()
+                    },
+                    transform: Transform::from_xyz(0.0, 0.5, 0.0),
+                    ..default()
+                })
+                .insert(Emitter);
+        });
+
+    // camera
+    commands.spawn(Camera2dBundle::default());
+}
+
+#[derive(Component)]
+struct Emitter;
+
+#[derive(Resource)]
+struct AudioController(Handle<SpatialAudioSink>);
+
+fn update_positions(
+    audio_sinks: Res<Assets<SpatialAudioSink>>,
+    music_controller: Res<AudioController>,
+    time: Res<Time>,
+    mut emitter: Query<&mut Transform, With<Emitter>>,
+) {
+    if let Some(sink) = audio_sinks.get(&music_controller.0) {
+        let mut emitter_transform = emitter.single_mut();
+        emitter_transform.translation.x = (time.elapsed_seconds()).sin() as f32 * 5.0;
+        sink.set_emitter_position(emitter_transform.translation);
+    }
+}
diff --git a/examples/audio/spatial_audio.rs b/examples/audio/spatial_audio_3d.rs
similarity index 94%
rename from examples/audio/spatial_audio.rs
rename to examples/audio/spatial_audio_3d.rs
index 4ed5879cf852d..b939349942abb 100644
--- a/examples/audio/spatial_audio.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -17,12 +17,14 @@ fn setup(
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
+    let gap = 4.0;
+
     let music = asset_server.load("sounds/Windless Slopes.ogg");
     let handle = audio_sinks.get_handle(audio.play_spatial_with_settings(
         music,
         PlaybackSettings::LOOP,
         Transform::IDENTITY,
-        4.0,
+        gap,
         Vec3::ZERO,
     ));
     commands.insert_resource(AudioController(handle));
@@ -31,7 +33,7 @@ fn setup(
     commands.spawn(PbrBundle {
         mesh: meshes.add(Mesh::from(shape::Cube { size: 0.2 })),
         material: materials.add(Color::RED.into()),
-        transform: Transform::from_xyz(-2.0, 0.0, 0.0),
+        transform: Transform::from_xyz(-gap / 2.0, 0.0, 0.0),
         ..default()
     });
 
@@ -39,7 +41,7 @@ fn setup(
     commands.spawn(PbrBundle {
         mesh: meshes.add(Mesh::from(shape::Cube { size: 0.2 })),
         material: materials.add(Color::GREEN.into()),
-        transform: Transform::from_xyz(2.0, 0.0, 0.0),
+        transform: Transform::from_xyz(gap / 2.0, 0.0, 0.0),
         ..default()
     });
 

From 39f524cf0c87caf1640fa53186221094cd13cd8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 22:57:20 +0200
Subject: [PATCH 07/26] copy

---
 crates/bevy_audio/src/audio.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 309c9cafd2fc7..dffca5553bc52 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -252,7 +252,7 @@ where
 }
 
 /// Settings to control playback from the start.
-#[derive(Clone, Debug)]
+#[derive(Clone, Copy, Debug)]
 pub struct PlaybackSettings {
     /// Play in repeat
     pub repeat: bool,

From a6fef89913b88b6a5a3b2ffd7d7d2f4d56e53bac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Tue, 20 Sep 2022 22:59:41 +0200
Subject: [PATCH 08/26] no debug for that internal struct

---
 crates/bevy_audio/src/audio.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index dffca5553bc52..6c7982ccc9414 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -296,7 +296,7 @@ impl PlaybackSettings {
     }
 }
 
-#[derive(Clone, Debug)]
+#[derive(Clone)]
 pub(crate) struct SpatialSettings {
     pub(crate) left_ear: [f32; 3],
     pub(crate) right_ear: [f32; 3],

From dc6067f84c3118f28cdc2a5beed37c8bc8e5fd62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Wed, 21 Sep 2022 01:27:34 +0200
Subject: [PATCH 09/26] spacial -> spatial

Co-authored-by: harudagondi <giogdeasis@gmail.com>
---
 Cargo.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 2c55c6a720436..77052e413dbe6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -820,7 +820,7 @@ path = "examples/audio/spatial_audio_2d.rs"
 
 [package.metadata.example.spatial_audio_2d]
 name = "Spatial Audio 2D"
-description = "Shows how to play spacial audio, and moving the emitter in 2D"
+description = "Shows how to play spatial audio, and moving the emitter in 2D"
 category = "Audio"
 wasm = true
 
@@ -830,7 +830,7 @@ path = "examples/audio/spatial_audio_3d.rs"
 
 [package.metadata.example.spatial_audio_3d]
 name = "Spatial Audio 3D"
-description = "Shows how to play spacial audio, and moving the emitter in 3D"
+description = "Shows how to play spatial audio, and moving the emitter in 3D"
 category = "Audio"
 wasm = true
 

From a953c4d74c38fdfef538bc855dac13868782c194 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Wed, 21 Sep 2022 01:38:21 +0200
Subject: [PATCH 10/26] update example readme

---
 examples/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 793a44e4aef3c..62890a9efaeaf 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -182,8 +182,8 @@ Example | Description
 [Audio](../examples/audio/audio.rs) | Shows how to load and play an audio file
 [Audio Control](../examples/audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played
 [Decodable](../examples/audio/decodable.rs) | Shows how to create and register a custom audio source by implementing the `Decodable` type.
-[Spatial Audio 2D](../examples/audio/spatial_audio_2d.rs) | Shows how to play spacial audio, and moving the emitter in 2D
-[Spatial Audio 3D](../examples/audio/spatial_audio_3d.rs) | Shows how to play spacial audio, and moving the emitter in 3D
+[Spatial Audio 2D](../examples/audio/spatial_audio_2d.rs) | Shows how to play spatial audio, and moving the emitter in 2D
+[Spatial Audio 3D](../examples/audio/spatial_audio_3d.rs) | Shows how to play spatial audio, and moving the emitter in 3D
 
 ## Diagnostics
 

From 5d38b9f80a420e0fec2d677a7b423b8a1774c5c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 23 Sep 2022 00:53:53 +0200
Subject: [PATCH 11/26] mention issue when not compiling in release

---
 crates/bevy_audio/src/audio.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 6c7982ccc9414..e4c0878d9ae9e 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -132,6 +132,9 @@ where
     /// 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.
     ///
+    /// The two channels can be randomly reversed when compiling in debug. This is fixed by
+    /// compiling in release: <https://github.com/RustAudio/rodio/issues/444>.
+    ///
     /// ```
     /// # use bevy_ecs::system::Res;
     /// # use bevy_asset::AssetServer;
@@ -207,6 +210,9 @@ where
     /// 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.
     ///
+    /// The two channels can be randomly reversed when compiling in debug. This is fixed by
+    /// compiling in release: <https://github.com/RustAudio/rodio/issues/444>.
+    ///
     /// ```
     /// # use bevy_ecs::system::Res;
     /// # use bevy_asset::AssetServer;

From 8220e0852152f4ac9dd90a8fa71d47122d31ab6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Mon, 21 Nov 2022 21:01:48 +0100
Subject: [PATCH 12/26] fix it

---
 crates/bevy_audio/src/audio_output.rs | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index e645a294e180a..1fdb564961a5d 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -138,11 +138,6 @@ pub fn play_queued_audio_system<Source: Asset + Decodable>(
     mut spatial_sinks: ResMut<Assets<SpatialAudioSink>>,
 ) {
     if let Some(audio_sources) = audio_sources {
-        audio_output.try_play_queued(
-            &*audio_sources,
-            &mut *audio,
-            &mut sinks,
-            &mut *spatial_sinks,
-        );
+        audio_output.try_play_queued(&*audio_sources, &mut *audio, &mut sinks, &mut spatial_sinks);
     };
 }

From 8eb4e5bdcad64d32dcb5516116fcaad416a9a411 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Mon, 21 Nov 2022 20:51:44 +0100
Subject: [PATCH 13/26] use patched rodio

---
 Cargo.toml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index 77052e413dbe6..06f9920d85806 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1733,3 +1733,6 @@ codegen-units = 1
 inherits = "release"
 lto = "fat"
 panic = "abort"
+
+[patch.crates-io]
+rodio = { git = "https://github.com/dis-da-moe/rodio" }

From 42ebc13116e7f6bc037df172eb9cca353f4f67e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Mon, 21 Nov 2022 21:09:49 +0100
Subject: [PATCH 14/26] spawn bundles

---
 examples/audio/spatial_audio_2d.rs | 9 +++++----
 examples/audio/spatial_audio_3d.rs | 9 +++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index ce902a2511917..3d92234a19321 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -57,8 +57,8 @@ fn setup(
             });
 
             // sound emitter
-            parent
-                .spawn(SpriteBundle {
+            parent.spawn((
+                SpriteBundle {
                     sprite: Sprite {
                         color: Color::BLUE,
                         custom_size: Some(Vec2::new(0.3, 0.3)),
@@ -66,8 +66,9 @@ fn setup(
                     },
                     transform: Transform::from_xyz(0.0, 0.5, 0.0),
                     ..default()
-                })
-                .insert(Emitter);
+                },
+                Emitter,
+            ));
         });
 
     // camera
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
index b939349942abb..e68d211a2fe20 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -46,8 +46,8 @@ fn setup(
     });
 
     // sound emitter
-    commands
-        .spawn(PbrBundle {
+    commands.spawn((
+        PbrBundle {
             mesh: meshes.add(Mesh::from(shape::UVSphere {
                 radius: 0.2,
                 ..default()
@@ -55,8 +55,9 @@ fn setup(
             material: materials.add(Color::BLUE.into()),
             transform: Transform::from_xyz(0.0, 0.0, 0.0),
             ..default()
-        })
-        .insert(Emitter);
+        },
+        Emitter,
+    ));
 
     // light
     commands.spawn(PointLightBundle {

From 3b9809334ffc9c1f6163fd2e8247aac44ac6929e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Wed, 23 Nov 2022 09:08:48 +0100
Subject: [PATCH 15/26] pr is merged, use official rodio repo

---
 Cargo.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Cargo.toml b/Cargo.toml
index 06f9920d85806..cbe43e3a556a4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1735,4 +1735,4 @@ lto = "fat"
 panic = "abort"
 
 [patch.crates-io]
-rodio = { git = "https://github.com/dis-da-moe/rodio" }
+rodio = { git = "https://github.com/RustAudio/rodio" }

From 04163cd7f102ac33bf7d019829efd211a3e23b09 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 13:42:19 +0100
Subject: [PATCH 16/26] update for next version of rodio

---
 crates/bevy_audio/src/audio_output.rs | 5 ++++-
 crates/bevy_audio/src/audio_source.rs | 3 ++-
 crates/bevy_audio/src/lib.rs          | 1 +
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 1fdb564961a5d..832e6c3d98e34 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -53,6 +53,7 @@ where
 impl<Source> AudioOutput<Source>
 where
     Source: Asset + Decodable,
+    f32: rodio::cpal::FromSample<Source::DecoderItem>,
 {
     fn play_source(&self, audio_source: &Source, repeat: bool) -> Option<Sink> {
         self.stream_handle.as_ref().map(|stream_handle| {
@@ -136,7 +137,9 @@ pub fn play_queued_audio_system<Source: Asset + Decodable>(
     mut audio: ResMut<Audio<Source>>,
     mut sinks: ResMut<Assets<AudioSink>>,
     mut spatial_sinks: ResMut<Assets<SpatialAudioSink>>,
-) {
+) where
+    f32: rodio::cpal::FromSample<Source::DecoderItem>,
+{
     if let Some(audio_sources) = audio_sources {
         audio_output.try_play_queued(&*audio_sources, &mut *audio, &mut sinks, &mut spatial_sinks);
     };
diff --git a/crates/bevy_audio/src/audio_source.rs b/crates/bevy_audio/src/audio_source.rs
index dda555f13a4de..afbf445350526 100644
--- a/crates/bevy_audio/src/audio_source.rs
+++ b/crates/bevy_audio/src/audio_source.rs
@@ -104,5 +104,6 @@ pub trait AddAudioSource {
     /// the [audio][super::AudioPlugin] and [asset][bevy_asset::AssetPlugin] plugins must be added first.    
     fn add_audio_source<T>(&mut self) -> &mut Self
     where
-        T: Decodable + Asset;
+        T: Decodable + Asset,
+        f32: rodio::cpal::FromSample<T::DecoderItem>;
 }
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index ae38fd79346e4..32eddbd9853d1 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -73,6 +73,7 @@ impl AddAudioSource for App {
     fn add_audio_source<T>(&mut self) -> &mut Self
     where
         T: Decodable + Asset,
+        f32: rodio::cpal::FromSample<T::DecoderItem>,
     {
         self.add_asset::<T>()
             .init_resource::<Audio<T>>()

From 363a78d354549e8479807970bdd92bf3960cd477 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 13:42:28 +0100
Subject: [PATCH 17/26] circles are nice

---
 examples/audio/spatial_audio_2d.rs | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index 3d92234a19321..207288dd7ccee 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -1,5 +1,5 @@
 //! This example illustrates how to load and play an audio file, and control where the sounds seems to come from.
-use bevy::prelude::*;
+use bevy::{prelude::*, sprite::MaterialMesh2dBundle};
 
 fn main() {
     App::new()
@@ -11,6 +11,8 @@ fn main() {
 
 fn setup(
     mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<ColorMaterial>>,
     asset_server: Res<AssetServer>,
     audio: Res<Audio>,
     audio_sinks: Res<Assets<SpatialAudioSink>>,
@@ -58,13 +60,10 @@ fn setup(
 
             // sound emitter
             parent.spawn((
-                SpriteBundle {
-                    sprite: Sprite {
-                        color: Color::BLUE,
-                        custom_size: Some(Vec2::new(0.3, 0.3)),
-                        ..default()
-                    },
-                    transform: Transform::from_xyz(0.0, 0.5, 0.0),
+                MaterialMesh2dBundle {
+                    mesh: meshes.add(shape::Circle::new(0.15).into()).into(),
+                    material: materials.add(ColorMaterial::from(Color::BLUE)),
+                    transform: Transform::from_translation(Vec3::new(0.0, 0.5, 0.0)),
                     ..default()
                 },
                 Emitter,

From 2eeb62cc4944c5f4072c9ba79d4b2c4489819a44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 13:53:18 +0100
Subject: [PATCH 18/26] :paperclip:

---
 examples/audio/spatial_audio_2d.rs | 2 +-
 examples/audio/spatial_audio_3d.rs | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index 207288dd7ccee..f0b1676c3adf0 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -88,7 +88,7 @@ fn update_positions(
 ) {
     if let Some(sink) = audio_sinks.get(&music_controller.0) {
         let mut emitter_transform = emitter.single_mut();
-        emitter_transform.translation.x = (time.elapsed_seconds()).sin() as f32 * 5.0;
+        emitter_transform.translation.x = time.elapsed_seconds().sin() * 5.0;
         sink.set_emitter_position(emitter_transform.translation);
     }
 }
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
index e68d211a2fe20..91e973d776572 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -90,8 +90,8 @@ fn update_positions(
 ) {
     if let Some(sink) = audio_sinks.get(&music_controller.0) {
         let mut emitter_transform = emitter.single_mut();
-        emitter_transform.translation.x = (time.elapsed_seconds()).sin() as f32 * 3.0;
-        emitter_transform.translation.z = (time.elapsed_seconds()).cos() as f32 * 3.0;
+        emitter_transform.translation.x = time.elapsed_seconds().sin() * 3.0;
+        emitter_transform.translation.z = time.elapsed_seconds().cos() * 3.0;
         sink.set_emitter_position(emitter_transform.translation);
     }
 }

From ec19fb151ff41b03111b5f3480ed1f780f08fd95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 19:33:14 +0100
Subject: [PATCH 19/26] span in 2d

---
 examples/audio/spatial_audio_2d.rs | 78 ++++++++++++++----------------
 1 file changed, 37 insertions(+), 41 deletions(-)

diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index f0b1676c3adf0..67398a3493a26 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -9,6 +9,10 @@ fn main() {
         .run();
 }
 
+/// 1 pixel would be one unit of distance for audio and sound attenuation would happen very fast.
+/// Keeping an audio span scale allow this example to have visible movements and shape size while keeping attenuation reasonable.
+const AUDIO_SPAN: f32 = 100.0;
+
 fn setup(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
@@ -17,58 +21,50 @@ fn setup(
     audio: Res<Audio>,
     audio_sinks: Res<Assets<SpatialAudioSink>>,
 ) {
-    let gap = 4.0;
+    let gap = 400.0;
 
     let music = asset_server.load("sounds/Windless Slopes.ogg");
     let handle = audio_sinks.get_handle(audio.play_spatial_with_settings(
         music,
         PlaybackSettings::LOOP,
         Transform::IDENTITY,
-        gap,
+        gap / AUDIO_SPAN,
         Vec3::ZERO,
     ));
     commands.insert_resource(AudioController(handle));
 
-    // Putting the visual presentation in a parent with a big scale as sound attenuation happens quite fast so distance are kept small
-    commands
-        .spawn(SpatialBundle {
-            transform: Transform::from_scale(Vec3::splat(100.0)),
+    // left ear
+    commands.spawn(SpriteBundle {
+        sprite: Sprite {
+            color: Color::RED,
+            custom_size: Some(Vec2::splat(20.0)),
             ..default()
-        })
-        .with_children(|parent| {
-            // left ear
-            parent.spawn(SpriteBundle {
-                sprite: Sprite {
-                    color: Color::RED,
-                    custom_size: Some(Vec2::splat(0.2)),
-                    ..default()
-                },
-                transform: Transform::from_xyz(-gap / 2.0, 0.0, 0.0),
-                ..default()
-            });
+        },
+        transform: Transform::from_xyz(-gap / 2.0, 0.0, 0.0),
+        ..default()
+    });
 
-            // right ear
-            parent.spawn(SpriteBundle {
-                sprite: Sprite {
-                    color: Color::GREEN,
-                    custom_size: Some(Vec2::splat(0.2)),
-                    ..default()
-                },
-                transform: Transform::from_xyz(gap / 2.0, 0.0, 0.0),
-                ..default()
-            });
+    // right ear
+    commands.spawn(SpriteBundle {
+        sprite: Sprite {
+            color: Color::GREEN,
+            custom_size: Some(Vec2::splat(20.0)),
+            ..default()
+        },
+        transform: Transform::from_xyz(gap / 2.0, 0.0, 0.0),
+        ..default()
+    });
 
-            // sound emitter
-            parent.spawn((
-                MaterialMesh2dBundle {
-                    mesh: meshes.add(shape::Circle::new(0.15).into()).into(),
-                    material: materials.add(ColorMaterial::from(Color::BLUE)),
-                    transform: Transform::from_translation(Vec3::new(0.0, 0.5, 0.0)),
-                    ..default()
-                },
-                Emitter,
-            ));
-        });
+    // sound emitter
+    commands.spawn((
+        MaterialMesh2dBundle {
+            mesh: meshes.add(shape::Circle::new(15.0).into()).into(),
+            material: materials.add(ColorMaterial::from(Color::BLUE)),
+            transform: Transform::from_translation(Vec3::new(0.0, 50.0, 0.0)),
+            ..default()
+        },
+        Emitter,
+    ));
 
     // camera
     commands.spawn(Camera2dBundle::default());
@@ -88,7 +84,7 @@ fn update_positions(
 ) {
     if let Some(sink) = audio_sinks.get(&music_controller.0) {
         let mut emitter_transform = emitter.single_mut();
-        emitter_transform.translation.x = time.elapsed_seconds().sin() * 5.0;
-        sink.set_emitter_position(emitter_transform.translation);
+        emitter_transform.translation.x = time.elapsed_seconds().sin() * 500.0;
+        sink.set_emitter_position(emitter_transform.translation / AUDIO_SPAN);
     }
 }

From 998ea9d874d77cfe1cb83df38003fce41b15f97c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 19:41:07 +0100
Subject: [PATCH 20/26] rename AudioSinkExt trait

---
 crates/bevy_audio/src/lib.rs   | 2 +-
 crates/bevy_audio/src/sinks.rs | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 32eddbd9853d1..af751a8364c61 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -31,7 +31,7 @@ mod sinks;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        Audio, AudioOutput, AudioSink, AudioSinkExt, AudioSource, Decodable, PlaybackSettings,
+        Audio, AudioOutput, AudioSink, AudioSinkPlayback, AudioSource, Decodable, PlaybackSettings,
         SpatialAudioSink,
     };
 }
diff --git a/crates/bevy_audio/src/sinks.rs b/crates/bevy_audio/src/sinks.rs
index cf32163e55714..e5847a0fee79c 100644
--- a/crates/bevy_audio/src/sinks.rs
+++ b/crates/bevy_audio/src/sinks.rs
@@ -4,7 +4,7 @@ use bevy_transform::prelude::Transform;
 use rodio::{Sink, SpatialSink};
 
 /// Common interactions with an audio sink.
-pub trait AudioSinkExt {
+pub trait AudioSinkPlayback {
     /// Gets the volume of the sound.
     ///
     /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
@@ -67,7 +67,7 @@ pub trait AudioSinkExt {
 /// ```
 /// # use bevy_ecs::system::{Local, Res};
 /// # use bevy_asset::{Assets, Handle};
-/// # use bevy_audio::{AudioSink, AudioSinkExt};
+/// # use bevy_audio::{AudioSink, AudioSinkPlayback};
 /// // Execution of this system should be controlled by a state or input,
 /// // otherwise it would just toggle between play and pause every frame.
 /// fn pause(
@@ -98,7 +98,7 @@ impl Drop for AudioSink {
     }
 }
 
-impl AudioSinkExt for AudioSink {
+impl AudioSinkPlayback for AudioSink {
     fn volume(&self) -> f32 {
         self.sink.as_ref().unwrap().volume()
     }
@@ -165,7 +165,7 @@ impl Drop for SpatialAudioSink {
     }
 }
 
-impl AudioSinkExt for SpatialAudioSink {
+impl AudioSinkPlayback for SpatialAudioSink {
     fn volume(&self) -> f32 {
         self.sink.as_ref().unwrap().volume()
     }

From 98979178c8329ccf7312de0c966138aa0d30ded8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 19:54:07 +0100
Subject: [PATCH 21/26] update dependencies and checks

---
 crates/bevy_audio/Cargo.toml |  2 +-
 deny.toml                    | 15 +++------------
 2 files changed, 4 insertions(+), 13 deletions(-)

diff --git a/crates/bevy_audio/Cargo.toml b/crates/bevy_audio/Cargo.toml
index bea3041c61c87..ac1510493d3cc 100644
--- a/crates/bevy_audio/Cargo.toml
+++ b/crates/bevy_audio/Cargo.toml
@@ -24,7 +24,7 @@ rodio = { version = "0.16", 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"] }
diff --git a/deny.toml b/deny.toml
index 19537d1b115c4..9f3571838af47 100644
--- a/deny.toml
+++ b/deny.toml
@@ -6,7 +6,6 @@ unmaintained = "deny"
 yanked = "deny"
 notice = "deny"
 ignore = [
-    "RUSTSEC-2020-0056", # from cpal v0.14.1 - unmaintained - https://github.com/koute/stdweb/issues/403
     "RUSTSEC-2022-0048", # from xml-rs 0.8.4 - unmaintained - it's used in a build script of winit
 ]
 
@@ -35,20 +34,12 @@ wildcards = "deny"
 highlight = "all"
 # Certain crates/versions that will be skipped when doing duplicate detection.
 skip = [
-    { name = "ndk-sys", version = "0.3" },               # from rodio v0.16.0
-    { name = "ndk", version = "0.6" },                   # from rodio v0.16.0
-    { name = "nix", version = "0.23" },                  # from cpal v0.14.1
+    { name = "core-foundation-sys", version = "0.6" },   # from cpal v0.15.0
+    { name = "jni", version = "0.19" },                  # from cpal v0.15.0
+    { name = "nix", version = "0.24" },                  # from cpal v0.15.0
     { name = "redox_syscall", version = "0.2" },         # from notify v5.1.0
-    { name = "rustc_version", version = "0.2" },         # from postcard v1.0.2
-    { name = "semver", version = "0.9" },                # from postcard v1.0.2
     { name = "windows-sys", version = "0.42" },          # from notify v5.1.0
     { name = "windows", version = "0.43"},               # from gilrs v0.10.1
-    { name = "windows", version = "0.37" },              # from rodio v0.16.0
-    { name = "windows_aarch64_msvc", version = "0.37" }, # from rodio v0.16.0
-    { name = "windows_i686_gnu", version = "0.37" },     # from rodio v0.16.0
-    { name = "windows_i686_msvc", version = "0.37" },    # from rodio v0.16.0
-    { name = "windows_x86_64_gnu", version = "0.37" },   # from rodio v0.16.0
-    { name = "windows_x86_64_msvc", version = "0.37" },  # from rodio v0.16.0
 ]
 
 [sources]

From 17c663e39630266cef20c90cc1ddee13385a24cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 22:57:03 +0100
Subject: [PATCH 22/26] rodio 0.17 :tada:

---
 Cargo.toml                   | 3 ---
 crates/bevy_audio/Cargo.toml | 4 ++--
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index cbe43e3a556a4..77052e413dbe6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1733,6 +1733,3 @@ codegen-units = 1
 inherits = "release"
 lto = "fat"
 panic = "abort"
-
-[patch.crates-io]
-rodio = { git = "https://github.com/RustAudio/rodio" }
diff --git a/crates/bevy_audio/Cargo.toml b/crates/bevy_audio/Cargo.toml
index ac1510493d3cc..43902b12aaabf 100644
--- a/crates/bevy_audio/Cargo.toml
+++ b/crates/bevy_audio/Cargo.toml
@@ -20,14 +20,14 @@ 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.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]

From ceaa7cb48fbaff0ce123c1efdcd0f82807382d81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 23:18:44 +0100
Subject: [PATCH 23/26] remove outdated comments

---
 crates/bevy_audio/src/audio.rs | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index e4c0878d9ae9e..6c7982ccc9414 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -132,9 +132,6 @@ where
     /// 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.
     ///
-    /// The two channels can be randomly reversed when compiling in debug. This is fixed by
-    /// compiling in release: <https://github.com/RustAudio/rodio/issues/444>.
-    ///
     /// ```
     /// # use bevy_ecs::system::Res;
     /// # use bevy_asset::AssetServer;
@@ -210,9 +207,6 @@ where
     /// 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.
     ///
-    /// The two channels can be randomly reversed when compiling in debug. This is fixed by
-    /// compiling in release: <https://github.com/RustAudio/rodio/issues/444>.
-    ///
     /// ```
     /// # use bevy_ecs::system::Res;
     /// # use bevy_asset::AssetServer;

From ac5da74d0ec17b4438c39fbf0d99c0363fecd974 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 23:20:15 +0100
Subject: [PATCH 24/26] doc improvement

Co-Authored-By: Alice Cecile <alice.i.cecile@gmail.com>
---
 crates/bevy_audio/src/audio.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 6c7982ccc9414..fa08641c73fe0 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -62,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;
@@ -151,7 +151,7 @@ where
     ///
     /// 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 for control on the playback, or move the listener and emitter
+    /// to a strong handle allows you to control the playback, or move the listener and emitter
     /// through the [`SpatialAudioSink`] asset.
     ///
     /// ```

From 55afc9a1da7f5e69150f5a2f4d2c1f9095482d61 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 23:29:34 +0100
Subject: [PATCH 25/26] don't unwrap

---
 crates/bevy_audio/src/audio_output.rs | 49 +++++++++++++++++----------
 1 file changed, 31 insertions(+), 18 deletions(-)

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 832e6c3d98e34..30a86aa0fd36d 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -56,15 +56,22 @@ where
     f32: rodio::cpal::FromSample<Source::DecoderItem>,
 {
     fn play_source(&self, audio_source: &Source, repeat: bool) -> Option<Sink> {
-        self.stream_handle.as_ref().map(|stream_handle| {
-            let sink = Sink::try_new(stream_handle).unwrap();
-            if repeat {
-                sink.append(audio_source.decoder().repeat_infinite());
-            } else {
-                sink.append(audio_source.decoder());
-            }
-            sink
-        })
+        self.stream_handle
+            .as_ref()
+            .and_then(|stream_handle| match Sink::try_new(stream_handle) {
+                Ok(sink) => {
+                    if repeat {
+                        sink.append(audio_source.decoder().repeat_infinite());
+                    } else {
+                        sink.append(audio_source.decoder());
+                    }
+                    Some(sink)
+                }
+                Err(err) => {
+                    warn!("Error playing sound: {err:?}");
+                    None
+                }
+            })
     }
 
     fn play_spatial_source(
@@ -73,20 +80,26 @@ where
         repeat: bool,
         spatial: SpatialSettings,
     ) -> Option<SpatialSink> {
-        self.stream_handle.as_ref().map(|stream_handle| {
-            let sink = SpatialSink::try_new(
+        self.stream_handle.as_ref().and_then(|stream_handle| {
+            match SpatialSink::try_new(
                 stream_handle,
                 spatial.emitter,
                 spatial.left_ear,
                 spatial.right_ear,
-            )
-            .unwrap();
-            if repeat {
-                sink.append(audio_source.decoder().repeat_infinite());
-            } else {
-                sink.append(audio_source.decoder());
+            ) {
+                Ok(sink) => {
+                    if repeat {
+                        sink.append(audio_source.decoder().repeat_infinite());
+                    } else {
+                        sink.append(audio_source.decoder());
+                    }
+                    Some(sink)
+                }
+                Err(err) => {
+                    warn!("Error playing spatial sound: {err:?}");
+                    None
+                }
             }
-            sink
         })
     }
 

From 25c3c6be2de2a676853367ecf0d1c27473804f43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <mockersf@gmail.com>
Date: Fri, 17 Feb 2023 23:46:41 +0100
Subject: [PATCH 26/26] reformulate

---
 examples/audio/spatial_audio_2d.rs | 11 ++++++-----
 examples/audio/spatial_audio_3d.rs |  1 +
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index 67398a3493a26..44601d0e632b4 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -9,9 +9,9 @@ fn main() {
         .run();
 }
 
-/// 1 pixel would be one unit of distance for audio and sound attenuation would happen very fast.
-/// Keeping an audio span scale allow this example to have visible movements and shape size while keeping attenuation reasonable.
-const AUDIO_SPAN: f32 = 100.0;
+/// Spatial audio uses the distance to attenuate the sound volume. In 2D with the default camera, 1 pixel is 1 unit of distance,
+/// so we use a scale so that 100 pixels is 1 unit of distance for audio.
+const AUDIO_SCALE: f32 = 100.0;
 
 fn setup(
     mut commands: Commands,
@@ -21,6 +21,7 @@ fn setup(
     audio: Res<Audio>,
     audio_sinks: Res<Assets<SpatialAudioSink>>,
 ) {
+    // Space between the two ears
     let gap = 400.0;
 
     let music = asset_server.load("sounds/Windless Slopes.ogg");
@@ -28,7 +29,7 @@ fn setup(
         music,
         PlaybackSettings::LOOP,
         Transform::IDENTITY,
-        gap / AUDIO_SPAN,
+        gap / AUDIO_SCALE,
         Vec3::ZERO,
     ));
     commands.insert_resource(AudioController(handle));
@@ -85,6 +86,6 @@ fn update_positions(
     if let Some(sink) = audio_sinks.get(&music_controller.0) {
         let mut emitter_transform = emitter.single_mut();
         emitter_transform.translation.x = time.elapsed_seconds().sin() * 500.0;
-        sink.set_emitter_position(emitter_transform.translation / AUDIO_SPAN);
+        sink.set_emitter_position(emitter_transform.translation / AUDIO_SCALE);
     }
 }
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
index 91e973d776572..c9213a30cf765 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -17,6 +17,7 @@ fn setup(
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
+    // Space between the two ears
     let gap = 4.0;
 
     let music = asset_server.load("sounds/Windless Slopes.ogg");