From e94aa047360d833537e051a6dc417423bb4ddf75 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Mon, 17 Apr 2023 20:10:38 +0300
Subject: [PATCH 01/15] bevy_audio: ECS-based API redesign

---
 crates/bevy_audio/src/audio.rs        | 411 ++++++++------------------
 crates/bevy_audio/src/audio_output.rs | 201 +++++--------
 crates/bevy_audio/src/lib.rs          |  40 +--
 crates/bevy_audio/src/sinks.rs        |  53 +---
 examples/audio/audio.rs               |   7 +-
 examples/audio/audio_control.rs       |  42 +--
 examples/audio/decodable.rs           |   4 +-
 examples/audio/spatial_audio_2d.rs    |  51 ++--
 examples/audio/spatial_audio_3d.rs    |  53 ++--
 examples/games/breakout.rs            |  21 +-
 10 files changed, 323 insertions(+), 560 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 0e17168f9b6a6..4615bb8b5f6e3 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -1,256 +1,9 @@
-use crate::{AudioSink, AudioSource, Decodable, SpatialAudioSink};
-use bevy_asset::{Asset, Handle, HandleId};
+use crate::{AudioSource, Decodable};
+use bevy_asset::{Asset, Handle};
 use bevy_derive::{Deref, DerefMut};
-use bevy_ecs::system::Resource;
+use bevy_ecs::prelude::*;
 use bevy_math::Vec3;
 use bevy_transform::prelude::Transform;
-use parking_lot::RwLock;
-use std::{collections::VecDeque, fmt};
-
-/// Use this [`Resource`] to play audio.
-///
-/// ```
-/// # use bevy_ecs::system::Res;
-/// # use bevy_asset::AssetServer;
-/// # use bevy_audio::Audio;
-/// fn play_audio_system(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-///     audio.play(asset_server.load("my_sound.ogg"));
-/// }
-/// ```
-#[derive(Resource)]
-pub struct Audio<Source = AudioSource>
-where
-    Source: Asset + Decodable,
-{
-    /// Queue for playing audio from asset handles
-    pub(crate) queue: RwLock<VecDeque<AudioToPlay<Source>>>,
-}
-
-impl<Source: Asset> fmt::Debug for Audio<Source>
-where
-    Source: Decodable,
-{
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        f.debug_struct("Audio").field("queue", &self.queue).finish()
-    }
-}
-
-impl<Source> Default for Audio<Source>
-where
-    Source: Asset + Decodable,
-{
-    fn default() -> Self {
-        Self {
-            queue: Default::default(),
-        }
-    }
-}
-
-impl<Source> Audio<Source>
-where
-    Source: Asset + Decodable,
-{
-    /// Play audio from a [`Handle`] to the audio source
-    ///
-    /// ```
-    /// # use bevy_ecs::system::Res;
-    /// # use bevy_asset::AssetServer;
-    /// # use bevy_audio::Audio;
-    /// fn play_audio_system(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-    ///     audio.play(asset_server.load("my_sound.ogg"));
-    /// }
-    /// ```
-    ///
-    /// 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 you to control the playback through the [`AudioSink`] asset.
-    ///
-    /// ```
-    /// # use bevy_ecs::system::Res;
-    /// # use bevy_asset::{AssetServer, Assets};
-    /// # use bevy_audio::{Audio, AudioSink};
-    /// fn play_audio_system(
-    ///     asset_server: Res<AssetServer>,
-    ///     audio: Res<Audio>,
-    ///     audio_sinks: Res<Assets<AudioSink>>,
-    /// ) {
-    ///     // This is a weak handle, and can't be used to control playback.
-    ///     let weak_handle = audio.play(asset_server.load("my_sound.ogg"));
-    ///     // This is now a strong handle, and can be used to control playback.
-    ///     let strong_handle = audio_sinks.get_handle(weak_handle);
-    /// }
-    /// ```
-    pub fn play(&self, audio_source: Handle<Source>) -> Handle<AudioSink> {
-        let id = HandleId::random::<AudioSink>();
-        let config = AudioToPlay {
-            settings: PlaybackSettings::ONCE,
-            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 with [`PlaybackSettings`] that
-    /// allows looping or changing volume from the start.
-    ///
-    /// ```
-    /// # use bevy_ecs::system::Res;
-    /// # use bevy_asset::AssetServer;
-    /// # use bevy_audio::{Audio, Volume};
-    /// # use bevy_audio::PlaybackSettings;
-    /// fn play_audio_system(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-    ///     audio.play_with_settings(
-    ///         asset_server.load("my_sound.ogg"),
-    ///         PlaybackSettings::LOOP.with_volume(Volume::new_relative(0.75)),
-    ///     );
-    /// }
-    /// ```
-    ///
-    /// See [`Self::play`] on how to control playback once it's started.
-    pub fn play_with_settings(
-        &self,
-        audio_source: Handle<Source>,
-        settings: PlaybackSettings,
-    ) -> Handle<AudioSink> {
-        let id = HandleId::random::<AudioSink>();
-        let config = AudioToPlay {
-            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, Volume};
-    /// # 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(Volume::new_relative(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)
-    }
-}
 
 /// Defines the volume to play an audio source at.
 #[derive(Clone, Copy, Debug)]
@@ -278,7 +31,7 @@ impl Volume {
     }
 }
 
-/// A volume level equivalent to a positive only float.
+/// A volume level equivalent to a non-negative float.
 #[derive(Clone, Copy, Deref, DerefMut, Debug)]
 pub struct VolumeLevel(pub(crate) f32);
 
@@ -300,10 +53,13 @@ impl VolumeLevel {
     }
 }
 
