🎵 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.

Latest release: 0.3.0 — reliability, datasets, recording, queues. Build report: docs/reports/0.3.0-report.md.

🚀 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 ~11 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, sample_rate=, mono=, offset=, duration=) — resample to 16 kHz mono in one call, or decode only a window
• Parallel decode: load_many(paths, sample_rate=, mono=) uses every core, GIL released
• Recording: Recorder() captures from the microphone to a float32 array
• Queues and live input: Player.enqueue(path) chains tracks; begin_feed/feed push samples from Python with backpressure
• 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 with a stable .code (io, format, device, stalled, unsupported, usage)
• Tested guarantees: no panics on corrupt input (mutation fuzzing), deterministic decode (PCM hashes in CI), underrun reporting. The full list is on the docs site.
• 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 with the stable ABI (abi3-py310): one per platform — Linux x86_64 and aarch64, Windows amd64, macOS arm64 and Intel — each covering Python 3.10 and newer. 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), ...]

Record

import sound_rs

with sound_rs.Recorder() as recorder:
    audio, rate = recorder.record(5.0)     # float32, (frames, channels)

Queue and live input

import numpy as np
import sound_rs

with sound_rs.Player() as player:
    player.play_file("a.flac")
    player.enqueue("b.mp3")                # plays next, own rate and layout
    player.wait()

player = sound_rs.Player()
player.begin_feed(48000)
player.feed(np.zeros(4800, dtype=np.float32))   # blocks when the buffer is full
player.end_feed()
player.wait()

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
audio, rate = sound_rs.load("music.flac", sample_rate=16000, mono=True) # dataset shape

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                      # decode, gapless, seek, fuzzing, properties, player
cargo clippy --all-targets -- -D warnings
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 tests/decode_regression.py  # PCM hashes; must not change
python docs/check_api.py        # every public name is documented
python bench/run.py --compare --report bench/REPORT.md
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.