articles / / 6 min read
Sonarch: one import for audio in ML, with a Rust engine underneath
Why I built sonarch, an audio library that carries its own sample rate, matches librosa's numbers and loads files on every core.
Every audio ML project I've worked on starts the same way. Before any model gets trained, I spend an afternoon writing glue: soundfile or torchaudio to load the files, librosa to resample and compute mel spectrograms, pyloudnorm to normalize levels, a shell call to ffmpeg for the one format nothing else opens. Then the bugs show up in that glue, not in the model.
sonarch is my attempt to replace that afternoon with one import. Version 0.1.0 is out on PyPI. This post explains the problem it solves, the design choices behind it, how fast it is (including where it's slower), and what's next.
pip install sonarch
The bugs live in the glue
Audio libraries in Python are each good at their own job. The trouble is what happens between them.
Silent sample-rate mismatches. In librosa, audio is a NumPy array and the sample rate is a separate integer you carry around by hand. Pass the wrong one to a feature function and you get a spectrogram that looks plausible and is quietly wrong. Nothing raises. You find out weeks later when the model underperforms.
Hidden defaults. librosa.load(path) resamples to 22,050 Hz and downmixes to mono unless you tell it not to. That's a reasonable default for music analysis, and a surprising one for a speech model that expects 16 kHz.
Training/inference drift. The preprocessing in your training notebook and the preprocessing in your serving code are two copies of the same steps, written at different times. If they differ by one parameter, the model sees different features in production than it saw in training.
Slow data loading. Decoding thousands of FLAC or MP3 files one by one in Python keeps the GPU waiting.
A moving target. torchaudio is deprecating its loading functions in favour of torchcodec, so the "which library do I load audio with" question has a new answer again.
The design: metadata travels with the data
The core of sonarch is an Audio object. It holds the waveform as a PyTorch tensor, always shaped (channels, samples), together with its sample rate. Every operation reads and updates that metadata, so you never pass sr= around by hand.
import sonarch as sa
audio = sa.load("clip.flac")
audio.sample_rate # 44100
audio.channels # 2
audio.duration # 12.4 seconds
audio.loudness # -18.2 LUFS, computed on first access
audio = audio.resample(16_000).to_mono().to("cuda")
Because the object knows its own sample rate, mismatches fail loudly instead of producing wrong numbers:
a, b = sa.load("a.wav"), sa.load("b_48k.wav")
a + b # SampleRateMismatchError: 16000 Hz vs 48000 Hz
sa.mix(a, b.resample(16_000), align="pad") # explicit, pads the shorter clip
The same rule applies to saving. sa.save raises ClippingError instead of silently clipping samples that go above full scale. "Fail loudly" is one of the project's written design principles, and it's the one that saves the most debugging time.
The other principle I care about is wrap first, replace later. sonarch isn't trying to reinvent every DSP routine. Where an excellent tool exists, sonarch puts it behind the same API. Decoding falls back to FFmpeg (bundled through PyAV, so there's no system install), and features are designed to match librosa's numbers. Code gets rewritten only where it can be clearly faster or more correct.
Matching the numbers people already trust
A new audio library is only useful if switching to it doesn't change your results. So sonarch's numerical operations are tested against the libraries people already use:
STFT,MelSpectrogram,LogMelandMFCCmatch librosa to float32 precision with the same arguments.trim_silencegives exactly the same result aslibrosa.effects.trim.- Resampling uses the same windowed-sinc filter design as
torchaudio.functional.resampleand matches it to float32 precision. - Loudness follows ITU-R BS.1770-4 and matches pyloudnorm.
- For lossless formats, the Rust decoder's output is bit-exact with FFmpeg.
A typical speech preprocessing chain looks like this:
audio = sa.load("speech.wav", sample_rate=16_000, mono=True)
audio = audio.loudness_normalize(-23).trim_silence(top_db=30).fix_length(10.0)
mel = sa.MelSpectrogram(n_mels=80, n_fft=400, hop_length=160)(audio) # (1, 80, frames)
mfcc = sa.MFCC(n_mfcc=13)(audio)
Features run on whatever device the audio lives on, so moving to the GPU is one .to("cuda") call. There are migration guides for librosa and torchaudio that map each call you already know to its sonarch equivalent and list the differences that matter, such as librosa's 22,050 Hz default.
Fast where it counts: the Rust engine
The hot paths run in a Rust extension built with PyO3 and maturin. It decodes WAV, AIFF, FLAC, MP3 and Ogg Vorbis with Symphonia, resamples on the CPU, and loads batches of files in parallel with Rayon. It releases Python's GIL while it works, so sa.load is safe to call from your own threads or from a PyTorch DataLoader. Other formats (AAC/M4A, Opus, audio tracks from video) go through FFmpeg, and both engines return the same samples.
Prebuilt wheels include the Rust engine and the FFmpeg libraries, so users don't need Rust or FFmpeg installed.
Loading a whole dataset is one call:
clips = sa.load_many(paths, sample_rate=16_000, mono=True) # decode, downmix, resample, on every core
Here are the numbers, measured on an 8-core Apple Silicon laptop with Python 3.12. Decoding a single 60-second stereo 48 kHz file, in milliseconds (lower is better):
| Format | sonarch | soundfile | librosa |
|---|---|---|---|
| WAV | 8.5 | 10.8 | 10.8 |
| FLAC | 47.3 | 56.4 | 56.9 |
| MP3 | 41.5 | 33.9 | 35.0 |
| Opus | 102.8 | 347.6 | 308.6 |
Resampling the same clip to 16 kHz takes 6.5 ms in sonarch, against 13.7 ms for librosa and 165.4 ms for torchaudio with the same filter. The batch case is where the Rust engine shows the biggest gain: loading, downmixing and resampling 300 five-second FLAC files takes 0.39 s with load_many, against 2.14 s for librosa one file at a time.
The fair comparison is librosa with 8 threads, which takes 0.44 s, so the honest headline is "as fast as a hand-written thread pool, without writing one." And MP3 is a loss: soundfile uses mpg123, a hand-optimized C decoder, and it's faster than sonarch's decoder. I'd rather publish that than hide it. Every number above can be reproduced with the scripts in benchmarks/.
What's next
0.1 is the "Core" milestone: loading, saving, resampling, levels, trimming and spectral features. The roadmap is built around the rest of the glue problem:
- v0.2, ML-ready: a
Pipelinethat saves to YAML, so you ship the exact preprocessing with your model and the drift problem goes away. It also brings batched GPU execution with padding and masks, plus presets such assa.preset("whisper")matched to Hugging Face's feature extractors. - v0.3, codecs: one
Codecinterface over EnCodec, DAC, Mimi and SNAC for audio tokenization. - v0.4, data: pack large folders into compressed FLAC or Opus shards and stream them.
- v0.5, augmentation and metrics: seedable augmentations, plus PESQ, STOI and SI-SDR to measure what compression costs before you train on it.
Each later milestone is a design target, not a promise. The README marks every section as available, in progress or planned, so it's always clear which code you can use today.
Try it
pip install sonarch
sonarch is alpha, so the API may still change before 1.0. That's also why feedback matters most right now. If you work with audio in Python, I'd like to know where your own glue code breaks, which formats or features you need, and whether the benchmarks hold on your hardware. Issues and PRs are welcome on GitHub.