fast-audio-resampler

Fast streaming audio resampling for Rust, focused on x86/x86_64, AArch64 ARM, and RISC-V CPUs.

The crate exposes a reusable library by default. WAV CLI support is optional and gated behind the cli feature so library users do not pull hound.

Usage

use fast_audio_resampler::{FirBackend, Quality, Resampler, ResamplerConfig};

let config = ResamplerConfig {
    input_rate: 44_100,
    output_rate: 48_000,
    channels: 2,
    quality: Quality::Balanced,
    backend: FirBackend::Auto,
    max_input_frames_per_chunk: None,
};

let mut resampler = Resampler::<f32>::new(config)?;
let mut output = Vec::new();
resampler.process(&input_samples, &mut output)?;
resampler.finish(&mut output)?;
# Ok::<(), Box<dyn std::error::Error>>(())

CLI:

cargo run --features cli -- --in input.wav --out output.wav --rate 48000

Python bindings are available through PyO3 for Python 3.9+:

maturin develop --features python-extension

from fast_audio_resampler import F32Resampler

resampler = F32Resampler(44_100, 48_000, 2, quality="balanced", backend="auto")
output, stats = resampler.process(input_samples)
tail, tail_stats = resampler.finish()
output.extend(tail)

Benchmarks

Criterion benchmark results from cargo bench --bench resampler. Each one-shot case processes one second of input audio. Times are medians; lower is better.

Exact-ratio special conversions use compact engines where available:

• Exact 8k <-> 16k at Quality::Fast: polyphase IIR all-pass path.
• Exact 8k <-> 16k at Quality::Balanced and Quality::Best: FIR half-band path.
• Exact 24k -> 8k: sparse FIR third-band path.
• Other ratios: windowed-sinc polyphase FIR path.

x86_64

Quality::Fast IIR results on x86_64:

Quality::Balanced FIR half-band results on x86_64:

General-ratio Quality::Balanced FIR results on x86_64:

AArch64 ARM

AArch64 ARM benchmarks should be regenerated with the current IIR/FIR split. The crate includes NEON FIR kernels and an IIR stereo NEON backend path, both selected where supported.

Design Choices

• Uses windowed-sinc polyphase FIR resampling for arbitrary sample-rate ratios.
• Uses FIR half-band filtering for exact 8000 <-> 16000 at Quality::Balanced and Quality::Best.
• Uses sparse FIR third-band filtering for exact 24000 -> 8000.
• Uses a polyphase IIR all-pass path for exact 8000 <-> 16000 at Quality::Fast.
• Supports f32 and i16 sample paths.
• Uses runtime CPU feature detection instead of CPU vendor checks.
• Uses AVX2/FMA, AVX-512, and AArch64 NEON intrinsics for FIR f32 where available.
• Uses RISC-V RVV 1.0 FIR kernels on riscv64 builds compiled with -C target-feature=+v.
• Uses a Q15 fixed-point i16 path with AVX2 _mm256_madd_epi16, AArch64 NEON widening multiply, or RISC-V RVV widening multiply-accumulate on supported CPUs.
• Keeps FIR backend naming explicit with FirBackend and SelectedFirBackend; deprecated Backend aliases remain for compatibility.
• Keeps IIR backend selection separate from FIR backend selection. IIR currently has scalar, x86 SSE2, AArch64 NEON, and RVV-gated stereo all-pass kernels, with conservative auto-selection based on benchmark behavior.
• Keeps RISC-V RVV selection compile-time gated because stable Rust does not yet provide portable runtime detection for the vector extension.
• Stores FIR coefficients in phase-major aligned storage for cache-friendly reads.
• Uses per-channel ring buffers and IIR state for streaming history, avoiding steady-state buffer shifting.
• Keeps the public API stable while hiding FIR backend and buffer details internally.

Complexity

Let:

• N = input frames processed
• M = output frames produced
• C = channel count
• T = FIR tap count selected by Quality
• S = fixed IIR all-pass stage count for the exact-ratio fast path

Construction:

• Time: O(P * T), where P is the number of polyphase coefficient phases.
• Space: O(P * T + C * T) for FIR coefficient tables and per-channel history.
• Exact 8k <-> 16k Quality::Fast IIR construction uses fixed coefficient/state storage per channel instead of a phase table.
• Exact 24k -> 8k construction uses a compact sparse third-band coefficient table instead of a full phase table.

Processing:

• FIR time: O(M * C * T) scalar work.
• IIR exact-ratio fast time: O(M * C * S), where S is small and fixed.
• Exact 24k -> 8k sparse FIR time: O(M * C * T_sparse), where zero-valued third-band taps are omitted.
• FIR SIMD reduces the constant factor by processing multiple taps per instruction.
• IIR stereo backends can process left/right all-pass lanes together where the target architecture supports it.
• Streaming append is O(N * C).
• Ring-buffer history discard is O(C) and does not move sample data.

Output size:

• Approximately ceil(N * output_rate / input_rate) frames after finish.

Features

• Default: library only, no WAV dependency.
• cli: enables the WAV command-line tool and the optional hound dependency.
• python: enables testable PyO3 bindings with the Python 3.9 stable ABI.
• python-extension: enables python plus PyO3 extension-module linking for Python package builds.