Simplify and cut down on features

- Remove separate noise shaping module and options. It does not cater to
  99% users so does not justify the complexity.

- Rename option values to `--dither` to better match what other audio
  libraries use.

- Rework configuration so dithering is an `Option`. This saves a dynamic
  dispatch to a no-op `NoneDitherer` when dithering is set to none.

- Change default ditherer to `tpdf` instead of `tpdf_hp` which should be
  even safer on all DACs. (`tpdf_hp` is the simplest form of FIR noise
  shaping)

- Removed `rect` (`rpdf`) and `sto` ditherers, that are suboptimal to
  the others in all cases. Keeping them around is a bit academic.

Author: roderickvd

playback/src/config.rs

@@ -1,7 +1,6 @@
 use super::player::NormalisationData;
 use crate::convert::i24;
 pub use crate::dither::{Ditherer, DithererBuilder};
-pub use crate::shape_noise::{NoiseShaper, NoiseShaperBuilder};
 
 use std::convert::TryFrom;
 use std::mem;
@@ -136,8 +135,7 @@ pub struct PlayerConfig {
 
     // pass function pointers so they can be lazily instantiated *after* spawning a thread
     // (thereby circumventing Send bounds that they might not satisfy)
-    pub ditherer: DithererBuilder,
-    pub noise_shaper: NoiseShaperBuilder,
+    pub ditherer: Option<DithererBuilder>,
 }
 
 impl Default for PlayerConfig {
@@ -154,8 +152,7 @@ impl Default for PlayerConfig {
             normalisation_knee: 1.0,
             gapless: true,
             passthrough: false,
-            ditherer: <dyn Ditherer>::default(),
-            noise_shaper: <dyn NoiseShaper>::default(),
+            ditherer: Some(<dyn Ditherer>::default()),
         }
     }
 }

playback/src/convert.rs

@@ -1,5 +1,4 @@
-use crate::dither::Ditherer;
-use crate::shape_noise::NoiseShaper;
+use crate::dither::{Ditherer, DithererBuilder};
 use zerocopy::AsBytes;
 
 #[derive(AsBytes, Copy, Clone, Debug)]
