Support decibels in bevy_audio::Volume

crates/bevy_audio/src/audio.rs

@@ -74,7 +74,7 @@ impl PlaybackSettings {
     /// added again.
     pub const ONCE: PlaybackSettings = PlaybackSettings {
         mode: PlaybackMode::Once,
-        volume: Volume(1.0),
+        volume: Volume::Linear(1.0),
         speed: 1.0,
         paused: false,
         muted: false,

crates/bevy_audio/src/audio_output.rs

@@ -1,6 +1,6 @@
 use crate::{
     AudioPlayer, Decodable, DefaultSpatialScale, GlobalVolume, PlaybackMode, PlaybackSettings,
-    SpatialAudioSink, SpatialListener,
+    SpatialAudioSink, SpatialListener, Volume,
 };
 use bevy_asset::{Asset, Assets};
 use bevy_ecs::{prelude::*, system::SystemParam};
@@ -170,7 +170,9 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
             }
 
             sink.set_speed(settings.speed);
-            sink.set_volume(settings.volume.0 * global_volume.volume.0);
+            sink.set_volume(Volume::Linear(
+                settings.volume.to_linear() * global_volume.volume.to_linear(),
+            ));
 
             if settings.paused {
                 sink.pause();
@@ -210,7 +212,9 @@ pub(crate) fn play_queued_audio_system<Source: Asset + Decodable>(
             }
 
             sink.set_speed(settings.speed);
-            sink.set_volume(settings.volume.0 * global_volume.volume.0);
+            sink.set_volume(Volume::Linear(
+                settings.volume.to_linear() * global_volume.volume.to_linear(),
+            ));
 
             if settings.paused {
                 sink.pause();

crates/bevy_audio/src/sinks.rs

@@ -3,37 +3,26 @@ use bevy_math::Vec3;
 use bevy_transform::prelude::Transform;
 use rodio::{Sink, SpatialSink};
 
+use crate::Volume;
+
 /// Common interactions with an audio sink.
 pub trait AudioSinkPlayback {
-    /// Gets the volume of the sound.
-    ///
-    /// The value `1.0` is the "normal" volume (unfiltered input). Any value
-    /// other than `1.0` will multiply each sample by this value.
+    /// Gets the volume of the sound as a [`Volume`].
     ///
     /// If the sink is muted, this returns the managed volume rather than the
-    /// sink's actual volume. This allows you to use the volume as if the sink
-    /// were not muted, because a muted sink has a volume of 0.
-    fn volume(&self) -> f32;
+    /// sink's actual volume. This allows you to use the returned volume as if
+    /// the sink were not muted, because a muted sink has a physical volume of
+    /// 0.
+    fn volume(&self) -> Volume;
 
-    /// Changes the volume of the sound.
-    ///
-    /// The value `1.0` is the "normal" volume (unfiltered input). Any value other than `1.0`
-    /// will multiply each sample by this value.
+    /// Changes the volume of the sound to the given [`Volume`].
     ///
     /// If the sink is muted, changing the volume won't unmute it, i.e. the
-    /// sink's volume will remain at `0.0`. However, the sink will remember the
-    /// volume change and it will be used when [`unmute`](Self::unmute) is
-    /// called. This allows you to control the volume even when the sink is
-    /// muted.
-    ///
-    /// # Note on Audio Volume
-    ///
-    /// An increase of 10 decibels (dB) roughly corresponds to the perceived volume doubling in intensity.
-    /// As this function scales not the volume but the amplitude, a conversion might be necessary.
-    /// For example, to halve the perceived volume you need to decrease the volume by 10 dB.
-    /// This corresponds to 20log(x) = -10dB, solving x = 10^(-10/20) = 0.316.
-    /// Multiply the current volume by 0.316 to halve the perceived volume.
-    fn set_volume(&mut self, volume: f32);
+    /// sink's volume will remain "off" / "muted". However, the sink will
+    /// remember the volume change and it will be used when
+    /// [`unmute`](Self::unmute) is called. This allows you to control the
+    /// volume even when the sink is muted.
+    fn set_volume(&mut self, volume: Volume);
 
     /// Gets the speed of the sound.
     ///
@@ -132,7 +121,7 @@ pub struct AudioSink {
     /// If the sink is muted, this is `Some(volume)` where `volume` is the
     /// user's intended volume setting, even if the underlying sink's volume is
     /// 0.
-    pub(crate) managed_volume: Option<f32>,
+    pub(crate) managed_volume: Option<Volume>,
 }
 
 impl AudioSink {
@@ -146,15 +135,16 @@ impl AudioSink {
 }
 
 impl AudioSinkPlayback for AudioSink {
-    fn volume(&self) -> f32 {
-        self.managed_volume.unwrap_or_else(|| self.sink.volume())
+    fn volume(&self) -> Volume {
+        self.managed_volume
+            .unwrap_or_else(|| Volume::Linear(self.sink.volume()))
     }
 
-    fn set_volume(&mut self, volume: f32) {
+    fn set_volume(&mut self, volume: Volume) {
         if self.is_muted() {
             self.managed_volume = Some(volume);
         } else {
-            self.sink.set_volume(volume);
+            self.sink.set_volume(volume.to_linear());
         }
     }
 
@@ -197,7 +187,7 @@ impl AudioSinkPlayback for AudioSink {
 
     fn unmute(&mut self) {
         if let Some(volume) = self.managed_volume.take() {
-            self.sink.set_volume(volume);
+            self.sink.set_volume(volume.to_linear());
         }
     }
 }
@@ -227,7 +217,7 @@ pub struct SpatialAudioSink {
     /// If the sink is muted, this is `Some(volume)` where `volume` is the
     /// user's intended volume setting, even if the underlying sink's volume is
     /// 0.
-    pub(crate) managed_volume: Option<f32>,
+    pub(crate) managed_volume: Option<Volume>,
 }
 
 impl SpatialAudioSink {
@@ -241,15 +231,16 @@ impl SpatialAudioSink {
 }
 
 impl AudioSinkPlayback for SpatialAudioSink {
-    fn volume(&self) -> f32 {
-        self.managed_volume.unwrap_or_else(|| self.sink.volume())
+    fn volume(&self) -> Volume {
+        self.managed_volume
+            .unwrap_or_else(|| Volume::Linear(self.sink.volume()))
     }
 
-    fn set_volume(&mut self, volume: f32) {
+    fn set_volume(&mut self, volume: Volume) {
         if self.is_muted() {
             self.managed_volume = Some(volume);
         } else {
-            self.sink.set_volume(volume);
+            self.sink.set_volume(volume.to_linear());
         }
     }
 
@@ -292,7 +283,7 @@ impl AudioSinkPlayback for SpatialAudioSink {
 
     fn unmute(&mut self) {
         if let Some(volume) = self.managed_volume.take() {
-            self.sink.set_volume(volume);
+            self.sink.set_volume(volume.to_linear());
         }
     }
 }
@@ -326,11 +317,11 @@ mod tests {
 
     fn test_audio_sink_playback<T: AudioSinkPlayback>(mut audio_sink: T) {
         // Test volume
-        assert_eq!(audio_sink.volume(), 1.0); // default volume
-        audio_sink.set_volume(0.5);
-        assert_eq!(audio_sink.volume(), 0.5);
-        audio_sink.set_volume(1.0);
-        assert_eq!(audio_sink.volume(), 1.0);
+        assert_eq!(audio_sink.volume(), Volume::Linear(1.0)); // default volume
+        audio_sink.set_volume(Volume::Linear(0.5));
+        assert_eq!(audio_sink.volume(), Volume::Linear(0.5));
+        audio_sink.set_volume(Volume::Linear(1.0));
+        assert_eq!(audio_sink.volume(), Volume::Linear(1.0));
 
         // Test speed
         assert_eq!(audio_sink.speed(), 1.0); // default speed
@@ -361,11 +352,11 @@ mod tests {
         assert!(!audio_sink.is_muted());
 
         // Test volume with mute
-        audio_sink.set_volume(0.5);
+        audio_sink.set_volume(Volume::Linear(0.5));
         audio_sink.mute();
-        assert_eq!(audio_sink.volume(), 0.5); // returns managed volume even though sink volume is 0
+        assert_eq!(audio_sink.volume(), Volume::Linear(0.5)); // returns managed volume even though sink volume is 0
         audio_sink.unmute();
-        assert_eq!(audio_sink.volume(), 0.5); // managed volume is restored
+        assert_eq!(audio_sink.volume(), Volume::Linear(0.5)); // managed volume is restored
 
         // Test toggle mute
         audio_sink.toggle_mute();