feat: add audio dithering support #794

roderickvd · 2025-09-12T21:05:58Z

Builds on our noise generators to add four dithering algorithms:

TPDF (Triangular PDF) - Optimal decorrelation (default)
RPDF (Rectangular PDF) - Lower noise floor, worse decorrelation
GPDF (Gaussian PDF) - Higher noise floor, analog characteristics
HighPass - Blue noise to reduce low-frequency artifacts

Gated by new dither feature flag, that's enabled by default.

API

use rodio::source::{dither, DitherAlgorithm};
use rodio::BitDepth;

let source = SineWave::new(440.0);
let dithered = dither(source, BitDepth::new(16).unwrap(), DitherAlgorithm::TPDF);

Parent branch

This is branched off of #786 which introduces Source::bits_per_sample(), because you'll typically want to dither down to:

let output_bits = config.bits_per_sample();  // in cpal master: https://github.com/RustAudio/cpal/pull/1008
let target_bits = source_bits.map_or(output_bits, |src_bits| src_bits.min(output_bits));

I'll mark this PR for review when that PR is merged.

Copilot

Pull Request Overview

This PR introduces audio dithering support to Rodio with four dithering algorithms, while also implementing significant infrastructure improvements across decoders and sources.

Key Changes:

Audio dithering feature: Adds TPDF, RPDF, GPDF, and HighPass dithering algorithms for quantization noise management
BitDepth type addition: New type for tracking audio bit depth throughout the audio pipeline
Decoder improvements: Enhanced seeking, error handling, and configuration for WAV and Vorbis decoders
Source trait expansion: Added bits_per_sample() method and improved seeking error handling

Reviewed Changes

Copilot reviewed 89 out of 91 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/source/dither.rs	New dithering implementation with four algorithms (TPDF, RPDF, GPDF, HighPass)
src/common.rs	Adds BitDepth type and updates ChannelCount/SampleRate handling
src/decoder/wav.rs	Major WAV decoder improvements with better seeking and configuration
src/decoder/vorbis.rs	Enhanced Vorbis decoder with granule-based seeking and duration scanning
src/source/mod.rs	Expanded Source trait with bits_per_sample() method and improved SeekError variants
tests/	Updated test files to use Path-based decoder APIs instead of File objects

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/source/dither.rs

Copilot · 2025-09-12T21:07:12Z

src/decoder/vorbis.rs

+        // Try to find a granule from this position (limited packet scan during binary search)
+        match find_granule_from_position(data, mid, Some(50)) {


[nitpick] The magic number 50 for packet limit should be defined as a named constant to improve code readability and maintainability.

Copilot · 2025-09-12T21:07:13Z

src/decoder/wav.rs

-        };
+        // len is number of samples, not bytes, so use samples_to_duration
+        // Note: hound's len() returns total samples across all channels
+        let samples_per_channel = len / (channels as u64);


Division by channels as u64 could cause integer truncation issues. The conversion from u16 to u64 for channels should be explicit and the division should handle potential remainders properly.

Suggested change

let samples_per_channel = len / (channels as u64);

let channels_u64 = channels as u64;

if len % channels_u64 != 0 {

eprintln!(

"Warning: total number of samples ({}) is not evenly divisible by number of channels ({}). Truncating to {} samples per channel.",

len, channels, len / channels_u64

);

}

let samples_per_channel = len / channels_u64;

src/source/mod.rs

yara-blue · 2025-09-13T10:15:04Z

Parent branch

This is branched off of #786 which introduces Source::bits_per_sample(), because you'll typically want to dither down to:

😅 😅 For a minute or two I thought you introduced another ~6k PR.

Btw lets add a new rule/convention to keep PR's under 1500 lines. I'll hold myself to that for rewriting the entire audio pipeline.

roderickvd · 2025-09-26T21:04:52Z

Rebased on master.

yara-blue · 2025-09-27T10:32:02Z

src/source/dither.rs

