Allow re-use of an existing audio sink.

[AxiomaticSemantics]

Objective

Some users may benefit from avoiding archetype moves on entities and re-use of a sink on an entity, this also has some side benefits such as fine-grained control and inhibition of playing a current track if the current track is deemed to be a higher priority.

• Allow re-use of an audio sink which has been added to an entity using the PlaybackSettings::ONCE policy,

Solution

• Make the required info public

---

Changelog

• Allow reuse of AudioSink and SpatialAudioSink.

Migration Guide

[alice-i-cecile]

Doc strings for these fields now that they're pub.

[AxiomaticSemantics]

Ya sorry this should be draft still

[alice-i-cecile]

Could you demonstrate how to take advantage of this for users? An example would be ideal, but a doc test would work too.

[AxiomaticSemantics]

Could you demonstrate how to take advantage of this for users? An example would be ideal, but a doc test would work too.

There is some work that would need to be done, for my use it's a bit messy yet. I'm basically reproducing a subset of the normal playback done in bevy_audio itself, so I'd like to bring support for what I'm doing into bevy_audio.
I'm planning on adding the required bundles when I create my entity vs how I have it here. I don't like the way it's accessed so I'd like to have some of the audio people guide how it's handled, this is my first stab at it.

  pub(crate) fn unit_audio(
      mut commands: Commands,
      global_volume: Res<GlobalVolume>,
      audio_sources: Res<Assets<AudioSource>>,
      tracks: Res<AudioAssets>,
      mut unit_q: Query<
          (
              Entity,
              &mut AudioActions,
              Option<&Handle<AudioSource>>,
              Option<&mut AudioSink>,
              Option<&PlaybackSettings>,
          ),
          (With<Unit>, Changed<AudioActions>),
      >,      
  ) {
      for (entity, mut audio_actions, source, mut sink, settings) in &mut unit_q {
          for action in audio_actions.iter() {
              if let Some(_) = source {
                  let source = tracks.foreground_tracks[action.as_str()].clone_weak();
                  let Some(audio_source) = audio_sources.get(source) else {
                      continue;
                  };
          
                  {
                      let sink = sink.as_mut().unwrap();
                      let settings = settings.as_ref().unwrap();
                      sink.set_speed(settings.speed);
                      sink.set_volume(settings.volume.get() * global_volume.volume.get());
  
                      if settings.paused {
                          sink.pause();
                      }
                  }
  
                  sink.as_ref().unwrap().sink.append(audio_source.decoder());
              } else {
                  commands.entity(entity).insert(AudioBundle {
                      source: tracks.foreground_tracks[action.as_str()].clone_weak(),
                      settings: PlaybackSettings::ONCE,
                  });
              }
          }
          audio_actions.clear();
      }
  }

[MiniaczQ]

That's a pretty rough interface :/

maybe a very simple example to get people started
and then direct them to docs as much as possible?

[AxiomaticSemantics]

That's a pretty rough interface :/

maybe a very simple example to get people started and then direct them to docs as much as possible?

The above was just to show my current use-case to Alice, planning on adding support directly into bevy_audio once there has been a discussion about it. That example will not be included for any public consumption, more of a POC.