-/// Settings to control playback from the start.
-#[derive(Clone, Copy, Debug)]
+/// Initial settings to be used when audio starts playing.
+/// If you would like to control the audio while it is playing, query for the
+/// [`AudioSink`] or [`SpatialAudioSink`] components.
+/// Changes to this component will *not* be applied to already-playing audio.
+#[derive(Component, Clone, Copy, Debug)]
 pub struct PlaybackSettings {
-    /// Play in repeat
+    /// Repeat/loop the sound.
     pub repeat: bool,
     /// Volume to play at.
     pub volume: Volume,
@@ -318,14 +74,14 @@ impl Default for PlaybackSettings {
 }
 
 impl PlaybackSettings {
-    /// Will play the associate audio source once.
+    /// Will play the associated audio source once.
     pub const ONCE: PlaybackSettings = PlaybackSettings {
         repeat: false,
         volume: Volume::Relative(VolumeLevel(1.0)),
         speed: 1.0,
     };
 
-    /// Will play the associate audio source in a loop.
+    /// Will play the associated audio source in a loop.
     pub const LOOP: PlaybackSettings = PlaybackSettings {
         repeat: true,
         volume: Volume::Relative(VolumeLevel(1.0)),
@@ -345,40 +101,39 @@ impl PlaybackSettings {
     }
 }
 
-#[derive(Clone)]
-pub(crate) struct SpatialSettings {
+/// Settings for playing spatial audio.
+///
+/// These settings are applied when the sound starts playing. If they are changed after
+/// the sound has started playing, they will have no effect. Bevy does not yet support
+/// moving positional sound sources.
+///
+/// Note: Bevy does not currently support HRTF or any other high-quality 3D sound rendering
+/// features. Spatial audio is implemented via simple left-right stereo panning.
+#[derive(Component, Clone, Debug)]
+pub 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
-    Source: Asset + Decodable,
-{
-    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>
-where
-    Source: Asset + Decodable,
-{
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("AudioToPlay")
-            .field("sink_handle", &self.sink_handle)
-            .field("source_handle", &self.source_handle)
-            .field("settings", &self.settings)
-            .finish()
+impl SpatialSettings {
+    /// Configure spatial audio coming from the `emitter` position and heard by a `listener`.
+    ///
+    /// The `listener` transform provides the position and rotation where the sound is to be
+    /// heard from. `gap` is the distance between the left and right "ears" of the listener.
+    /// `emitter` is the position where the sound comes from.
+    pub fn new(listener: Transform, gap: f32, emitter: Vec3) -> Self {
+        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(),
+        }
     }
 }
 
 /// Use this [`Resource`] to control the global volume of all audio with a [`Volume::Relative`] volume.
 ///
-/// Keep in mind that changing this value will not affect already playing audio.
+/// Note: changing this value will not affect already playing audio.
 #[derive(Resource, Default, Clone, Copy)]
 pub struct GlobalVolume {
     /// The global volume of all audio.
@@ -393,3 +148,99 @@ impl GlobalVolume {
         }
     }
 }
+
+/// Bundle for playing a sound.
+///
+/// Insert this bundle onto an entity to trigger a sound source to begin playing.
+///
+/// If the handle refers to an unavailable asset (such as if it has not finished loading yet),
+/// the audio will not begin playing immediately. The audio will play when the asset is ready.
+///
+/// When Bevy begins the audio playback, an [`AudioSink`] component will be added to the
+/// entity. You can use that component to control the audio settings during playback.
+#[derive(Bundle, Default)]
+pub struct AudioBundle<Source = AudioSource>
+where
+    Source: Asset + Decodable,
+{
+    /// Asset containing the audio data to play.
+    pub source: Handle<Source>,
+    /// Initial settings that the audio starts playing with.
+    /// If you would like to control the audio while it is playing,
+    /// query for the [`AudioSink`] component.
+    /// Changes to this component will *not* be applied to already-playing audio.
+    pub settings: PlaybackSettings,
+}
+
+impl AudioBundle<AudioSource> {
+    /// Create an [`AudioBundle`] from a standard Bevy audio source.
+    ///
+    /// Use this if you are loading an audio file asset in the formats supported by Bevy.
+    pub fn from_audio_source(handle: Handle<AudioSource>) -> Self {
+        AudioBundle {
+            source: handle,
+            settings: Default::default(),
+        }
+    }
+}
+
+impl<Source> AudioBundle<Source>
+where
+    Source: Asset + Decodable,
+{
+    /// Create an [`AudioBundle`] from a generic source asset type
+    ///
+    /// Use this if you have a custom source of audio data (not a regular audio file asset loaded by Bevy).
+    ///
+    /// Don't forget to register your custom type: `app.add_audio_source::<MySource>()`!
+    pub fn from_custom_source(handle: Handle<Source>) -> Self {
+        AudioBundle {
+            source: handle,
+            settings: Default::default(),
+        }
+    }
+
+    /// Configure the initial playback settings.
+    ///
+    /// The audio will start playing with these settings, when the source data is available.
+    pub fn with_settings(mut self, settings: PlaybackSettings) -> Self {
+        self.settings = settings;
+        self
+    }
+
+    /// Enable 3D spatial audio playback with the given configuration.
+    ///
+    /// Converts this bundle into a [`SpatialAudioBundle`].
+    pub fn with_spatial(self, spatial: SpatialSettings) -> SpatialAudioBundle<Source> {
+        SpatialAudioBundle {
+            source: self.source,
+            settings: self.settings,
+            spatial,
+        }
+    }
+}
+
+/// Bundle for playing a sound with a 3D position.
+///
+/// Insert this bundle onto an entity to trigger a sound source to begin playing.
+///
+/// If the handle refers to an unavailable asset (such as if it has not finished loading yet),
+/// the audio will not begin playing immediately. The audio will play when the asset is ready.
+///
+/// When Bevy begins the audio playback, a [`SpatialAudioSink`] component will be added to the
+/// entity. You can use that component to control the audio settings during playback.
+#[derive(Bundle)]
+pub struct SpatialAudioBundle<Source = AudioSource>
+where
+    Source: Asset + Decodable,
+{
+    /// Asset containing the audio data to play.
+    pub source: Handle<Source>,
+    /// Initial settings that the audio starts playing with.
+    /// If you would like to control the audio while it is playing,
+    /// query for the [`SpatialAudioSink`] component.
+    /// Changes to this component will *not* be applied to already-playing audio.
+    pub settings: PlaybackSettings,
+    /// Spatial audio configuration. Specifies the positions of the source and listener.
+    pub spatial: SpatialSettings,
+}
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index a133f1fb0e1bd..0cae3346435d1 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -1,11 +1,8 @@
-use crate::{
-    Audio, AudioSource, Decodable, GlobalVolume, SpatialAudioSink, SpatialSettings, Volume,
-};
-use bevy_asset::{Asset, Assets};
-use bevy_ecs::system::{Res, ResMut, Resource};
+use crate::{Decodable, GlobalVolume, PlaybackSettings, SpatialAudioSink, SpatialSettings, Volume};
+use bevy_asset::{Asset, Assets, Handle};
+use bevy_ecs::prelude::*;
 use bevy_utils::tracing::warn;
 use rodio::{OutputStream, OutputStreamHandle, Sink, Source, SpatialSink};
-use std::marker::PhantomData;
 
 use crate::AudioSink;
 
@@ -22,157 +19,117 @@ use crate::AudioSink;
 /// since the memory cost will be the same.
 /// However, repeatedly inserting this resource into the app will **leak more memory**.
 #[derive(Resource)]
-pub struct AudioOutput<Source = AudioSource>
-where
-    Source: Decodable,
-{
+pub(crate) struct AudioOutput {
     stream_handle: Option<OutputStreamHandle>,
-    phantom: PhantomData<Source>,
 }
 
-impl<Source> Default for AudioOutput<Source>
-where
-    Source: Decodable,
-{
+impl Default for AudioOutput {
     fn default() -> Self {
         if let Ok((stream, stream_handle)) = OutputStream::try_default() {
             // We leak `OutputStream` to prevent the audio from stopping.
             std::mem::forget(stream);
             Self {
                 stream_handle: Some(stream_handle),
-                phantom: PhantomData,
             }
         } else {
             warn!("No audio device found.");
             Self {
                 stream_handle: None,
-                phantom: PhantomData,
             }
         }
     }
 }
 
-impl<Source> AudioOutput<Source>
-where
-    Source: Asset + Decodable,
+/// Plays "queued" audio through the [`AudioOutput`] resource.
+///
+/// "Queued" audio is any audio entity (with the components from
+/// [`AudioBundle`] or [`SpatialAudioBundle`]) that does not have
+/// an [`AudioSink`]/[`SpatialAudioSink`] component.
+///
+/// This system detects such entities, checks if their source asset
+/// data is available, and creates/inserts the sink.
+pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
+    audio_output: Res<AudioOutput>,
+    audio_sources: Res<Assets<Source>>,
+    global_volume: Res<GlobalVolume>,
+    query_nonplaying: Query<
+        (
+            Entity,
+            &Handle<Source>,
+            &PlaybackSettings,
+            Option<&SpatialSettings>,
+        ),
+        (Without<AudioSink>, Without<SpatialAudioSink>),
+    >,
+    mut commands: Commands,
+) where
     f32: rodio::cpal::FromSample<Source::DecoderItem>,
 {
-    fn play_source(&self, audio_source: &Source, repeat: bool) -> Option<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
-                }
-            })
-    }
+    let Some(stream_handle) = audio_output.stream_handle.as_ref() else {
+        // audio output unavailable; cannot play sound
+        return;
+    };
 
-    fn play_spatial_source(
-        &self,
-        audio_source: &Source,
-        repeat: bool,
-        spatial: SpatialSettings,
-    ) -> Option<SpatialSink> {
-        self.stream_handle.as_ref().and_then(|stream_handle| {
-            match SpatialSink::try_new(
-                stream_handle,
-                spatial.emitter,
-                spatial.left_ear,
-                spatial.right_ear,
-            ) {
-                Ok(sink) => {
-                    if repeat {
-                        sink.append(audio_source.decoder().repeat_infinite());
-                    } else {
-                        sink.append(audio_source.decoder());
+    for (entity, source_handle, settings, spatial) in &query_nonplaying {
+        if let Some(audio_source) = audio_sources.get(source_handle) {
+            // audio data is available (has loaded), begin playback and insert sink component
+            if let Some(spatial) = spatial {
+                match SpatialSink::try_new(
+                    stream_handle,
+                    spatial.emitter,
+                    spatial.left_ear,
+                    spatial.right_ear,
+                ) {
+                    Ok(sink) => {
+                        if settings.repeat {
+                            sink.append(audio_source.decoder().repeat_infinite());
+                        } else {
+                            sink.append(audio_source.decoder());
+                        }
+                        sink.set_speed(settings.speed);
+                        match settings.volume {
+                            Volume::Relative(vol) => {
+                                sink.set_volume(vol.0 * global_volume.volume.0);
+                            }
+                            Volume::Absolute(vol) => sink.set_volume(vol.0),
+                        }
+                        commands
+                            .entity(entity)
+                            .insert(SpatialAudioSink { sink: Some(sink) });
+                    }
+                    Err(err) => {
+                        warn!("Error playing spatial sound: {err:?}");
                     }
-                    Some(sink)
-                }
-                Err(err) => {
-                    warn!("Error playing spatial sound: {err:?}");
-                    None
                 }
-            }
-        })
-    }
-
-    fn try_play_queued(
-        &self,
-        audio_sources: &Assets<Source>,
-        audio: &mut Audio<Source>,
-        sinks: &mut Assets<AudioSink>,
-        spatial_sinks: &mut Assets<SpatialAudioSink>,
-        global_volume: &GlobalVolume,
-    ) {
-        let mut queue = audio.queue.write();
-        let len = queue.len();
-        let mut i = 0;
-        while i < len {
-            let config = queue.pop_front().unwrap();
-            if let Some(audio_source) = audio_sources.get(&config.source_handle) {
-                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);
-                        match config.settings.volume {
+            } else {
+                match Sink::try_new(stream_handle) {
+                    Ok(sink) => {
+                        if settings.repeat {
+                            sink.append(audio_source.decoder().repeat_infinite());
+                        } else {
+                            sink.append(audio_source.decoder());
+                        }
+                        sink.set_speed(settings.speed);
+                        match settings.volume {
                             Volume::Relative(vol) => {
                                 sink.set_volume(vol.0 * global_volume.volume.0);
                             }
                             Volume::Absolute(vol) => sink.set_volume(vol.0),
                         }
-
-                        // 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) });
+                        commands
+                            .entity(entity)
+                            .insert(AudioSink { sink: Some(sink) });
                     }
-                } else if let Some(sink) = self.play_source(audio_source, config.settings.repeat) {
-                    sink.set_speed(config.settings.speed);
-
-                    match config.settings.volume {
-                        Volume::Relative(vol) => sink.set_volume(vol.0 * global_volume.volume.0),
-                        Volume::Absolute(vol) => sink.set_volume(vol.0),
+                    Err(err) => {
+                        warn!("Error playing sound: {err:?}");
                     }
-
-                    // 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
-                queue.push_back(config);
             }
-            i += 1;
         }
     }
 }
 
-/// Plays audio currently queued in the [`Audio`] resource through the [`AudioOutput`] resource
-pub fn play_queued_audio_system<Source: Asset + Decodable>(
-    audio_output: Res<AudioOutput<Source>>,
-    audio_sources: Option<Res<Assets<Source>>>,
-    global_volume: Res<GlobalVolume>,
-    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,
-            &global_volume,
-        );
-    };
+/// Run Condition to only play audio if the audio output is available
+pub(crate) fn audio_output_available(audio_output: Res<AudioOutput>) -> bool {
+    audio_output.stream_handle.is_some()
 }
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 6544c789698fc..89cde2a4a4d79 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -30,13 +30,12 @@ mod sinks;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        Audio, AudioOutput, AudioSink, AudioSinkPlayback, AudioSource, Decodable, GlobalVolume,
-        PlaybackSettings, SpatialAudioSink,
+        AudioBundle, AudioSink, AudioSinkPlayback, AudioSource, Decodable, GlobalVolume,
+        PlaybackSettings, SpatialAudioBundle, SpatialAudioSink, SpatialSettings,
     };
 }
 
 pub use audio::*;
-pub use audio_output::*;
 pub use audio_source::*;
 
 pub use rodio::cpal::Sample as CpalSample;
@@ -46,28 +45,35 @@ pub use sinks::*;
 
 use bevy_app::prelude::*;
 use bevy_asset::{AddAsset, Asset};
+use bevy_ecs::prelude::*;
+
+/// Set for the audio playback systems, so they can share a run condition
+#[derive(SystemSet, Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
+struct AudioPlaySet;
 
 /// Adds support for audio playback to a Bevy Application
 ///
-/// Use the [`Audio`] resource to play audio.
+/// Insert an [`AudioBundle`] or [`SpatialAudioBundle`] onto your entities to play audio.
 #[derive(Default)]
 pub struct AudioPlugin {
-    /// The global volume for all audio sources with a [`Volume::Relative`] volume.
+    /// The global volume for all audio entities with a [`Volume::Relative`] volume.
     pub global_volume: GlobalVolume,
 }
 
 impl Plugin for AudioPlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<AudioOutput<AudioSource>>()
-            .add_asset::<AudioSource>()
-            .add_asset::<AudioSink>()
-            .add_asset::<SpatialAudioSink>()
-            .init_resource::<Audio<AudioSource>>()
-            .insert_resource(self.global_volume)
-            .add_systems(PostUpdate, play_queued_audio_system::<AudioSource>);
+        app.insert_resource(self.global_volume)
+            .configure_set(
+                PostUpdate,
+                AudioPlaySet.run_if(crate::audio_output::audio_output_available),
+            )
+            .init_resource::<crate::audio_output::AudioOutput>();
 
         #[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
-        app.init_asset_loader::<AudioLoader>();
+        {
+            app.add_audio_source::<AudioSource>();
+            app.init_asset_loader::<AudioLoader>();
+        }
     }
 }
 
@@ -77,9 +83,9 @@ impl AddAudioSource for App {
         T: Decodable + Asset,
         f32: rodio::cpal::FromSample<T::DecoderItem>,
     {
-        self.add_asset::<T>()
-            .init_resource::<Audio<T>>()
-            .init_resource::<AudioOutput<T>>()
-            .add_systems(PostUpdate, play_queued_audio_system::<T>)
+        self.add_asset::<T>().add_systems(
+            PostUpdate,
+            crate::audio_output::play_queued_audio_system::<T>.in_set(AudioPlaySet),
+        )
     }
 }
diff --git a/crates/bevy_audio/src/sinks.rs b/crates/bevy_audio/src/sinks.rs
index 2746eaf195da2..189d9acd16074 100644
--- a/crates/bevy_audio/src/sinks.rs
+++ b/crates/bevy_audio/src/sinks.rs
@@ -1,5 +1,5 @@
+use bevy_ecs::component::Component;
 use bevy_math::Vec3;
-use bevy_reflect::{TypePath, TypeUuid};
 use bevy_transform::prelude::Transform;
 use rodio::{Sink, SpatialSink};
 
@@ -65,30 +65,13 @@ pub trait AudioSinkPlayback {
     fn empty(&self) -> bool;
 }
 
-/// Asset controlling the playback of a sound
+/// Used to control audio during playback.
 ///
-/// ```
-/// # use bevy_ecs::system::{Local, Res};
-/// # use bevy_asset::{Assets, Handle};
-/// # 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(
-///     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()
-///         }
-///     }
-/// }
-/// ```
+/// Bevy inserts this component onto your entities when it begins playing an audio source.
+/// Use [`AudioBundle`] to trigger that to happen.
 ///
-#[derive(TypePath, TypeUuid)]
-#[uuid = "8BEE570C-57C2-4FC0-8CFB-983A22F7D981"]
+/// You can use this component to modify the playback settings while the audio is playing.
+#[derive(Component)]
 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
@@ -139,27 +122,13 @@ impl AudioSinkPlayback for AudioSink {
     }
 }
 
-/// Asset controlling the playback of a sound, or the locations of its listener and emitter.
+/// Used to control spatial audio during playback.
 ///
-/// ```
-/// # 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(
-///     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));
-///     }
-/// }
-/// ```
+/// Bevy inserts this component onto your entities when it begins playing an audio source.
+/// Use [`SpatialAudioBundle`] to trigger that to happen.
 ///
-#[derive(TypePath, TypeUuid)]
-#[uuid = "F3CA4C47-595E-453B-96A7-31C3DDF2A177"]
+/// You can use this component to modify the playback settings while the audio is playing.
+#[derive(Component)]
 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
diff --git a/examples/audio/audio.rs b/examples/audio/audio.rs
index 8e70e39847985..0818cecb01093 100644
--- a/examples/audio/audio.rs
+++ b/examples/audio/audio.rs
@@ -9,7 +9,8 @@ fn main() {
         .run();
 }
 
-fn setup(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-    let music = asset_server.load("sounds/Windless Slopes.ogg");
-    audio.play(music);
+fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
+    commands.spawn(AudioBundle::from_audio_source(
+        asset_server.load("sounds/Windless Slopes.ogg"),
+    ));
 }
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index f14ef902a09e0..abb5cfde5b847 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -10,48 +10,32 @@ fn main() {
         .run();
 }
 
-fn setup(
-    mut commands: Commands,
-    asset_server: Res<AssetServer>,
-    audio: Res<Audio>,
-    audio_sinks: Res<Assets<AudioSink>>,
-) {
-    let music = asset_server.load("sounds/Windless Slopes.ogg");
-    let handle = audio_sinks.get_handle(audio.play(music));
-    commands.insert_resource(MusicController(handle));
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn((
+        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg")),
+        MyMusic,
+    ));
 }
 
-#[derive(Resource)]
-struct MusicController(Handle<AudioSink>);
+#[derive(Component)]
+struct MyMusic;
 
-fn update_speed(
-    audio_sinks: Res<Assets<AudioSink>>,
-    music_controller: Res<MusicController>,
-    time: Res<Time>,
-) {
-    if let Some(sink) = audio_sinks.get(&music_controller.0) {
+fn update_speed(music_controller: Query<&AudioSink, With<MyMusic>>, time: Res<Time>) {
+    if let Ok(sink) = music_controller.get_single() {
         sink.set_speed(((time.elapsed_seconds() / 5.0).sin() + 1.0).max(0.1));
     }
 }
 
-fn pause(
-    keyboard_input: Res<Input<KeyCode>>,
-    audio_sinks: Res<Assets<AudioSink>>,
-    music_controller: Res<MusicController>,
-) {
+fn pause(keyboard_input: Res<Input<KeyCode>>, music_controller: Query<&AudioSink, With<MyMusic>>) {
     if keyboard_input.just_pressed(KeyCode::Space) {
-        if let Some(sink) = audio_sinks.get(&music_controller.0) {
+        if let Ok(sink) = music_controller.get_single() {
             sink.toggle();
         }
     }
 }
 
-fn volume(
-    keyboard_input: Res<Input<KeyCode>>,
-    audio_sinks: Res<Assets<AudioSink>>,
-    music_controller: Res<MusicController>,
-) {
-    if let Some(sink) = audio_sinks.get(&music_controller.0) {
+fn volume(keyboard_input: Res<Input<KeyCode>>, music_controller: Query<&AudioSink, With<MyMusic>>) {
+    if let Ok(sink) = music_controller.get_single() {
         if keyboard_input.just_pressed(KeyCode::Plus) {
             sink.set_volume(sink.volume() + 0.1);
         } else if keyboard_input.just_pressed(KeyCode::Minus) {
diff --git a/examples/audio/decodable.rs b/examples/audio/decodable.rs
index 13a986c5af82d..dbf565afbc1dc 100644
--- a/examples/audio/decodable.rs
+++ b/examples/audio/decodable.rs
@@ -93,10 +93,10 @@ fn main() {
     .run();
 }
 
-fn setup(mut assets: ResMut<Assets<SineAudio>>, audio: Res<Audio<SineAudio>>) {
+fn setup(mut assets: ResMut<Assets<SineAudio>>, mut commands: Commands) {
     // add a `SineAudio` to the asset server so that it can be played
     let audio_handle = assets.add(SineAudio {
         frequency: 440., //this is the frequency of A4
     });
-    audio.play(audio_handle);
+    commands.spawn(AudioBundle::from_custom_source(audio_handle));
 }
diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index b5c52bbe20945..f87420064a3e5 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -18,21 +18,27 @@ fn setup(
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<ColorMaterial>>,
     asset_server: Res<AssetServer>,
-    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");
-    let handle = audio_sinks.get_handle(audio.play_spatial_with_settings(
-        music,
-        PlaybackSettings::LOOP,
-        Transform::IDENTITY,
-        gap / AUDIO_SCALE,
-        Vec3::ZERO,
+    // 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,
+        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+            .with_settings(PlaybackSettings::LOOP)
+            .with_spatial(SpatialSettings::new(
+                Transform::IDENTITY,
+                gap / AUDIO_SCALE,
+                Vec3::ZERO,
+            )),
     ));
-    commands.insert_resource(AudioController(handle));
 
     // left ear
     commands.spawn(SpriteBundle {
@@ -56,17 +62,6 @@ fn setup(
         ..default()
     });
 
-    // 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());
 }
@@ -74,18 +69,14 @@ fn setup(
 #[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>>,
+    mut emitters: Query<(&mut Transform, Option<&SpatialAudioSink>), With<Emitter>>,
 ) {
-    if let Some(sink) = audio_sinks.get(&music_controller.0) {
-        let mut emitter_transform = emitter.single_mut();
+    for (mut emitter_transform, sink) in emitters.iter_mut() {
         emitter_transform.translation.x = time.elapsed_seconds().sin() * 500.0;
-        sink.set_emitter_position(emitter_transform.translation / AUDIO_SCALE);
+        if let Some(sink) = &sink {
+            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 c9cfb839a8979..ffe75ad79d2ea 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -12,23 +12,28 @@ fn main() {
 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>>,
 ) {
     // Space between the two ears
     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,
+    // 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()
+        },
+        Emitter,
+        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+            .with_settings(PlaybackSettings::LOOP)
+            .with_spatial(SpatialSettings::new(Transform::IDENTITY, gap, Vec3::ZERO)),
     ));
-    commands.insert_resource(AudioController(handle));
 
     // left ear
     commands.spawn(PbrBundle {
@@ -46,20 +51,6 @@ fn setup(
         ..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()
-        },
-        Emitter,
-    ));
-
     // light
     commands.spawn(PointLightBundle {
         point_light: PointLight {
@@ -80,19 +71,15 @@ fn setup(
 #[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>>,
+    mut emitters: Query<(&mut Transform, Option<&SpatialAudioSink>), With<Emitter>>,
 ) {
-    if let Some(sink) = audio_sinks.get(&music_controller.0) {
-        let mut emitter_transform = emitter.single_mut();
+    for (mut emitter_transform, sink) in emitters.iter_mut() {
         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);
+        if let Some(sink) = &sink {
+            sink.set_emitter_position(emitter_transform.translation);
+        }
     }
 }
diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index a1db60dab67ec..a5b763a1be2cf 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -90,9 +90,14 @@ struct CollisionEvent;
 #[derive(Component)]
 struct Brick;
 
+/// Store the handle in a resource for ease of access
 #[derive(Resource)]
 struct CollisionSound(Handle<AudioSource>);
 
+/// Marker for the entity used for collision sound playback
+#[derive(Component)]
+struct CollisionSoundManager;
+
 // This bundle is a collection of the components that define a "wall" in our game
 #[derive(Bundle)]
 struct WallBundle {
@@ -404,14 +409,26 @@ fn check_for_collisions(
 }
 
 fn play_collision_sound(
+    mut commands: Commands,
     mut collision_events: EventReader<CollisionEvent>,
-    audio: Res<Audio>,
     sound: Res<CollisionSound>,
+    query_sound: Query<Entity, With<CollisionSoundManager>>,
 ) {
     // Play a sound once per frame if a collision occurred.
     if !collision_events.is_empty() {
         // This prevents events staying active on the next frame.
         collision_events.clear();
-        audio.play(sound.0.clone());
+
+        // If there is an existing sound entity, we can reuse it.
+        // Removing the AudioSink component will cause Bevy to play the sound again.
+        if let Ok(entity) = query_sound.get_single() {
+            commands.entity(entity).remove::<AudioSink>();
+        } else {
+            // The entity doesn't exist, create it.
+            commands.spawn((
+                CollisionSoundManager,
+                AudioBundle::from_audio_source(sound.0.clone()),
+            ));
+        }
     }
 }

From efb26442fc73072595b2838351a43e6a77ca3fba Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Mon, 17 Apr 2023 23:01:28 +0300
Subject: [PATCH 02/15] Add `paused` to PlaybackSettings

---
 crates/bevy_audio/src/audio.rs        | 12 ++++++++++++
 crates/bevy_audio/src/audio_output.rs | 26 ++++++++++++++++----------
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 4615bb8b5f6e3..abb3f5397dc2b 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -65,6 +65,10 @@ pub struct PlaybackSettings {
     pub volume: Volume,
     /// Speed to play at.
     pub speed: f32,
+    /// Create the sink in paused state.
+    /// Useful for "deferred playback", if you want to prepare
+    /// the entity, but hear the sound later.
+    pub paused: bool,
 }
 
 impl Default for PlaybackSettings {
@@ -79,6 +83,7 @@ impl PlaybackSettings {
         repeat: false,
         volume: Volume::Relative(VolumeLevel(1.0)),
         speed: 1.0,
+        paused: false,
     };
 
     /// Will play the associated audio source in a loop.
@@ -86,8 +91,15 @@ impl PlaybackSettings {
         repeat: true,
         volume: Volume::Relative(VolumeLevel(1.0)),
         speed: 1.0,
+        paused: false,
     };
 
+    /// Helper to start in a paused state.
+    pub const fn paused(mut self) -> Self {
+        self.paused = true;
+        self
+    }
+
     /// Helper to set the volume from start of playback.
     pub const fn with_volume(mut self, volume: Volume) -> Self {
         self.volume = volume;
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 0cae3346435d1..661baf859ac91 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -81,11 +81,6 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                     spatial.right_ear,
                 ) {
                     Ok(sink) => {
-                        if settings.repeat {
-                            sink.append(audio_source.decoder().repeat_infinite());
-                        } else {
-                            sink.append(audio_source.decoder());
-                        }
                         sink.set_speed(settings.speed);
                         match settings.volume {
                             Volume::Relative(vol) => {
@@ -93,6 +88,14 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                             }
                             Volume::Absolute(vol) => sink.set_volume(vol.0),
                         }
+                        if settings.paused {
+                            sink.pause();
+                        }
+                        if settings.repeat {
+                            sink.append(audio_source.decoder().repeat_infinite());
+                        } else {
+                            sink.append(audio_source.decoder());
+                        }
                         commands
                             .entity(entity)
                             .insert(SpatialAudioSink { sink: Some(sink) });
@@ -104,11 +107,6 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
             } else {
                 match Sink::try_new(stream_handle) {
                     Ok(sink) => {
-                        if settings.repeat {
-                            sink.append(audio_source.decoder().repeat_infinite());
-                        } else {
-                            sink.append(audio_source.decoder());
-                        }
                         sink.set_speed(settings.speed);
                         match settings.volume {
                             Volume::Relative(vol) => {
@@ -116,6 +114,14 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                             }
                             Volume::Absolute(vol) => sink.set_volume(vol.0),
                         }
+                        if settings.paused {
+                            sink.pause();
+                        }
+                        if settings.repeat {
+                            sink.append(audio_source.decoder().repeat_infinite());
+                        } else {
+                            sink.append(audio_source.decoder());
+                        }
                         commands
                             .entity(entity)
                             .insert(AudioSink { sink: Some(sink) });

From 915f76cb0ce5d1778a6dee29fd227dc792a7ee2f Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 00:09:35 +0300
Subject: [PATCH 03/15] bevy_audio: auto-despawn feature for fire-and-forget
 audio entities

---
 crates/bevy_audio/src/audio.rs        | 28 +++++++--
 crates/bevy_audio/src/audio_output.rs | 90 ++++++++++++++++++++++-----
 crates/bevy_audio/src/lib.rs          | 13 ++--
 examples/games/breakout.rs            | 23 ++-----
 4 files changed, 110 insertions(+), 44 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index abb3f5397dc2b..73e35bb5a836f 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -53,14 +53,25 @@ impl VolumeLevel {
     }
 }
 
+/// How should Bevy manage the sound playback?
+#[derive(Debug, Clone, Copy)]
+pub enum PlaybackMode {
+    /// Play the sound once. Do nothing when it ends.
+    Once,
+    /// Repeat the sound forever.
+    Loop,
+    /// Despawn the entity when the sound finishes playing.
+    Despawn,
+}
+
 /// Initial settings to be used when audio starts playing.
 /// If you would like to control the audio while it is playing, query for the
 /// [`AudioSink`] or [`SpatialAudioSink`] components.
 /// Changes to this component will *not* be applied to already-playing audio.
 #[derive(Component, Clone, Copy, Debug)]
 pub struct PlaybackSettings {
-    /// Repeat/loop the sound.
-    pub repeat: bool,
+    /// The desired playback behavior.
+    pub mode: PlaybackMode,
     /// Volume to play at.
     pub volume: Volume,
     /// Speed to play at.
@@ -73,6 +84,7 @@ pub struct PlaybackSettings {
 
 impl Default for PlaybackSettings {
     fn default() -> Self {
+        // TODO: should the default be ONCE or DESPAWN?
         Self::ONCE
     }
 }
@@ -80,7 +92,7 @@ impl Default for PlaybackSettings {
 impl PlaybackSettings {
     /// Will play the associated audio source once.
     pub const ONCE: PlaybackSettings = PlaybackSettings {
-        repeat: false,
+        mode: PlaybackMode::Once,
         volume: Volume::Relative(VolumeLevel(1.0)),
         speed: 1.0,
         paused: false,
@@ -88,7 +100,15 @@ impl PlaybackSettings {
 
     /// Will play the associated audio source in a loop.
     pub const LOOP: PlaybackSettings = PlaybackSettings {
-        repeat: true,
+        mode: PlaybackMode::Loop,
+        volume: Volume::Relative(VolumeLevel(1.0)),
+        speed: 1.0,
+        paused: false,
+    };
+
+    /// Will play the associated audio source once and despawn the entity.
+    pub const DESPAWN: PlaybackSettings = PlaybackSettings {
+        mode: PlaybackMode::Despawn,
         volume: Volume::Relative(VolumeLevel(1.0)),
         speed: 1.0,
         paused: false,
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 661baf859ac91..044edd82b76cf 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -1,4 +1,7 @@
-use crate::{Decodable, GlobalVolume, PlaybackSettings, SpatialAudioSink, SpatialSettings, Volume};
+use crate::{
+    Decodable, GlobalVolume, PlaybackMode, PlaybackSettings, SpatialAudioSink, SpatialSettings,
+    Volume,
+};
 use bevy_asset::{Asset, Assets, Handle};
 use bevy_ecs::prelude::*;
 use bevy_utils::tracing::warn;
@@ -40,6 +43,10 @@ impl Default for AudioOutput {
     }
 }
 
+/// Marker for internal use, to despawn entities when playback finishes.
+#[derive(Component)]
+pub(crate) struct PlaybackDespawnMarker;
+
 /// Plays "queued" audio through the [`AudioOutput`] resource.
 ///
 /// "Queued" audio is any audio entity (with the components from
@@ -91,14 +98,30 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                         if settings.paused {
                             sink.pause();
                         }
-                        if settings.repeat {
-                            sink.append(audio_source.decoder().repeat_infinite());
-                        } else {
-                            sink.append(audio_source.decoder());
-                        }
-                        commands
-                            .entity(entity)
-                            .insert(SpatialAudioSink { sink: Some(sink) });
+                        match settings.mode {
+                            PlaybackMode::Loop => {
+                                sink.append(audio_source.decoder().repeat_infinite());
+                                commands
+                                    .entity(entity)
+                                    .insert(SpatialAudioSink { sink: Some(sink) });
+                            }
+                            PlaybackMode::Once => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    .insert(SpatialAudioSink { sink: Some(sink) });
+                            }
+                            PlaybackMode::Despawn => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    // PERF: insert as bundle to reduce archetype moves
+                                    .insert((
+                                        SpatialAudioSink { sink: Some(sink) },
+                                        PlaybackDespawnMarker,
+                                    ));
+                            }
+                        };
                     }
                     Err(err) => {
                         warn!("Error playing spatial sound: {err:?}");
@@ -117,14 +140,30 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                         if settings.paused {
                             sink.pause();
                         }
-                        if settings.repeat {
-                            sink.append(audio_source.decoder().repeat_infinite());
-                        } else {
-                            sink.append(audio_source.decoder());
-                        }
-                        commands
-                            .entity(entity)
-                            .insert(AudioSink { sink: Some(sink) });
+                        match settings.mode {
+                            PlaybackMode::Loop => {
+                                sink.append(audio_source.decoder().repeat_infinite());
+                                commands
+                                    .entity(entity)
+                                    .insert(AudioSink { sink: Some(sink) });
+                            }
+                            PlaybackMode::Once => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    .insert(AudioSink { sink: Some(sink) });
+                            }
+                            PlaybackMode::Despawn => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    // PERF: insert as bundle to reduce archetype moves
+                                    .insert((
+                                        AudioSink { sink: Some(sink) },
+                                        PlaybackDespawnMarker,
+                                    ));
+                            }
+                        };
                     }
                     Err(err) => {
                         warn!("Error playing sound: {err:?}");
@@ -135,6 +174,23 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
     }
 }
 
+pub(crate) fn despawn_finished_audio_entities(
+    mut commands: Commands,
+    query_nonspatial: Query<(Entity, &AudioSink), With<PlaybackDespawnMarker>>,
+    query_spatial: Query<(Entity, &SpatialAudioSink), With<PlaybackDespawnMarker>>,
+) {
+    for (entity, sink) in &query_nonspatial {
+        if sink.sink.as_ref().unwrap().empty() {
+            commands.entity(entity).despawn();
+        }
+    }
+    for (entity, sink) in &query_spatial {
+        if sink.sink.as_ref().unwrap().empty() {
+            commands.entity(entity).despawn();
+        }
+    }
+}
+
 /// Run Condition to only play audio if the audio output is available
 pub(crate) fn audio_output_available(audio_output: Res<AudioOutput>) -> bool {
     audio_output.stream_handle.is_some()
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 89cde2a4a4d79..9bd9372faecb7 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -47,6 +47,8 @@ use bevy_app::prelude::*;
 use bevy_asset::{AddAsset, Asset};
 use bevy_ecs::prelude::*;
 
+use audio_output::*;
+
 /// Set for the audio playback systems, so they can share a run condition
 #[derive(SystemSet, Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
 struct AudioPlaySet;
@@ -63,11 +65,12 @@ pub struct AudioPlugin {
 impl Plugin for AudioPlugin {
     fn build(&self, app: &mut App) {
         app.insert_resource(self.global_volume)
-            .configure_set(
+            .configure_set(PostUpdate, AudioPlaySet.run_if(audio_output_available))
+            .init_resource::<AudioOutput>()
+            .add_systems(
                 PostUpdate,
-                AudioPlaySet.run_if(crate::audio_output::audio_output_available),
-            )
-            .init_resource::<crate::audio_output::AudioOutput>();
+                despawn_finished_audio_entities.in_set(AudioPlaySet),
+            );
 
         #[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
         {
@@ -85,7 +88,7 @@ impl AddAudioSource for App {
     {
         self.add_asset::<T>().add_systems(
             PostUpdate,
-            crate::audio_output::play_queued_audio_system::<T>.in_set(AudioPlaySet),
+            play_queued_audio_system::<T>.in_set(AudioPlaySet),
         )
     }
 }
diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index a5b763a1be2cf..2eb877ce382dc 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -90,14 +90,9 @@ struct CollisionEvent;
 #[derive(Component)]
 struct Brick;
 
-/// Store the handle in a resource for ease of access
 #[derive(Resource)]
 struct CollisionSound(Handle<AudioSource>);
 
-/// Marker for the entity used for collision sound playback
-#[derive(Component)]
-struct CollisionSoundManager;
-
 // This bundle is a collection of the components that define a "wall" in our game
 #[derive(Bundle)]
 struct WallBundle {
@@ -412,23 +407,15 @@ fn play_collision_sound(
     mut commands: Commands,
     mut collision_events: EventReader<CollisionEvent>,
     sound: Res<CollisionSound>,
-    query_sound: Query<Entity, With<CollisionSoundManager>>,
 ) {
     // Play a sound once per frame if a collision occurred.
     if !collision_events.is_empty() {
         // This prevents events staying active on the next frame.
         collision_events.clear();
-
-        // If there is an existing sound entity, we can reuse it.
-        // Removing the AudioSink component will cause Bevy to play the sound again.
-        if let Ok(entity) = query_sound.get_single() {
-            commands.entity(entity).remove::<AudioSink>();
-        } else {
-            // The entity doesn't exist, create it.
-            commands.spawn((
-                CollisionSoundManager,
-                AudioBundle::from_audio_source(sound.0.clone()),
-            ));
-        }
+        commands.spawn(
+            AudioBundle::from_audio_source(sound.0.clone())
+                // auto-despawn the entity when playback finishes
+                .with_settings(PlaybackSettings::DESPAWN)
+        );
     }
 }

From d4722a68310ab7b1ca8677f48f344da28d09b50d Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 00:22:31 +0300
Subject: [PATCH 04/15] fix mobile example

---
 examples/games/breakout.rs | 2 +-
 examples/mobile/src/lib.rs | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index 2eb877ce382dc..7ddd27145088e 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -415,7 +415,7 @@ fn play_collision_sound(
         commands.spawn(
             AudioBundle::from_audio_source(sound.0.clone())
                 // auto-despawn the entity when playback finishes
-                .with_settings(PlaybackSettings::DESPAWN)
+                .with_settings(PlaybackSettings::DESPAWN),
         );
     }
 }
diff --git a/examples/mobile/src/lib.rs b/examples/mobile/src/lib.rs
index 843b5cb539975..617da71db82a2 100644
--- a/examples/mobile/src/lib.rs
+++ b/examples/mobile/src/lib.rs
@@ -152,7 +152,9 @@ fn button_handler(
     }
 }
 
-fn setup_music(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-    let music = asset_server.load("sounds/Windless Slopes.ogg");
-    audio.play(music);
+fn setup_music(asset_server: Res<AssetServer>, mut commands: Commands) {
+    commands.spawn(
+        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+            .with_settings(PlaybackSettings::LOOP),
+    );
 }

From 306aa2b105d3452d958632e00831645465062191 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 00:29:05 +0300
Subject: [PATCH 05/15] fix bevy_audio crate doc

---
 crates/bevy_audio/src/lib.rs | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 9bd9372faecb7..7f2ee087ee08a 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -1,8 +1,8 @@
 //! Audio support for the game engine Bevy
 //!
 //! ```no_run
-//! # use bevy_ecs::{system::Res, event::EventWriter};
-//! # use bevy_audio::{Audio, AudioPlugin};
+//! # use bevy_ecs::prelude::*;
+//! # use bevy_audio::{AudioBundle, AudioPlugin};
 //! # use bevy_asset::{AssetPlugin, AssetServer};
 //! # use bevy_app::{App, AppExit, NoopPluginGroup as MinimalPlugins, Startup};
 //! fn main() {
@@ -12,8 +12,11 @@
 //!         .run();
 //! }
 //!
-//! fn play_background_audio(asset_server: Res<AssetServer>, audio: Res<Audio>) {
-//!     audio.play(asset_server.load("background_audio.ogg"));
+//! fn play_background_audio(asset_server: Res<AssetServer>, mut commands: Commands) {
+//!     commands.spawn(
+//!         AudioBundle::from_audio_source(asset_server.load("background_audio.ogg"))
+//!             .with_settings(PlaybackSettings::LOOP)
+//!     );
 //! }
 //! ```
 

From 69cf1d00c98472816aa5b37a1dc1a61bf7cb9ec5 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 00:40:40 +0300
Subject: [PATCH 06/15] oops missing import

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

diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 7f2ee087ee08a..8eff68cb650f7 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -2,7 +2,7 @@
 //!
 //! ```no_run
 //! # use bevy_ecs::prelude::*;
-//! # use bevy_audio::{AudioBundle, AudioPlugin};
+//! # use bevy_audio::{AudioBundle, AudioPlugin, PlaybackSettings};
 //! # use bevy_asset::{AssetPlugin, AssetServer};
 //! # use bevy_app::{App, AppExit, NoopPluginGroup as MinimalPlugins, Startup};
 //! fn main() {

From 22dfe366355a291fbc5350cc1d644fb76dbcfcc5 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 09:50:20 +0300
Subject: [PATCH 07/15] fix intra-doc links

---
 crates/bevy_audio/src/audio.rs | 17 +++++++++--------
 crates/bevy_audio/src/sinks.rs |  4 ++--
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 73e35bb5a836f..5fbb9a66871a8 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -66,8 +66,8 @@ pub enum PlaybackMode {
 
 /// Initial settings to be used when audio starts playing.
 /// If you would like to control the audio while it is playing, query for the
-/// [`AudioSink`] or [`SpatialAudioSink`] components.
-/// Changes to this component will *not* be applied to already-playing audio.
+/// [`AudioSink`][crate::AudioSink] or [`SpatialAudioSink`][crate::SpatialAudioSink]
+/// components. Changes to this component will *not* be applied to already-playing audio.
 #[derive(Component, Clone, Copy, Debug)]
 pub struct PlaybackSettings {
     /// The desired playback behavior.
@@ -188,8 +188,8 @@ impl GlobalVolume {
 /// If the handle refers to an unavailable asset (such as if it has not finished loading yet),
 /// the audio will not begin playing immediately. The audio will play when the asset is ready.
 ///
-/// When Bevy begins the audio playback, an [`AudioSink`] component will be added to the
-/// entity. You can use that component to control the audio settings during playback.
+/// When Bevy begins the audio playback, an [`AudioSink`][crate::AudioSink] component will be
+/// added to the entity. You can use that component to control the audio settings during playback.
 #[derive(Bundle, Default)]
 pub struct AudioBundle<Source = AudioSource>
 where
@@ -199,7 +199,7 @@ where
     pub source: Handle<Source>,
     /// Initial settings that the audio starts playing with.
     /// If you would like to control the audio while it is playing,
-    /// query for the [`AudioSink`] component.
+    /// query for the [`AudioSink`][crate::AudioSink] component.
     /// Changes to this component will *not* be applied to already-playing audio.
     pub settings: PlaybackSettings,
 }
@@ -259,8 +259,9 @@ where
 /// If the handle refers to an unavailable asset (such as if it has not finished loading yet),
 /// the audio will not begin playing immediately. The audio will play when the asset is ready.
 ///
-/// When Bevy begins the audio playback, a [`SpatialAudioSink`] component will be added to the
-/// entity. You can use that component to control the audio settings during playback.
+/// When Bevy begins the audio playback, a [`SpatialAudioSink`][crate::SpatialAudioSink]
+/// component will be added to the entity. You can use that component to control the audio
+/// settings during playback.
 #[derive(Bundle)]
 pub struct SpatialAudioBundle<Source = AudioSource>
 where
@@ -270,7 +271,7 @@ where
     pub source: Handle<Source>,
     /// Initial settings that the audio starts playing with.
     /// If you would like to control the audio while it is playing,
-    /// query for the [`SpatialAudioSink`] component.
+    /// query for the [`SpatialAudioSink`][crate::SpatialAudioSink] component.
     /// Changes to this component will *not* be applied to already-playing audio.
     pub settings: PlaybackSettings,
     /// Spatial audio configuration. Specifies the positions of the source and listener.
diff --git a/crates/bevy_audio/src/sinks.rs b/crates/bevy_audio/src/sinks.rs
index 189d9acd16074..2f5cf4c29c238 100644
--- a/crates/bevy_audio/src/sinks.rs
+++ b/crates/bevy_audio/src/sinks.rs
@@ -68,7 +68,7 @@ pub trait AudioSinkPlayback {
 /// Used to control audio during playback.
 ///
 /// Bevy inserts this component onto your entities when it begins playing an audio source.
-/// Use [`AudioBundle`] to trigger that to happen.
+/// Use [`AudioBundle`][crate::AudioBundle] to trigger that to happen.
 ///
 /// You can use this component to modify the playback settings while the audio is playing.
 #[derive(Component)]
@@ -125,7 +125,7 @@ impl AudioSinkPlayback for AudioSink {
 /// Used to control spatial audio during playback.
 ///
 /// Bevy inserts this component onto your entities when it begins playing an audio source.
-/// Use [`SpatialAudioBundle`] to trigger that to happen.
+/// Use [`SpatialAudioBundle`][crate::SpatialAudioBundle] to trigger that to happen.
 ///
 /// You can use this component to modify the playback settings while the audio is playing.
 #[derive(Component)]

From 4b58ae4216499735273656bc8481d95548a2a63a Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Tue, 18 Apr 2023 10:58:28 +0300
Subject: [PATCH 08/15] oh no more intra-docs were broken

---
 crates/bevy_audio/src/audio_output.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 044edd82b76cf..e3063bccb347f 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -50,8 +50,8 @@ pub(crate) struct PlaybackDespawnMarker;
 /// Plays "queued" audio through the [`AudioOutput`] resource.
 ///
 /// "Queued" audio is any audio entity (with the components from
-/// [`AudioBundle`] or [`SpatialAudioBundle`]) that does not have
-/// an [`AudioSink`]/[`SpatialAudioSink`] component.
+/// [`AudioBundle`][crate::AudioBundle] or [`SpatialAudioBundle`][crate::SpatialAudioBundle])
+/// that does not have an [`AudioSink`]/[`SpatialAudioSink`] component.
 ///
 /// This system detects such entities, checks if their source asset
 /// data is available, and creates/inserts the sink.

From 5fc848194f86516484e30a9450fabb94e558df1f Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 23 Jun 2023 15:59:36 +0300
Subject: [PATCH 09/15] make PlaybackDespawnMarker pub

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

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index e3063bccb347f..2e1f1d420f946 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -45,7 +45,7 @@ impl Default for AudioOutput {
 
 /// Marker for internal use, to despawn entities when playback finishes.
 #[derive(Component)]
-pub(crate) struct PlaybackDespawnMarker;
+pub struct PlaybackDespawnMarker;
 
 /// Plays "queued" audio through the [`AudioOutput`] resource.
 ///

From eb40da9ff1146e3dd0019d3236da765580cccd5b Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 23 Jun 2023 16:04:58 +0300
Subject: [PATCH 10/15] Rename
 `AudioBundle::{from_audio_source,from_custom_source}` to
 `AudioBundle::{from_audio,from_custom_audio}`

---
 crates/bevy_audio/src/audio.rs     | 4 ++--
 examples/audio/audio.rs            | 2 +-
 examples/audio/audio_control.rs    | 2 +-
 examples/audio/decodable.rs        | 2 +-
 examples/audio/spatial_audio_2d.rs | 2 +-
 examples/audio/spatial_audio_3d.rs | 2 +-
 examples/games/breakout.rs         | 2 +-
 examples/mobile/src/lib.rs         | 2 +-
 8 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 5fbb9a66871a8..5922dd880c2ff 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -208,7 +208,7 @@ impl AudioBundle<AudioSource> {
     /// Create an [`AudioBundle`] from a standard Bevy audio source.
     ///
     /// Use this if you are loading an audio file asset in the formats supported by Bevy.
-    pub fn from_audio_source(handle: Handle<AudioSource>) -> Self {
+    pub fn from_audio(handle: Handle<AudioSource>) -> Self {
         AudioBundle {
             source: handle,
             settings: Default::default(),
@@ -225,7 +225,7 @@ where
     /// Use this if you have a custom source of audio data (not a regular audio file asset loaded by Bevy).
     ///
     /// Don't forget to register your custom type: `app.add_audio_source::<MySource>()`!
-    pub fn from_custom_source(handle: Handle<Source>) -> Self {
+    pub fn from_custom_audio(handle: Handle<Source>) -> Self {
         AudioBundle {
             source: handle,
             settings: Default::default(),
diff --git a/examples/audio/audio.rs b/examples/audio/audio.rs
index 0818cecb01093..ca08a9e44cf64 100644
--- a/examples/audio/audio.rs
+++ b/examples/audio/audio.rs
@@ -10,7 +10,7 @@ fn main() {
 }
 
 fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
-    commands.spawn(AudioBundle::from_audio_source(
+    commands.spawn(AudioBundle::from_audio(
         asset_server.load("sounds/Windless Slopes.ogg"),
     ));
 }
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index abb5cfde5b847..37511a4515542 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -12,7 +12,7 @@ fn main() {
 
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.spawn((
-        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg")),
+        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg")),
         MyMusic,
     ));
 }
diff --git a/examples/audio/decodable.rs b/examples/audio/decodable.rs
index dbf565afbc1dc..e1d57892ffb67 100644
--- a/examples/audio/decodable.rs
+++ b/examples/audio/decodable.rs
@@ -98,5 +98,5 @@ fn setup(mut assets: ResMut<Assets<SineAudio>>, mut commands: Commands) {
     let audio_handle = assets.add(SineAudio {
         frequency: 440., //this is the frequency of A4
     });
-    commands.spawn(AudioBundle::from_custom_source(audio_handle));
+    commands.spawn(AudioBundle::from_custom_audio(audio_handle));
 }
diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index f87420064a3e5..549e9ff65a65b 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -31,7 +31,7 @@ fn setup(
             ..default()
         },
         Emitter,
-        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
             .with_settings(PlaybackSettings::LOOP)
             .with_spatial(SpatialSettings::new(
                 Transform::IDENTITY,
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
index ffe75ad79d2ea..de6c2292ee09d 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -30,7 +30,7 @@ fn setup(
             ..default()
         },
         Emitter,
-        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
             .with_settings(PlaybackSettings::LOOP)
             .with_spatial(SpatialSettings::new(Transform::IDENTITY, gap, Vec3::ZERO)),
     ));
diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index 7ddd27145088e..581b33985d358 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -413,7 +413,7 @@ fn play_collision_sound(
         // This prevents events staying active on the next frame.
         collision_events.clear();
         commands.spawn(
-            AudioBundle::from_audio_source(sound.0.clone())
+            AudioBundle::from_audio(sound.0.clone())
                 // auto-despawn the entity when playback finishes
                 .with_settings(PlaybackSettings::DESPAWN),
         );
diff --git a/examples/mobile/src/lib.rs b/examples/mobile/src/lib.rs
index 617da71db82a2..4ae213156206b 100644
--- a/examples/mobile/src/lib.rs
+++ b/examples/mobile/src/lib.rs
@@ -154,7 +154,7 @@ fn button_handler(
 
 fn setup_music(asset_server: Res<AssetServer>, mut commands: Commands) {
     commands.spawn(
-        AudioBundle::from_audio_source(asset_server.load("sounds/Windless Slopes.ogg"))
+        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
             .with_settings(PlaybackSettings::LOOP),
     );
 }

From b6eaaf59c6318d70722674adec1fe8a2d4350029 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 23 Jun 2023 16:15:54 +0300
Subject: [PATCH 11/15] remove misleading info from doc comment about
 positional audio

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

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 5922dd880c2ff..5b890f73103a2 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -135,10 +135,6 @@ impl PlaybackSettings {
 
 /// Settings for playing spatial audio.
 ///
-/// These settings are applied when the sound starts playing. If they are changed after
-/// the sound has started playing, they will have no effect. Bevy does not yet support
-/// moving positional sound sources.
-///
 /// Note: Bevy does not currently support HRTF or any other high-quality 3D sound rendering
 /// features. Spatial audio is implemented via simple left-right stereo panning.
 #[derive(Component, Clone, Debug)]

From 4dd77076b8c18e2292b8abeab66fb8c05b68153d Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 23 Jun 2023 18:29:10 +0300
Subject: [PATCH 12/15] bevy_audio: add PlaybackMode::Remove

---
 crates/bevy_audio/src/audio.rs        | 14 ++++++--
 crates/bevy_audio/src/audio_output.rs | 51 +++++++++++++++++++++++----
 crates/bevy_audio/src/lib.rs          |  5 +--
 3 files changed, 57 insertions(+), 13 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index 5b890f73103a2..e8be1d91b9e3f 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -62,6 +62,8 @@ pub enum PlaybackMode {
     Loop,
     /// Despawn the entity when the sound finishes playing.
     Despawn,
+    /// Remove the audio components from the entity, when the sound finishes playing.
+    Remove,
 }
 
 /// Initial settings to be used when audio starts playing.
@@ -84,7 +86,7 @@ pub struct PlaybackSettings {
 
 impl Default for PlaybackSettings {
     fn default() -> Self {
-        // TODO: should the default be ONCE or DESPAWN?
+        // TODO: what should the default be: ONCE/DESPAWN/REMOVE?
         Self::ONCE
     }
 }
@@ -106,7 +108,7 @@ impl PlaybackSettings {
         paused: false,
     };
 
-    /// Will play the associated audio source once and despawn the entity.
+    /// Will play the associated audio source once and despawn the entity afterwards.
     pub const DESPAWN: PlaybackSettings = PlaybackSettings {
         mode: PlaybackMode::Despawn,
         volume: Volume::Relative(VolumeLevel(1.0)),
@@ -114,6 +116,14 @@ impl PlaybackSettings {
         paused: false,
     };
 
+    /// Will play the associated audio source once and remove the audio components afterwards.
+    pub const REMOVE: PlaybackSettings = PlaybackSettings {
+        mode: PlaybackMode::Remove,
+        volume: Volume::Relative(VolumeLevel(1.0)),
+        speed: 1.0,
+        paused: false,
+    };
+
     /// Helper to start in a paused state.
     pub const fn paused(mut self) -> Self {
         self.paused = true;
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 2e1f1d420f946..6e169f461ac90 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -1,6 +1,6 @@
 use crate::{
-    Decodable, GlobalVolume, PlaybackMode, PlaybackSettings, SpatialAudioSink, SpatialSettings,
-    Volume,
+    AudioBundle, Decodable, GlobalVolume, PlaybackMode, PlaybackSettings, SpatialAudioBundle,
+    SpatialAudioSink, SpatialSettings, Volume,
 };
 use bevy_asset::{Asset, Assets, Handle};
 use bevy_ecs::prelude::*;
@@ -47,6 +47,10 @@ impl Default for AudioOutput {
 #[derive(Component)]
 pub struct PlaybackDespawnMarker;
 
+/// Marker for internal use, to remove audio components when playback finishes.
+#[derive(Component)]
+pub struct PlaybackRemoveMarker;
+
 /// Plays "queued" audio through the [`AudioOutput`] resource.
 ///
 /// "Queued" audio is any audio entity (with the components from
@@ -121,6 +125,16 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                                         PlaybackDespawnMarker,
                                     ));
                             }
+                            PlaybackMode::Remove => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    // PERF: insert as bundle to reduce archetype moves
+                                    .insert((
+                                        SpatialAudioSink { sink: Some(sink) },
+                                        PlaybackRemoveMarker,
+                                    ));
+                            }
                         };
                     }
                     Err(err) => {
@@ -163,6 +177,13 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
                                         PlaybackDespawnMarker,
                                     ));
                             }
+                            PlaybackMode::Remove => {
+                                sink.append(audio_source.decoder());
+                                commands
+                                    .entity(entity)
+                                    // PERF: insert as bundle to reduce archetype moves
+                                    .insert((AudioSink { sink: Some(sink) }, PlaybackRemoveMarker));
+                            }
                         };
                     }
                     Err(err) => {
@@ -174,21 +195,37 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
     }
 }
 
-pub(crate) fn despawn_finished_audio_entities(
+pub(crate) fn cleanup_finished_audio(
     mut commands: Commands,
-    query_nonspatial: Query<(Entity, &AudioSink), With<PlaybackDespawnMarker>>,
-    query_spatial: Query<(Entity, &SpatialAudioSink), With<PlaybackDespawnMarker>>,
+    query_nonspatial_despawn: Query<(Entity, &AudioSink), With<PlaybackDespawnMarker>>,
+    query_spatial_despawn: Query<(Entity, &SpatialAudioSink), With<PlaybackDespawnMarker>>,
+    query_nonspatial_remove: Query<(Entity, &AudioSink), With<PlaybackRemoveMarker>>,
+    query_spatial_remove: Query<(Entity, &SpatialAudioSink), With<PlaybackRemoveMarker>>,
 ) {
-    for (entity, sink) in &query_nonspatial {
+    for (entity, sink) in &query_nonspatial_despawn {
         if sink.sink.as_ref().unwrap().empty() {
             commands.entity(entity).despawn();
         }
     }
-    for (entity, sink) in &query_spatial {
+    for (entity, sink) in &query_spatial_despawn {
         if sink.sink.as_ref().unwrap().empty() {
             commands.entity(entity).despawn();
         }
     }
+    for (entity, sink) in &query_nonspatial_remove {
+        if sink.sink.as_ref().unwrap().empty() {
+            commands
+                .entity(entity)
+                .remove::<(AudioBundle, AudioSink, PlaybackRemoveMarker)>();
+        }
+    }
+    for (entity, sink) in &query_spatial_remove {
+        if sink.sink.as_ref().unwrap().empty() {
+            commands
+                .entity(entity)
+                .remove::<(SpatialAudioBundle, SpatialAudioSink, PlaybackRemoveMarker)>();
+        }
+    }
 }
 
 /// Run Condition to only play audio if the audio output is available
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 8eff68cb650f7..6c75f1af85a6e 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -70,10 +70,7 @@ impl Plugin for AudioPlugin {
         app.insert_resource(self.global_volume)
             .configure_set(PostUpdate, AudioPlaySet.run_if(audio_output_available))
             .init_resource::<AudioOutput>()
-            .add_systems(
-                PostUpdate,
-                despawn_finished_audio_entities.in_set(AudioPlaySet),
-            );
+            .add_systems(PostUpdate, cleanup_finished_audio.in_set(AudioPlaySet));
 
         #[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
         {

From 1ef4372ffcd66d7101142ed07ce4bd1965c5ccae Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 7 Jul 2023 22:22:06 +0300
Subject: [PATCH 13/15] audio cleanup fn must be generic over stream type

---
 crates/bevy_audio/src/audio_output.rs | 32 +++++++++++++++++++--------
 crates/bevy_audio/src/lib.rs          |  7 +++---
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 6e169f461ac90..01d58d7ccfd8c 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -195,12 +195,24 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
     }
 }
 
-pub(crate) fn cleanup_finished_audio(
+pub(crate) fn cleanup_finished_audio<T: Decodable + Asset>(
     mut commands: Commands,
-    query_nonspatial_despawn: Query<(Entity, &AudioSink), With<PlaybackDespawnMarker>>,
-    query_spatial_despawn: Query<(Entity, &SpatialAudioSink), With<PlaybackDespawnMarker>>,
-    query_nonspatial_remove: Query<(Entity, &AudioSink), With<PlaybackRemoveMarker>>,
-    query_spatial_remove: Query<(Entity, &SpatialAudioSink), With<PlaybackRemoveMarker>>,
+    query_nonspatial_despawn: Query<
+        (Entity, &AudioSink),
+        (With<PlaybackDespawnMarker>, With<Handle<T>>),
+    >,
+    query_spatial_despawn: Query<
+        (Entity, &SpatialAudioSink),
+        (With<PlaybackDespawnMarker>, With<Handle<T>>),
+    >,
+    query_nonspatial_remove: Query<
+        (Entity, &AudioSink),
+        (With<PlaybackRemoveMarker>, With<Handle<T>>),
+    >,
+    query_spatial_remove: Query<
+        (Entity, &SpatialAudioSink),
+        (With<PlaybackRemoveMarker>, With<Handle<T>>),
+    >,
 ) {
     for (entity, sink) in &query_nonspatial_despawn {
         if sink.sink.as_ref().unwrap().empty() {
@@ -216,14 +228,16 @@ pub(crate) fn cleanup_finished_audio(
         if sink.sink.as_ref().unwrap().empty() {
             commands
                 .entity(entity)
-                .remove::<(AudioBundle, AudioSink, PlaybackRemoveMarker)>();
+                .remove::<(AudioSourceBundle<T>, AudioSink, PlaybackRemoveMarker)>();
         }
     }
     for (entity, sink) in &query_spatial_remove {
         if sink.sink.as_ref().unwrap().empty() {
-            commands
-                .entity(entity)
-                .remove::<(SpatialAudioBundle, SpatialAudioSink, PlaybackRemoveMarker)>();
+            commands.entity(entity).remove::<(
+                SpatialAudioSourceBundle<T>,
+                SpatialAudioSink,
+                PlaybackRemoveMarker,
+            )>();
         }
     }
 }
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 6c75f1af85a6e..544417a6edc82 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -69,8 +69,7 @@ impl Plugin for AudioPlugin {
     fn build(&self, app: &mut App) {
         app.insert_resource(self.global_volume)
             .configure_set(PostUpdate, AudioPlaySet.run_if(audio_output_available))
-            .init_resource::<AudioOutput>()
-            .add_systems(PostUpdate, cleanup_finished_audio.in_set(AudioPlaySet));
+            .init_resource::<AudioOutput>();
 
         #[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
         {
@@ -89,6 +88,8 @@ impl AddAudioSource for App {
         self.add_asset::<T>().add_systems(
             PostUpdate,
             play_queued_audio_system::<T>.in_set(AudioPlaySet),
-        )
+        );
+        self.add_systems(PostUpdate, cleanup_finished_audio::<T>.in_set(AudioPlaySet));
+        self
     }
 }

From 7ebf5a02d58a2695abbf08a86db405b5e1fdfc88 Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 7 Jul 2023 22:54:24 +0300
Subject: [PATCH 14/15] remove bundle constructor methods; use type alias for
 better UX

---
 crates/bevy_audio/src/audio.rs        | 59 ++++++---------------------
 crates/bevy_audio/src/audio_output.rs |  4 +-
 crates/bevy_audio/src/lib.rs          |  5 ++-
 examples/audio/audio.rs               |  7 ++--
 examples/audio/audio_control.rs       |  5 ++-
 examples/audio/decodable.rs           |  5 ++-
 examples/audio/spatial_audio_2d.rs    | 12 +++---
 examples/audio/spatial_audio_3d.rs    |  8 ++--
 examples/games/breakout.rs            | 10 ++---
 examples/mobile/src/lib.rs            |  8 ++--
 10 files changed, 49 insertions(+), 74 deletions(-)

diff --git a/crates/bevy_audio/src/audio.rs b/crates/bevy_audio/src/audio.rs
index e8be1d91b9e3f..546e158e3f906 100644
--- a/crates/bevy_audio/src/audio.rs
+++ b/crates/bevy_audio/src/audio.rs
@@ -187,6 +187,12 @@ impl GlobalVolume {
     }
 }
 
+/// Bundle for playing a standard bevy audio asset
+pub type AudioBundle = AudioSourceBundle<AudioSource>;
+
+/// Bundle for playing a standard bevy audio asset with a 3D position
+pub type SpatialAudioBundle = SpatialAudioSourceBundle<AudioSource>;
+
 /// Bundle for playing a sound.
 ///
 /// Insert this bundle onto an entity to trigger a sound source to begin playing.
@@ -196,8 +202,8 @@ impl GlobalVolume {
 ///
 /// When Bevy begins the audio playback, an [`AudioSink`][crate::AudioSink] component will be
 /// added to the entity. You can use that component to control the audio settings during playback.
-#[derive(Bundle, Default)]
-pub struct AudioBundle<Source = AudioSource>
+#[derive(Bundle)]
+pub struct AudioSourceBundle<Source = AudioSource>
 where
     Source: Asset + Decodable,
 {
@@ -210,52 +216,13 @@ where
     pub settings: PlaybackSettings,
 }
 
-impl AudioBundle<AudioSource> {
-    /// Create an [`AudioBundle`] from a standard Bevy audio source.
-    ///
-    /// Use this if you are loading an audio file asset in the formats supported by Bevy.
-    pub fn from_audio(handle: Handle<AudioSource>) -> Self {
-        AudioBundle {
-            source: handle,
-            settings: Default::default(),
-        }
-    }
-}
-
-impl<Source> AudioBundle<Source>
-where
-    Source: Asset + Decodable,
-{
-    /// Create an [`AudioBundle`] from a generic source asset type
-    ///
-    /// Use this if you have a custom source of audio data (not a regular audio file asset loaded by Bevy).
-    ///
-    /// Don't forget to register your custom type: `app.add_audio_source::<MySource>()`!
-    pub fn from_custom_audio(handle: Handle<Source>) -> Self {
-        AudioBundle {
-            source: handle,
+impl<T: Decodable + Asset> Default for AudioSourceBundle<T> {
+    fn default() -> Self {
+        Self {
+            source: Default::default(),
             settings: Default::default(),
         }
     }
-
-    /// Configure the initial playback settings.
-    ///
-    /// The audio will start playing with these settings, when the source data is available.
-    pub fn with_settings(mut self, settings: PlaybackSettings) -> Self {
-        self.settings = settings;
-        self
-    }
-
-    /// Enable 3D spatial audio playback with the given configuration.
-    ///
-    /// Converts this bundle into a [`SpatialAudioBundle`].
-    pub fn with_spatial(self, spatial: SpatialSettings) -> SpatialAudioBundle<Source> {
-        SpatialAudioBundle {
-            source: self.source,
-            settings: self.settings,
-            spatial,
-        }
-    }
 }
 
 /// Bundle for playing a sound with a 3D position.
@@ -269,7 +236,7 @@ where
 /// component will be added to the entity. You can use that component to control the audio
 /// settings during playback.
 #[derive(Bundle)]
-pub struct SpatialAudioBundle<Source = AudioSource>
+pub struct SpatialAudioSourceBundle<Source = AudioSource>
 where
     Source: Asset + Decodable,
 {
diff --git a/crates/bevy_audio/src/audio_output.rs b/crates/bevy_audio/src/audio_output.rs
index 01d58d7ccfd8c..fd2173f6726d3 100644
--- a/crates/bevy_audio/src/audio_output.rs
+++ b/crates/bevy_audio/src/audio_output.rs
@@ -1,6 +1,6 @@
 use crate::{
-    AudioBundle, Decodable, GlobalVolume, PlaybackMode, PlaybackSettings, SpatialAudioBundle,
-    SpatialAudioSink, SpatialSettings, Volume,
+    AudioSourceBundle, Decodable, GlobalVolume, PlaybackMode, PlaybackSettings, SpatialAudioSink,
+    SpatialAudioSourceBundle, SpatialSettings, Volume,
 };
 use bevy_asset::{Asset, Assets, Handle};
 use bevy_ecs::prelude::*;
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 544417a6edc82..16d6f03238d6a 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -33,8 +33,9 @@ mod sinks;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        AudioBundle, AudioSink, AudioSinkPlayback, AudioSource, Decodable, GlobalVolume,
-        PlaybackSettings, SpatialAudioBundle, SpatialAudioSink, SpatialSettings,
+        AudioBundle, AudioSink, AudioSinkPlayback, AudioSource, AudioSourceBundle, Decodable,
+        GlobalVolume, PlaybackSettings, SpatialAudioBundle, SpatialAudioSink,
+        SpatialAudioSourceBundle, SpatialSettings,
     };
 }
 
diff --git a/examples/audio/audio.rs b/examples/audio/audio.rs
index ca08a9e44cf64..96ebdbb19e121 100644
--- a/examples/audio/audio.rs
+++ b/examples/audio/audio.rs
@@ -10,7 +10,8 @@ fn main() {
 }
 
 fn setup(asset_server: Res<AssetServer>, mut commands: Commands) {
-    commands.spawn(AudioBundle::from_audio(
-        asset_server.load("sounds/Windless Slopes.ogg"),
-    ));
+    commands.spawn(AudioBundle {
+        source: asset_server.load("sounds/Windless Slopes.ogg"),
+        ..default()
+    });
 }
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index 37511a4515542..05be780713757 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -12,7 +12,10 @@ fn main() {
 
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.spawn((
-        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg")),
+        AudioBundle {
+            source: asset_server.load("sounds/Windless Slopes.ogg"),
+            ..default()
+        },
         MyMusic,
     ));
 }
diff --git a/examples/audio/decodable.rs b/examples/audio/decodable.rs
index e1d57892ffb67..9ed6539d24c9e 100644
--- a/examples/audio/decodable.rs
+++ b/examples/audio/decodable.rs
@@ -98,5 +98,8 @@ fn setup(mut assets: ResMut<Assets<SineAudio>>, mut commands: Commands) {
     let audio_handle = assets.add(SineAudio {
         frequency: 440., //this is the frequency of A4
     });
-    commands.spawn(AudioBundle::from_custom_audio(audio_handle));
+    commands.spawn(AudioSourceBundle {
+        source: audio_handle,
+        ..default()
+    });
 }
diff --git a/examples/audio/spatial_audio_2d.rs b/examples/audio/spatial_audio_2d.rs
index 549e9ff65a65b..5a9c93a034edc 100644
--- a/examples/audio/spatial_audio_2d.rs
+++ b/examples/audio/spatial_audio_2d.rs
@@ -31,13 +31,11 @@ fn setup(
             ..default()
         },
         Emitter,
-        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
-            .with_settings(PlaybackSettings::LOOP)
-            .with_spatial(SpatialSettings::new(
-                Transform::IDENTITY,
-                gap / AUDIO_SCALE,
-                Vec3::ZERO,
-            )),
+        SpatialAudioBundle {
+            source: asset_server.load("sounds/Windless Slopes.ogg"),
+            settings: PlaybackSettings::LOOP,
+            spatial: SpatialSettings::new(Transform::IDENTITY, gap / AUDIO_SCALE, Vec3::ZERO),
+        },
     ));
 
     // left ear
diff --git a/examples/audio/spatial_audio_3d.rs b/examples/audio/spatial_audio_3d.rs
index de6c2292ee09d..e7cea097687ed 100644
--- a/examples/audio/spatial_audio_3d.rs
+++ b/examples/audio/spatial_audio_3d.rs
@@ -30,9 +30,11 @@ fn setup(
             ..default()
         },
         Emitter,
-        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
-            .with_settings(PlaybackSettings::LOOP)
-            .with_spatial(SpatialSettings::new(Transform::IDENTITY, gap, Vec3::ZERO)),
+        SpatialAudioBundle {
+            source: asset_server.load("sounds/Windless Slopes.ogg"),
+            settings: PlaybackSettings::LOOP,
+            spatial: SpatialSettings::new(Transform::IDENTITY, gap, Vec3::ZERO),
+        },
     ));
 
     // left ear
diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index 581b33985d358..d582856cc52dc 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -412,10 +412,10 @@ fn play_collision_sound(
     if !collision_events.is_empty() {
         // This prevents events staying active on the next frame.
         collision_events.clear();
-        commands.spawn(
-            AudioBundle::from_audio(sound.0.clone())
-                // auto-despawn the entity when playback finishes
-                .with_settings(PlaybackSettings::DESPAWN),
-        );
+        commands.spawn(AudioBundle {
+            source: sound.0.clone(),
+            // auto-despawn the entity when playback finishes
+            settings: PlaybackSettings::DESPAWN,
+        });
     }
 }
diff --git a/examples/mobile/src/lib.rs b/examples/mobile/src/lib.rs
index 4ae213156206b..b6f01e55370cc 100644
--- a/examples/mobile/src/lib.rs
+++ b/examples/mobile/src/lib.rs
@@ -153,8 +153,8 @@ fn button_handler(
 }
 
 fn setup_music(asset_server: Res<AssetServer>, mut commands: Commands) {
-    commands.spawn(
-        AudioBundle::from_audio(asset_server.load("sounds/Windless Slopes.ogg"))
-            .with_settings(PlaybackSettings::LOOP),
-    );
+    commands.spawn(AudioBundle {
+        source: asset_server.load("sounds/Windless Slopes.ogg"),
+        settings: PlaybackSettings::LOOP,
+    });
 }

From 21bd1e7fc5cfdcd32c91dd7196b9b11a250e5c8c Mon Sep 17 00:00:00 2001
From: Ida Iyes <identry@protonmail.com>
Date: Fri, 7 Jul 2023 23:01:09 +0300
Subject: [PATCH 15/15] oops forgot doc

---
 crates/bevy_audio/src/lib.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 16d6f03238d6a..11b3699096b39 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/crates/bevy_audio/src/lib.rs
@@ -13,10 +13,10 @@
 //! }
 //!
 //! fn play_background_audio(asset_server: Res<AssetServer>, mut commands: Commands) {
-//!     commands.spawn(
-//!         AudioBundle::from_audio_source(asset_server.load("background_audio.ogg"))
-//!             .with_settings(PlaybackSettings::LOOP)
-//!     );
+//!     commands.spawn(AudioBundle {
+//!         source: asset_server.load("background_audio.ogg"),
+//!         settings: PlaybackSettings::LOOP,
+//!     });
 //! }
 //! ```