+
+/// Dither algorithm selection - chooses the probability density function (PDF).
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub enum Algorithm {


I've spend some time trying to learn about these. I find it quite hard to find info on these. Would love to know (out of intrest, this is not blocking the PR in any way) how you got to these docs. Is it something you've learned over the years?

I think you will love reading Wannamaker's PhD seminal dissertation on this. I believe this is a shorter IEEE extract of it, but it's been years since I read all these. Yes, I actually dove into it like four years ago reading these, as well as source code of GStreamer, PortAudio and others.

Beyond high-passed dither there are more elaborate noise-shaping techniques that I may propose in a later PR. Emphasis on may.

yara-blue · 2025-09-27T10:34:47Z

src/source/dither.rs

+        // LSB amplitude for signed audio: 1.0 / (2^(bits-1))
+        // This represents the amplitude of one quantization level
+        let lsb_amplitude = if target_bits.get() >= Sample::MANTISSA_DIGITS {
+            // For bit depths at or beyond the floating point precision limit,


Is the idea to not do the LSB amplitude calc. as a performance improvement? Or do we need to skip it because we get artifacting otherwise?

My gut tells me that the extra branch from the if will be more expensive then the calculation.

This branch is in the constructor, not the hot path.

The point is that some sources may report a bit depth of 32 that users would want to dither to for requantization (remember, this would be great to use with the Source::bits_per_sample() that #786 introduced). Because our audio pipeline in the end will be constrained to 24 bits, we then still want to select the LSB and dither before truncating.

yara-blue · 2025-09-27T10:47:17Z

src/source/dither.rs

+
+/// Dithering interface delegating to the supported dithering algorithms.
+#[derive(Clone)]
+pub enum Dither<I, R = SmallRng>


How about we merge this and the DitherImpl struct? That would get rid of the match in channels, sample_rate etc.

How would that look like while still supporting the various PDFs and so, different noise generators? I want to prevent branching in the iterator. This delegation is faster, particularly when the algorithm is selected at compile time.

This delegation is faster, particularly when the algorithm is selected at compile time.

Thats surprising since there is a match in the iterator. That will branch.

This delegation is faster

Do we have a benchmark to back this up?

This delegation is faster, particularly when the algorithm is selected at compile time.

Thats surprising since there is a match in the iterator. That will branch.

match creates jump tables which are O(1). if branches are O(n).

match creates jump tables which are O(1). if branches are O(n).

On a modern optimizing compiler this is no longer true. But its a moot point as the number of comparisons is not at all what can kill performance with branches.

Branches prevent in-lining and a ton of other essential compiler optimizations. Further more if the CPU's branch predictor makes an incorrect prediction the entire pipeline needs to be flushed.

For a for loop (basically a loop { if i > num break else do things} }this is not an issue since the branch predictor can figure out that if statement will usually be true. That means only once we go into the else we pay the price.

But as always compilers and CPU's have become far to complex for anyone to reason about performance in detail. So optimize for readability and benchmark after.

yara-blue

I think we can make source/dither smaller by merging the Dither and DitherImpl structs. Let me know what you think.

No comments on the rest, looks perfect.

roderickvd · 2025-09-27T10:57:22Z

I think we can make source/dither smaller by merging the Dither and DitherImpl structs. Let me know what you think.

Thanks for the review - please check out my question about that. I'm not sure.

yara-blue · 2025-09-27T11:10:40Z

Thanks for the review - please check out my question about that. I'm not sure.

I'll give a try and then we can compare 👍

yara-blue · 2025-09-27T11:35:44Z

I pushed a messy idea/prototype (we got a builder again). This gets rid of the branching and should end up a lot shorter. It does make it impossible to change dithering method on the fly but I dont think you would want to do that right? Feel free to revert if we decide not to go this route.

roderickvd · 2025-09-27T12:06:51Z

I do want the ergonomics of sound.dither().amplify(). Sure, we could have Source::dither() select DitherBuilder::tpdf() by default. But I think builders make most sense when they are "point of origin" like with the decoder or microphone. I do agree that this proposal shaves off a lot of code and should be even faster.

I don't immediately have a strong feeling either way. What do you say looking at that source-and-effect chain?

yara-blue · 2025-09-27T13:11:15Z

I don't immediately have a strong feeling either way. What do you say looking at that source-and-effect chain?

New idea I'll have to work it out. I'll send another very ugly commit your way.

yara-blue · 2025-09-27T13:51:41Z

Curious what you think, I quite like it. No branching on algorithm shorter code and no builder 🎉

roderickvd · 2025-09-27T16:50:26Z

Your proposal is clever, however cannot select a PDF at runtime. There sure would be reasons why someone would want that, like in a dialog or on the command line to configure an application’s behavior.

I benchmarked the branching and monomorphization approaches with divan and the performance differences are negligible: 0.01ns delta on my Apple M3. I’m gonna propose a middle ground: remove the DitherInner enum and replace it with a NoiseGenerator enum that dispatches. It does save a lot of code.

Also replace f32 with Sample where appropriate for consistency

…elvet density to NonZero

- Replace trait-based DitherAlgorithm with runtime enum Algorithm - Implement Dither as a single struct supporting all algorithms - Add NoiseGenerator enum for dynamic noise generation - Expose new dither() function using Algorithm and BitDepth - Update docs and tests for new API

yara-blue · 2025-09-27T20:14:35Z

I benchmarked the branching and monomorphization approaches with divan and the performance differences are negligible: 0.01ns delta on my Apple M3.

The modern optimizing compiler, a true miracle.

Your proposal is clever, however cannot select a PDF at runtime. There sure would be reasons why someone would want that, like in a dialog or on the command line to configure an application’s behavior.

👍

yara-blue · 2025-09-27T20:20:36Z

src/source/mod.rs

+/// and when converting between bit depths. Apply at the target output bit depth.
+#[cfg(feature = "dither")]
+#[cfg_attr(docsrs, doc(cfg(feature = "dither")))]
+pub fn dither<I>(input: I, target_bits: BitDepth, algorithm: DitherAlgorithm) -> Dither<I>


replace this with a default implementation on source? So you can do sine().dither().amplify().pausable() etc.

otherwise good to merge btw

Huh that must have fallen off somewhere! Good catch, will re-add it and merge when done. Thanks.

roderickvd · 2025-09-28T07:19:30Z

I benchmarked the branching and monomorphization approaches with divan and the performance differences are negligible: 0.01ns delta on my Apple M3.

The modern optimizing compiler, a true miracle.

I forgot to say "0.01ns" per sample, but yes.

Besides the compiler there's speculative branch prediction in CPUs as well of course. You're right it's nigh impossible reason about it, and then it differs per architecture too. Though lately I'm making more effort to try and feed it code that at least should be easy to digest in the hot path.

roderickvd requested review from Copilot and yara-blue September 12, 2025 21:05

roderickvd added the enhancement label Sep 12, 2025

roderickvd changed the base branch from feat/comprehensive-seeking-and-bit-depth to master September 12, 2025 21:06

Copilot AI reviewed Sep 12, 2025

View reviewed changes

roderickvd force-pushed the feat/dither branch 2 times, most recently from cd1b454 to 01714ce Compare September 17, 2025 20:55

roderickvd marked this pull request as ready for review September 17, 2025 21:50

yara-blue assigned yara-blue and unassigned yara-blue Sep 20, 2025

roderickvd force-pushed the feat/dither branch 2 times, most recently from 8268179 to 14e63ca Compare September 26, 2025 21:03

yara-blue reviewed Sep 27, 2025

View reviewed changes

yara-blue requested changes Sep 27, 2025

View reviewed changes

roderickvd and others added 5 commits September 27, 2025 22:08

feat: add audio dithering support with dither source and feature flag

a9240e0

fix: handle LSB amplitude for high bit depths in dither source

923d24f

refactor: Velvet noise to use usize for density and positions

f777244

Also replace f32 with Sample where appropriate for consistency

refactor: rebase on master

eccbdbf

messy example of builder API approach

d4be9df

dvdsk and others added 4 commits September 27, 2025 22:08

nice and simple :)

f3b9331

refactor: remove explicit SmallRng from noise type impl blocks

f54393d

refactor: remove SeedableRng bound from noise generators and change V…

629a1e3

…elvet density to NonZero

roderickvd force-pushed the feat/dither branch from e157735 to 8293813 Compare September 27, 2025 20:08

roderickvd requested a review from yara-blue September 27, 2025 20:12

yara-blue reviewed Sep 27, 2025

View reviewed changes

roderickvd added 2 commits September 28, 2025 00:10

refactor: move dither to Source trait

9a9e262

docs: clarify dither function as Source::dither

3d72cdf

roderickvd merged commit d89514d into master Sep 27, 2025
9 checks passed

roderickvd deleted the feat/dither branch September 27, 2025 22:16

		// Try to find a granule from this position (limited packet scan during binary search)
		match find_granule_from_position(data, mid, Some(50)) {

-        let samples_per_channel = len / (channels as u64);
+        let channels_u64 = channels as u64;
+        if len % channels_u64 != 0 {
+            eprintln!(
+                "Warning: total number of samples ({}) is not evenly divisible by number of channels ({}). Truncating to {} samples per channel.",
+                len, channels, len / channels_u64
+            );
+        }
+        let samples_per_channel = len / channels_u64;

feat: add audio dithering support #794

feat: add audio dithering support #794

Conversation

roderickvd commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API

Parent branch

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yara-blue commented Sep 13, 2025

Parent branch

Uh oh!

roderickvd commented Sep 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yara-blue left a comment

Choose a reason for hiding this comment

Uh oh!

roderickvd commented Sep 27, 2025

Uh oh!

yara-blue commented Sep 27, 2025

Uh oh!

yara-blue commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roderickvd commented Sep 27, 2025

Uh oh!

yara-blue commented Sep 27, 2025

Uh oh!

yara-blue commented Sep 27, 2025

Uh oh!

roderickvd commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yara-blue commented Sep 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

roderickvd commented Sep 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

roderickvd commented Sep 12, 2025 •

edited

Loading

yara-blue commented Sep 27, 2025 •

edited

Loading

roderickvd commented Sep 27, 2025 •

edited

Loading