🎵 sound_rs

sound_rs is a fast, Rust-powered audio library for Python that I built and maintain — decoding with symphonia (plus minimp3 for MP3), resampling with rubato, output through cpal.

Documentation: neksand.github.io/sound_rs — guides, API reference, the soundrs command and the benchmark methodology.

🚀 Features

• Formats: WAV, MP3, FLAC, OGG/Vorbis, M4A, AAC — any bit depth, including 24-bit
• Streaming playback: a two-hour file costs ~4 MB of RAM, not gigabytes, and the first sound arrives in ~9 ms instead of after the whole decode
• Player: one output stream stays open — play, pause, resume, seek, stop, volume, position, duration
• Decode to NumPy: load(path) -> (ndarray, sample_rate), shape (frames, channels)
• Parallel decode: load_many(paths) uses every core, with the GIL released
• Gapless (MP3, OGG, AAC/MP4): encoder delay and padding are trimmed, so decoded audio lines up with the original
• Fast metadata: get_audio_info reads the container header, ~1 ms regardless of file length
• Resampling: rubato's FFT resampler with a proper anti-aliasing filter
• Device-native output: the stream opens in whatever sample format the device wants (f32, f64, i16, i32, u8, u16)
• Errors: everything raises sound_rs.SoundRsError (a RuntimeError subclass)
• No ffmpeg, no system libraries: MP3, FLAC, OGG, AAC and WAV are decoded inside the wheel; pip install sound_rs needs nothing else
• Typed: ships sound_rs.pyi and py.typed, so editors autocomplete everything

🧠 Installation

pip install sound_rs

Wheels are built for Linux (x86_64), Windows (amd64) and macOS (arm64) for Python 3.10–3.14. Other platforms build from source.

⌨️ Command line

Installing the package also installs soundrs, so you can check the setup and read the docs without opening Python:

soundrs --help       # commands and the documentation link
soundrs devices      # output devices, default marked with *
soundrs info a.flac  # rate, channels, duration from the header
soundrs play a.flac --volume 0.5
soundrs docs         # prints https://neksand.github.io/sound_rs/

Exit codes: 0 success, 1 runtime failure, 2 bad usage.

💻 Usage

One-shot playback

import sound_rs

sound_rs.play_audio("sound.wav")          # blocks, GIL released
sound_rs.play_audio("sound.mp3", device="MacBook Pro Speakers")

The player

import sound_rs

with sound_rs.Player() as player:
    player.play_file("music.flac")   # returns immediately, streams from disk
    player.volume = 0.7
    player.seek(42.0)
    player.pause()
    player.resume()
    print(player.position, player.duration)
    player.wait()                    # block until it ends

sound_rs.list_devices()              # [(0, "MacBook Pro Speakers", True), ...]

Inspect and decode

sample_rate, channels, duration = sound_rs.get_audio_info("music.mp3")  # no decode
audio, rate = sound_rs.load("music.flac")                               # (frames, channels) float32

pairs = sound_rs.load_many(["a.flac", "b.flac", "c.flac"])              # parallel

From a NumPy array

import numpy as np

rate = 44100
t = np.linspace(0, 2.0, rate * 2, endpoint=False, dtype=np.float32)
sound_rs.play_array(np.sin(2 * np.pi * 440 * t), rate)   # mono, 1D
sound_rs.play_array(np.stack([left, right]), rate)       # 2D, channels first
sound_rs.play_sine_wave(440.0, 1.0, 44100)

🧩 Benchmark

Every measurement runs in its own process: peak RSS is process-wide, so timing and memory cannot share one. Median and p95 over repeated runs, competitors run side by side on the same files.

python bench/run.py                 # sound_rs only
python bench/run.py --compare       # + soundfile / sounddevice
python bench/run.py --reps 9

Hardware I measured on: Apple M5 Pro, macOS 26.6.2, Python 3.14.7, release build (lto = "fat", opt-level = 3). Competitors: libsndfile 1.2 (soundfile 0.14), PortAudio (sounddevice). Corpus: 3 s and 10 min stereo 44.1 kHz, generated by the harness.

Scoreboard — every axis in this section, side by side:

Import time (cold process):

Metadata (60 s file): sound_rs 1.2 ms, soundfile 31.7 ms.

Decode 60 s stereo, median / p95:

Streaming a 10-minute FLAC — time to the first sound and peak memory:

Playback of a 3 s tone — overhead over the track duration:

Batch decode two FLAC files: load_many 272 ms vs a soundfile loop 448 ms.

What the numbers do not hide:

• MP3 output is offset by 47 samples (~1 ms) versus libsndfile and ffmpeg. Sample values agree to 1.6e-05 once aligned; the offset comes from how the decoder delay is trimmed, and the length matches exactly.
• WAV decode is a memcpy race with libsndfile; the gap there is small by nature, the real wins are FLAC, metadata, memory and latency.
• AAC decoding is slower than everything else — it is a newer, less tuned decoder — but libsndfile cannot read AAC at all.

🛠️ Roadmap

🧪 Development

cargo test                      # resampler, channel conversion, gapless, seek
maturin develop --release       # build into your venv
python tests/smoke.py           # end-to-end decode + API checks
SOUND_RS_PLAY=1 python tests/smoke.py   # also plays (needs an audio device)
python bench/run.py --compare   # full benchmark
python3 docs/_build.py          # rebuild the documentation site

⚙️ Built With

• 🦀 Rust — performance and safety
• 🔗 PyO3 — Python bridge
• 🧰 Maturin — building and publishing
• 🔊 cpal, symphonia, minimp3, rubato — output, decoding, resampling

👨‍💻 Author

Nurassyl Mussainov Kazakhstan 🇰🇿 Python / Rust Developer

🔗 GitHub: Neksand 📦 PyPI: sound_rs

📜 License

Licensed under the MIT License — free for personal and commercial use.