@@ -15,28 +14,32 @@ impl i24 {
 }
 
 pub struct Converter {
-    ditherer: Box<dyn Ditherer>,
-    noise_shaper: Box<dyn NoiseShaper>,
+    ditherer: Option<Box<dyn Ditherer>>,
 }
 
 impl Converter {
-    pub fn new(ditherer: Box<dyn Ditherer>, noise_shaper: Box<dyn NoiseShaper>) -> Self {
-        info!(
-            "Converting with ditherer: {} and noise shaper: {}",
-            ditherer, noise_shaper
-        );
-        Self {
-            ditherer,
-            noise_shaper,
+    pub fn new(dither_config: Option<DithererBuilder>) -> Self {
+        if let Some(ref ditherer_builder) = dither_config {
+            let ditherer = (ditherer_builder)();
+            info!("Converting with ditherer: {}", ditherer.name());
+            Self {
+                ditherer: Some(ditherer),
+            }
+        } else {
+            Self { ditherer: None }
         }
     }
 
-    // Denormalize, dither and shape noise
+    // Denormalize and dither
     pub fn scale(&mut self, sample: f32, factor: i64) -> f32 {
         // From the many float to int conversion methods available, match what
         // the reference Vorbis implementation uses: sample * 32768 (for 16 bit)
         let int_value = sample * factor as f32;
-        self.shaped_dither(int_value)
+
+        match self.ditherer {
+            Some(ref mut d) => int_value + d.noise(int_value),
+            None => int_value,
+        }
     }
 
     // Special case for samples packed in a word of greater bit depth (e.g.
@@ -59,11 +62,6 @@ impl Converter {
         int_value
     }
 
-    fn shaped_dither(&mut self, sample: f32) -> f32 {
-        let noise = self.ditherer.noise(sample);
-        self.noise_shaper.shape(sample, noise)
-    }
-
     // https://doc.rust-lang.org/nomicon/casts.html: casting float to integer
     // rounds towards zero, then saturates. Ideally halves should round to even to
     // prevent any bias, but since it is extremely unlikely that a float has

playback/src/dither.rs

@@ -5,30 +5,27 @@ use std::fmt;
 const NUM_CHANNELS: usize = 2;
 
 // Dithering lowers digital-to-analog conversion ("requantization") error,
-// lowering distortion and replacing it with a constant, fixed noise level,
-// which is more pleasant to the ear than the distortion. Doing so can with
-// a noise-shaped dither can increase the dynamic range of 96 dB CD-quality
-// audio to a perceived 120 dB.
+// linearizing output, lowering distortion and replacing it with a constant,
+// fixed noise level, which is more pleasant to the ear than the distortion.
 //
-// Guidance: experts can configure many different configurations of ditherers
-// and noise shapers. For the rest of us:
+// Guidance:
 //
-//  * Don't dither or shape noise on S32 or F32. On F32 it's not supported
-//    anyway (there are no rounding errors due to integer conversions) and on
-//    S32 the noise level is so far down that it is simply inaudible.
-//
-//  * Generally use high pass dithering (hp) without noise shaping. Depending
-//    on personal preference you may use Gaussian dithering (gauss) instead;
+//  * On S24, S24_3 and S24, the default is to use triangular dithering.
+//    Depending on personal preference you may use Gaussian dithering instead;
 //    it's not as good objectively, but it may be preferred subjectively if
-//    you are looking for a more "analog" sound.
+//    you are looking for a more "analog" sound akin to tape hiss.
 //
-//  * On power-constrained hardware, use the fraction saving noise shaper
-//    instead of dithering. Performance-wise, this is not necessary even on a
-//    Raspberry Pi Zero, but if you're on batteries...
+//  * Advanced users who know that they have a DAC without noise shaping have
+//    a third option: high-passed dithering, which is like triangular dithering
+//    except that it moves dithering noise up in frequency where it is less
+//    audible. Note: 99% of DACs are of delta-sigma design with noise shaping,
+//    so unless you have a multibit / R2R DAC, or otherwise know what you are
+//    doing, this is not for you.
 //
-// Implementation note: we save the handle to ThreadRng so it doesn't require
-// a lookup on each call (which is on each sample!). This is ~2.5x as fast.
-// Downside is that it is not Send so we cannot move it around player threads.
+//  * Don't dither or shape noise on S32 or F32. On F32 it's not supported
+//    anyway (there are no integer conversions and so no rounding errors) and
+//    on S32 the noise level is so far down that it is simply inaudible even
+//    after volume normalisation and control.
 //
 pub trait Ditherer {
     fn new() -> Self
@@ -40,7 +37,7 @@ pub trait Ditherer {
 
 impl dyn Ditherer {
     pub fn default() -> fn() -> Box<Self> {
-        mk_ditherer::<HighPassDitherer>
+        mk_ditherer::<TriangularDitherer>
     }
 }
 
@@ -50,83 +47,11 @@ impl fmt::Display for dyn Ditherer {
     }
 }
 
-pub struct NoDithering {}
-impl Ditherer for NoDithering {
-    fn new() -> Self {
-        Self {}
-    }
-
-    fn name(&self) -> &'static str {
-        "None"
-    }
-
-    fn noise(&mut self, _sample: f32) -> f32 {
-        0.0
-    }
-}
-
-// "True" white noise (refer to Gaussian for analog source hiss). Advantages:
-// least CPU-intensive dither, lowest signal-to-noise ratio. Disadvantage:
-// highest perceived loudness, suffers from intermodulation distortion unless
-// you are using this for subtractive dithering, which you most likely are not,
-// and is not supported by any of the librespot backends. Guidance: use some
-// other ditherer unless you know what you're doing.
-pub struct RectangularDitherer {
-    cached_rng: ThreadRng,
-    distribution: Uniform<f32>,
-}
-
-impl Ditherer for RectangularDitherer {
-    fn new() -> Self {
-        Self {
-            cached_rng: rand::thread_rng(),
-            // 1 LSB peak-to-peak needed to linearize the response:
-            distribution: Uniform::new_inclusive(-0.5, 0.5),
-        }
-    }
-
-    fn name(&self) -> &'static str {
-        "Rectangular"
-    }
-
-    fn noise(&mut self, _sample: f32) -> f32 {
-        self.distribution.sample(&mut self.cached_rng)
-    }
-}
-
-// Like Rectangular, but with lower error and OK to use for the default case
-// of non-subtractive dithering such as to the librespot backends.
-pub struct StochasticDitherer {
-    cached_rng: ThreadRng,
-    distribution: Uniform<f32>,
-}
-
-impl Ditherer for StochasticDitherer {
-    fn new() -> Self {
-        Self {
-            cached_rng: rand::thread_rng(),
-            distribution: Uniform::new(0.0, 1.0),
-        }
-    }
-
-    fn name(&self) -> &'static str {
-        "Stochastic"
-    }
-
-    fn noise(&mut self, sample: f32) -> f32 {
-        let fract = sample.fract();
-        if self.distribution.sample(&mut self.cached_rng) <= fract {
-            1.0 - fract
-        } else {
-            fract * -1.0
-        }
-    }
-}
+// Implementation note: we save the handle to ThreadRng so it doesn't require
+// a lookup on each call (which is on each sample!). This is ~2.5x as fast.
+// Downside is that it is not Send so we cannot move it around player threads.
+//
 
-// Higher level than Rectangular. Advantages: superior to Rectangular as it
-// does not suffer from modulation noise effects. Disadvantage: more CPU-
-// expensive. Guidance: all-round recommendation to reduce quantization noise,
-// even on 24-bit output.
 pub struct TriangularDitherer {
     cached_rng: ThreadRng,
     distribution: Triangular<f32>,
@@ -150,9 +75,6 @@ impl Ditherer for TriangularDitherer {
     }
 }
 
-// Like Triangular, but with higher noise power and more like phono hiss.
-// Guidance: theoretically less optimal, but an alternative to Triangular
-// if a more analog sound is sought after.
 pub struct GaussianDitherer {
     cached_rng: ThreadRng,
     distribution: Normal<f32>,
@@ -176,10 +98,6 @@ impl Ditherer for GaussianDitherer {
     }
 }
 
-// Like Triangular, but with a high-pass filter. Advantages: comparably less
-// perceptible noise, less CPU-intensive. Disadvantage: this acts like a FIR
-// filter with weights [1.0, -1.0], and is superseded by noise shapers.
-// Guidance: better than Triangular if not doing other noise shaping.
 pub struct HighPassDitherer {
     active_channel: usize,
     previous_noises: [f32; NUM_CHANNELS],
@@ -198,7 +116,7 @@ impl Ditherer for HighPassDitherer {
     }
 
     fn name(&self) -> &'static str {
-        "High Pass"
+        "Triangular, High Passed"
     }
 
     fn noise(&mut self, _sample: f32) -> f32 {
@@ -216,21 +134,11 @@ pub fn mk_ditherer<D: Ditherer + 'static>() -> Box<dyn Ditherer> {
 
 pub type DithererBuilder = fn() -> Box<dyn Ditherer>;
 
-pub const DITHERERS: &[(&str, DithererBuilder)] = &[
-    ("none", mk_ditherer::<NoDithering>),
-    ("rect", mk_ditherer::<RectangularDitherer>),
-    ("sto", mk_ditherer::<StochasticDitherer>),
-    ("tri", mk_ditherer::<TriangularDitherer>),
-    ("gauss", mk_ditherer::<GaussianDitherer>),
-    ("hp", mk_ditherer::<HighPassDitherer>),
-];
-
-pub fn find_ditherer(name: Option<String>) -> Option<fn() -> Box<dyn Ditherer>> {
-    match name {
-        Some(name) => DITHERERS
-            .iter()
-            .find(|ditherer| name == ditherer.0)
-            .map(|ditherer| ditherer.1),
-        _ => Some(mk_ditherer::<NoDithering>),
+pub fn find_ditherer(name: Option<String>) -> Option<DithererBuilder> {
+    match name.as_deref() {
+        Some("tpdf") => Some(mk_ditherer::<TriangularDitherer>),
+        Some("gpdf") => Some(mk_ditherer::<GaussianDitherer>),
+        Some("tpdf_hp") => Some(mk_ditherer::<HighPassDitherer>),
+        _ => None,
     }
 }

playback/src/lib.rs

@@ -12,4 +12,3 @@ mod decoder;
 pub mod dither;
 pub mod mixer;
 pub mod player;
-pub mod shape_noise;

playback/src/player.rs

@@ -299,7 +299,7 @@ impl Player {
         let handle = thread::spawn(move || {
             debug!("new Player[{}]", session.session_id());
 
-            let converter = Converter::new((config.ditherer)(), (config.noise_shaper)());
+            let converter = Converter::new(config.ditherer);
 
             let internal = PlayerInternal {
                 session,