br41ndmg

A Rust audio resampling library with a polyphase sinc engine, offline and streaming APIs, WAV/FLAC input, and a stereo SSE2 fast path.

Overview

br41ndmg resamples f32 audio with a precomputed polyphase sinc filter bank. The library exposes both offline and streaming APIs, reads WAV and FLAC files, writes WAV, and uses the same filter math in chunked and full-buffer processing — so streaming output is bit-for-bit identical to the offline path.

Current Features

• f32 sample buffers for offline and streaming resampling
• f32 and f64 DSP helper APIs for sinc, window, and FIR kernel generation
• Offline resampling for mono and interleaved multichannel buffers
• Streaming resampling for interleaved audio
• Polyphase sinc filtering with precomputed fractional phases
• Configurable polyphase filter phase count, tap count, and window
• WAV input: 8/16/24/32-bit PCM and 32-bit float
• FLAC input: 4–32-bit samples (default flac feature, pure-Rust decoder)
• WAV output: 32-bit float
• SSE2 stereo fast path on x86 and x86_64
• Streaming output is bit-exact with the offline path regardless of input chunking
• DSP validation tests for impulse, sine, sweep, DC, and alias-suppression regressions
• Real-audio integration tests driven by test_subjects/ FLAC fixtures
• Criterion benchmarks for mono and stereo 44.1 kHz → 48 kHz conversion

Quick Start

Installation

[dependencies]
br41ndmg = "0.1"

The default features include FLAC support. To build a leaner, WAV-only crate:

[dependencies]
br41ndmg = { version = "0.1", default-features = false }

Basic Usage

use br41ndmg::Resampler;

let input_rate = 44_100.0f32;
let output_rate = 48_000.0f32;
let resampler = Resampler::new(input_rate, output_rate)?;

let input_samples: Vec<f32> = /* your audio data */;
let output_samples = resampler.resample(&input_samples)?;

Custom Filter Settings

use br41ndmg::{PolyphaseFilterParams, Resampler, Window};

let params = PolyphaseFilterParams {
    phases: 512,
    taps_per_phase: 95,
    window: Window::Blackman,
};
let resampler = Resampler::with_filter_params(44_100.0, 48_000.0, params)?;

File I/O (WAV and FLAC)

use br41ndmg::io::{read_audio, write_wav};

// .wav or .flac — the decoder is selected from the extension
let input = read_audio("input.flac")?;
let output = input.resample_to(48_000)?;
write_wav("output.wav", &output)?;

Real-Time Streaming

use br41ndmg::StreamingResampler;

let mut stream = StreamingResampler::new(44_100.0f32, 48_000.0f32, 2)?;
let input_frames = 256;
let input_chunk = vec![0.0f32; input_frames * 2];
let mut output = vec![0.0; stream.output_samples_for(input_frames)];

let written_frames = stream.process_into(&input_chunk, &mut output)?;
let ready = &output[..written_frames * stream.channels()];

Command-Line Tool

The CLI lives in a separate package but installs a binary still named br41ndmg:

cargo install br41ndmg-cli

Run with no arguments (or a directory, or -i/--interactive) to open the interactive file browser, or pass three positional arguments for the non-interactive path:

# interactive browser, starts in the current directory
br41ndmg

# interactive browser, starting in a given folder
br41ndmg test_subjects/

# force interactive mode explicitly
br41ndmg -i

# non-interactive: single file -> explicit output path
br41ndmg input.flac output.wav 48000

# non-interactive: single file -> directory (auto-named <stem>_<rate>Hz.wav)
br41ndmg input.flac out_dir/ 48000

# non-interactive: batch every .wav/.flac in a folder -> out_dir/
br41ndmg test_subjects/ out_dir/ 48000

In the browser, navigate with arrow keys (or j/k), Enter/Space to open or toggle files, a to select all, c to clear, and p to proceed. On the settings screen pick a target rate from common presets (or type a custom one) and choose the output directory by typing or browsing for it, then start.

From a source checkout, use cargo run --release --bin br41ndmg -- <args> in place of br41ndmg.

Roadmap

• Core math primitives (sinc, windows, FIR kernels)
• Polyphase sinc implementation
• File I/O integration (WAV + FLAC)
• Real-time streaming support
• SIMD optimization for stereo interleaved paths
• f32 DSP helper support
• DSP quality validation suite expansion
• Configurable polyphase filter parameters
• Bit-exact streaming/offline equivalence
• Expanded performance baselines and profiling data

Documentation

• docs/USAGE.md - End-user guide and recipes
• docs/REQUIREMENTS.md - Scope and current capabilities
• docs/ARCHITECTURE.md - Module map and current data flow
• docs/DSP_NOTES.md - Sinc and polyphase theory notes
• docs/REALTIME.md - Real-time / callback guidance
• docs/TEST_PLAN.md - Testing strategy
• docs/BENCHMARK_PLAN.md - Benchmark coverage and next steps
• docs/PERFORMANCE.md - Current performance notes

API documentation is generated with cargo doc --open.

Long-Term Targets

These are project goals, not hard guarantees from the current default filter settings.

License

MIT