br41ndmg 0.1.0

A polyphase sinc audio resampler with offline and streaming APIs for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# 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

```toml
[dependencies]
br41ndmg = "0.1"
```

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

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

### Basic Usage

```rust
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

```rust
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)

```rust
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

```rust
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 Example

Resample a file, a file into a directory (auto-named `<stem>_<rate>Hz.wav`),
or a whole folder at once:

```bash
# single file -> explicit output path
cargo run --release --example resample_file -- input.flac output.wav 48000

# single file -> directory (auto-named)
cargo run --release --example resample_file -- input.flac out_dir/ 48000

# batch: every .wav/.flac in a folder -> out_dir/
cargo run --release --example resample_file -- test_subjects/ out_dir/ 48000
```

## Roadmap

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

## Documentation

- [docs/USAGE.md](docs/USAGE.md) - End-user guide and recipes
- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) - Scope and current capabilities
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Module map and current data flow
- [docs/DSP_NOTES.md](docs/DSP_NOTES.md) - Sinc and polyphase theory notes
- [docs/REALTIME.md](docs/REALTIME.md) - Real-time / callback guidance
- [docs/TEST_PLAN.md](docs/TEST_PLAN.md) - Testing strategy
- [docs/BENCHMARK_PLAN.md](docs/BENCHMARK_PLAN.md) - Benchmark coverage and next steps
- [docs/PERFORMANCE.md](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.

| Metric | Target |
|--------|--------|
| Aliasing suppression | < -100 dB |
| Passband ripple | < 0.1 dB |
| Stopband attenuation | > 100 dB |

## License

MIT