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

dvdsk · 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.

…ion for all decoders Major decoder enhancements implementing universal try_seek() support, bit depth detection, and changing decoder selection to prioritize alternative decoders over Symphonia. Key changes: - Universal seeking: All decoders implement try_seek() with SeekMode configuration - Bit depth detection: Added Source::bits_per_sample() for lossless formats - Decoder precedence: Alternative decoders now tried before Symphonia decoders - Enhanced DecoderBuilder: Added scan_duration, total_duration, seek_mode settings - Critical fix: Resolved zero span length issue in Symphonia Ogg Vorbis decoder - Performance: Optimized Vorbis, FLAC, and WAV decoder implementations BREAKING CHANGES: - SeekError::NotSupported renamed to SeekError::SeekingNotSupported - WavDecoder no longer implements ExactSizeIterator - Alternative decoders now take precedence when multiple format features enabled - DecoderBuilder::with_coarse_seek deprecated for with_seek_mode Closes: - #190 - #775

Without this, minimp3 would incorrectly accept WAV files as MP3 when both `minimp3` and Symphonia's `wav` features are enabled.

Fixes #141

- Improve clarity and conciseness of doc comments for all decoders - Remove redundant and overly verbose explanations - Add missing details to trait and method docs - Update examples to use consistent file paths and types - Move Settings struct visibility to crate-internal - Refactor Path/PathBuf decoder constructors for optimal hinting - Standardize iterator and trait method documentation across formats - Remove misleading or outdated implementation notes - Fix Zero source bits_per_sample to return None - Update seek test attributes for feature consistency

- Introduce BitDepth as a newtype for non-zero u32 - Update Source trait and all implementations to use Option<BitDepth> - Update decoders, sources, and tests to use BitDepth instead of u32 for bit depth - Replace NonZero usage for sample rate and channel count with SampleRate and ChannelCount types where appropriate - Update documentation and examples to reflect new types fix: change bits_per_sample to return Option<BitDepth>

…d tests

style: cargo fmt

Also replace f32 with Sample where appropriate for consistency

roderickvd requested review from dvdsk and Copilot 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 and others added 14 commits September 17, 2025 21:34

adds mic docs & example + fixes mic yielding zeros

a2fc272

ci: add silent MP3 file and test for decoder silence (#411)

5253ff2

fix: MP3 format probe to reject WAV files with minimp3

2bea71c

Without this, minimp3 would incorrectly accept WAV files as MP3 when both `minimp3` and Symphonia's `wav` features are enabled.

feat: add Decoder support for Bytes, Arc, Box, and Vec types

16c3673

Fixes #141

docs: add doc(cfg(...)) attributes for docsrs feature documentation

5e815ad

feat: add bits_per_sample method to Microphone source

81e23f6

refactor: use Decoder::try_from<Path> for file loading in examples an…

4187282

…d tests

refactor: address review comments

4f5dd27

refactor: move LoopedDecoder to its own module and refactor construction

e01f1a2

refactor: move ReadSeekSource into symphonia module

924fa29

fix: import Settings from decoder::builder in decoder modules

712b61a

roderickvd force-pushed the feat/dither branch from 5286b13 to 98ccef0 Compare September 17, 2025 19:54

roderickvd added 5 commits September 17, 2025 22:50

style: reorder imports and clean up formatting in decoder modules

46ebd9e

refactor: use SampleRate type throughout

5ecd76b

style: cargo fmt

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

ff2e421

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

9cf9e75

refactor: Velvet noise to use usize for density and positions

01714ce

Also replace f32 with Sample where appropriate for consistency

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

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

dvdsk assigned dvdsk and unassigned dvdsk Sep 20, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add audio dithering support #794

feat: add audio dithering support #794

Uh oh!

roderickvd commented Sep 12, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Sep 12, 2025

Uh oh!

Copilot AI Sep 12, 2025

Uh oh!

Uh oh!

dvdsk commented Sep 13, 2025

Parent branch

Uh oh!

Uh oh!

		// 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

Are you sure you want to change the base?

feat: add audio dithering support #794

Uh oh!

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!

dvdsk commented Sep 13, 2025

Parent branch

Uh oh!

Uh oh!

roderickvd commented Sep 12, 2025 •

edited

Loading