Support decibels in bevy_audio::Volume (#17605)

# Objective

- Allow users to configure volume using decibels by changing the
`Volume` type from newtyping an `f32` to an enum with `Linear` and
`Decibels` variants.
- Fixes #9507.
- Alternative reworked version of closed #9582.

## Solution

Compared to #9582, this PR has
the following main differences:

1. It uses the term "linear scale" instead of "amplitude" per
https://github.com/bevyengine/bevy/pull/9582/files#r1513529491.
2. Supports `ops` for doing `Volume` arithmetic. Can add two volumes,
e.g. to increase/decrease the current volume. Can multiply two volumes,
e.g. to get the “effective” volume of an audio source considering global
volume.

[requested and blessed on Discord]:
https://discord.com/channels/691052431525675048/749430447326625812/1318272597003341867

## Testing

- Ran `cargo run --example soundtrack`.
- Ran `cargo run --example audio_control`.
- Ran `cargo run --example spatial_audio_2d`.
- Ran `cargo run --example spatial_audio_3d`.
- Ran `cargo run --example pitch`.
- Ran `cargo run --example decodable`.
- Ran `cargo run --example audio`.

---

## Migration Guide

Audio volume can now be configured using decibel values, as well as
using linear scale values. To enable this, some types and functions in
`bevy_audio` have changed.

- `Volume` is now an enum with `Linear` and `Decibels` variants.

Before:

```rust
let v = Volume(1.0);
```

After:

```rust
let volume = Volume::Linear(1.0);
let volume = Volume::Decibels(0.0); // or now you can deal with decibels if you prefer
```

- `Volume::ZERO` has been renamed to the more semantically correct
`Volume::SILENT` because `Volume` now supports decibels and "zero
volume" in decibels actually means "normal volume".
- The `AudioSinkPlayback` trait's volume-related methods now deal with
`Volume` types rather than `f32`s. `AudioSinkPlayback::volume()` now
returns a `Volume` rather than an `f32`. `AudioSinkPlayback::set_volume`
now receives a `Volume` rather than an `f32`. This affects the
`AudioSink` and `SpatialAudioSink` implementations of the trait. The
previous `f32` values are equivalent to the volume converted to linear
scale so the `Volume:: Linear` variant should be used to migrate between
`f32`s and `Volume`.
- The `GlobalVolume::new` function now receives a `Volume` instead of an
`f32`.

---------

Co-authored-by: Zachary Harrold <[email protected]>

Author: mgi388

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

@@ -170,7 +170,7 @@ 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(settings.volume * global_volume.volume);
 
             if settings.paused {
                 sink.pause();
@@ -210,7 +210,7 @@ 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(settings.volume * global_volume.volume);
 
             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();